{"_id":"@cybeleri/mcp-test-kit","name":"@cybeleri/mcp-test-kit","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cybeleri/mcp-test-kit","publishConfig":{"access":"public"},"version":"1.0.0","description":"CLI testing framework for MCP (Model Context Protocol) servers - validate, benchmark, and security-check your MCP implementations","main":"dist/index.js","bin":{"mcp-test":"dist/cli.js"},"scripts":{"build":"tsc","test":"jest","test:coverage":"jest --coverage","lint":"eslint src --ext .ts","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","testing","cli","ai","llm","claude","anthropic","validation","security"],"author":{"name":"cybeleri"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cybeleri/mcp-test-kit.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","chalk":"^4.1.2","commander":"^11.1.0","ora":"^5.4.1","table":"^6.8.1","yaml":"^2.3.4"},"devDependencies":{"@types/jest":"^29.5.11","@types/node":"^20.10.6","jest":"^29.7.0","ts-jest":"^29.1.1","typescript":"^5.3.3"},"engines":{"node":">=18.0.0"},"_id":"@cybeleri/mcp-test-kit@1.0.0","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/cybeleri/mcp-test-kit/issues"},"homepage":"https://github.com/cybeleri/mcp-test-kit#readme","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-C36PoPf1AcxoJifyhbetSeJ6BZb6Cpu2EqA5QNX+uokjCtrRbIruqaamDy+rWc9YTXBR1w2XmZJzxiUC3dPpvQ==","shasum":"a5480d10739dbeaad2f467aa9acbc3e5b3680774","tarball":"https://registry.npmjs.org/@cybeleri/mcp-test-kit/-/mcp-test-kit-1.0.0.tgz","fileCount":31,"unpackedSize":115166,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDxuecLRW0flsiiUXnxCHx3NpQqihy3647tS2KX6amc9QIhAJw98es10Oq5jXBPm4kOgsC5GqkbuECh+sDLKoaHaJLV"}]},"_npmUser":{"name":"cybeleri","email":"cybeleri@gmail.com"},"directories":{},"maintainers":[{"name":"cybeleri","email":"cybeleri@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-test-kit_1.0.0_1766859321429_0.5689993621796132"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-27T18:15:21.365Z","1.0.0":"2025-12-27T18:15:21.668Z","modified":"2025-12-27T18:15:22.277Z"},"maintainers":[{"name":"cybeleri","email":"cybeleri@gmail.com"}],"description":"CLI testing framework for MCP (Model Context Protocol) servers - validate, benchmark, and security-check your MCP implementations","homepage":"https://github.com/cybeleri/mcp-test-kit#readme","keywords":["mcp","model-context-protocol","testing","cli","ai","llm","claude","anthropic","validation","security"],"repository":{"type":"git","url":"git+https://github.com/cybeleri/mcp-test-kit.git"},"author":{"name":"cybeleri"},"bugs":{"url":"https://github.com/cybeleri/mcp-test-kit/issues"},"license":"MIT","readme":"# MCP Test Kit\n\n> CLI testing framework for MCP (Model Context Protocol) servers - validate, benchmark, and security-check your MCP implementations\n\n[![npm version](https://badge.fury.io/js/mcp-test-kit.svg)](https://www.npmjs.com/package/mcp-test-kit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Why MCP Test Kit?\n\nThe MCP ecosystem is growing rapidly, but **88% of MCP servers have security gaps** (Source: Astrix Security). MCP Test Kit helps you:\n\n- **Validate** your MCP server works correctly before deployment\n- **Discover** tools, resources, and prompts exposed by your server\n- **Security audit** for common vulnerabilities and misconfigurations\n- **Benchmark** connection and tool execution performance\n- **CI/CD integration** with JSON output for automated testing\n\n## Installation\n\n```bash\n# Global installation\nnpm install -g mcp-test-kit\n\n# Or use npx\nnpx mcp-test-kit test \"node ./my-server.js\"\n```\n\n## Quick Start\n\n```bash\n# Run all tests on an MCP server\nmcp-test test \"node ./dist/server.js\"\n\n# Quick connection check\nmcp-test quick \"npx @modelcontextprotocol/server-filesystem .\"\n\n# List available tools\nmcp-test list \"python server.py\"\n\n# Security assessment\nmcp-test security \"node ./my-server.js\" --verbose\n```\n\n## Commands\n\n### `mcp-test test <server>`\n\nRun full test suite on an MCP server.\n\n```bash\nmcp-test test \"node server.js\" [options]\n\nOptions:\n  -a, --args <args...>    Arguments to pass to server\n  -e, --env <vars...>     Environment variables (KEY=VALUE)\n  -t, --timeout <ms>      Connection timeout (default: 10000)\n  -v, --verbose           Enable verbose output\n  --connection-only       Only run connection tests\n  --protocol-only         Only run protocol tests\n  --tools-only            Only run tool validation\n  --security-only         Only run security checks\n  -f, --format <type>     Output: console, json, markdown\n```\n\n**Example:**\n\n```bash\n# Test with environment variables\nmcp-test test \"node server.js\" -e \"API_KEY=xxx\" -e \"DEBUG=true\"\n\n# Output as JSON for CI\nmcp-test test \"node server.js\" -f json > results.json\n\n# Run only security checks\nmcp-test test \"node server.js\" --security-only\n```\n\n### `mcp-test quick <server>`\n\nQuick connection check - verify server is reachable.\n\n```bash\nmcp-test quick \"node server.js\"\n```\n\nOutput:\n\n```\n✅ Server is reachable\n   Name: my-mcp-server\n   Version: 1.0.0\n   Protocol: 2024-11-05\n```\n\n### `mcp-test list <server>`\n\nList all tools exposed by the server.\n\n```bash\nmcp-test list \"node server.js\"\n\n# Output as JSON\nmcp-test list \"node server.js\" --json\n```\n\n### `mcp-test security <server>`\n\nRun security assessment and get a score.\n\n```bash\nmcp-test security \"node server.js\" --verbose\n```\n\nOutput:\n\n```\nSecurity Assessment Results\n══════════════════════════════════════════════════\n\nScore: [████████████████████░░░░░░░░░░░░░░░░░░░] 80%\n\n🚨 Critical Issues (0):\n\n⚠️  High Severity (1):\n   • Tool \"execute_query\" input patterns: Properties may need validation\n     → Add pattern restrictions, enums, or length limits\n\n✅ Passed Checks (5):\n   • Tool \"get_weather\" naming\n   • Tool \"search_docs\" naming\n   ...\n```\n\n## Programmatic Usage\n\n```typescript\nimport { MCPTestRunner, formatReport } from 'mcp-test-kit';\n\nconst runner = new MCPTestRunner({\n  server: 'node ./dist/server.js',\n  timeout: 10000\n}, {\n  connection: true,\n  protocol: true,\n  tools: true,\n  security: true\n});\n\nconst report = await runner.run();\n\nconsole.log(formatReport(report, 'console'));\n\n// Access individual results\nfor (const suite of report.suites) {\n  console.log(`${suite.name}: ${suite.summary.passed}/${suite.summary.total} passed`);\n}\n```\n\n## What Gets Tested\n\n### Connection Tests\n- Server startup and initialization\n- MCP protocol handshake\n- Server info (name, version, protocol version)\n\n### Protocol Compliance\n- Ping response (optional)\n- Tools list endpoint\n- Resources list endpoint\n- Prompts list endpoint\n\n### Tool Validation\n- Tool schema completeness\n- Required fields validation\n- Input schema JSON Schema compliance\n- Error handling for invalid arguments\n\n### Security Checks\n- Dangerous naming patterns (exec, shell, sql, file access)\n- Input validation presence\n- Attack surface assessment (tool count)\n- Error information leakage\n- Protocol version currency\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: MCP Server Tests\n\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n\n      - run: npm install\n      - run: npm run build\n\n      - name: Test MCP Server\n        run: npx mcp-test-kit test \"node ./dist/server.js\" -f json > results.json\n\n      - name: Check Results\n        run: |\n          if grep -q '\"overallStatus\": \"fail\"' results.json; then\n            echo \"MCP tests failed!\"\n            cat results.json\n            exit 1\n          fi\n```\n\n## Security Scoring\n\n| Score | Rating | Description |\n|-------|--------|-------------|\n| 80-100% | ✅ PASS | Server follows security best practices |\n| 50-79% | ⚠️ WARN | Some security concerns need attention |\n| 0-49% | ❌ FAIL | Critical security issues detected |\n\n### What We Check\n\n1. **Tool Naming** - Flags dangerous patterns like `exec`, `shell`, `sql`, `eval`\n2. **Input Schemas** - Ensures tools have proper input validation\n3. **Attack Surface** - Warns if too many tools increase risk\n4. **Error Handling** - Checks for information leakage in errors\n5. **Protocol Version** - Ensures server uses current MCP protocol\n\n## Contributing\n\nContributions welcome! Please read our contributing guidelines first.\n\n```bash\n# Clone and install\ngit clone https://github.com/cybeleri/mcp-test-kit\ncd mcp-test-kit\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n```\n\n## License\n\nMIT © [cybeleri](https://github.com/cybeleri)\n\n---\n\n**Built for the MCP community** - Help make MCP servers safer and more reliable.\n","readmeFilename":"README.md","_rev":"1-10bf888dee320acfab5629aa22fa2e5e"}