{"_id":"@achieveai/mcp-discovery-tool","_rev":"2-faf0404f1821762bcf84d0f0579b76be","name":"@achieveai/mcp-discovery-tool","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.0":{"name":"@achieveai/mcp-discovery-tool","version":"1.1.0","keywords":["mcp","model-context-protocol","discovery","tools","capabilities","ai","llm"],"author":{"name":"Achieve.AI"},"license":"MIT","_id":"@achieveai/mcp-discovery-tool@1.1.0","maintainers":[{"name":"g_mcqdb","email":"gautam@mcqdb.com"}],"homepage":"https://github.com/achieveai/mcp-discovery-tool#readme","bugs":{"url":"https://github.com/achieveai/mcp-discovery-tool/issues"},"bin":{"mcp-discovery":"dist/index.js"},"dist":{"shasum":"f58a4cdea82c0bd3ed6b3e3acd724e49350817e3","tarball":"https://registry.npmjs.org/@achieveai/mcp-discovery-tool/-/mcp-discovery-tool-1.1.0.tgz","fileCount":36,"integrity":"sha512-byI38t2IJxQ8ZKtvlQd4WMKNJFmT8n7n8Z5R/Hs9ltRJ+kkI6kGjDW9EyasxI7L/5YzfSHcErb1IwqMbXq/EWw==","signatures":[{"sig":"MEQCIG/M1qLYsfTBB1PXRjUIcOW/MKm4pdnl87YjPqQz3JZxAiBQYxyfIxm2DVPEvhDwNcCu4isW1N9hOmfaPjwiRd9XHQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95717},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"6c99831f5d013af3c31727240720b6ae30d6dc6c","scripts":{"dev":"tsx src/index.ts","lint":"echo \"Linting coming soon\"","test":"echo \"Tests coming soon\"","build":"tsc","format":"echo \"Formatting coming soon\"","prepublishOnly":"npm run build"},"_npmUser":{"name":"g_mcqdb","email":"gautam@mcqdb.com"},"repository":{"url":"git+https://github.com/achieveai/mcp-discovery-tool.git","type":"git"},"_npmVersion":"11.5.2","description":"An MCP server that discovers and catalogs capabilities (tools, prompts, resources) of other MCP servers with intelligent detail level control to manage token usage","directories":{},"_nodeVersion":"22.17.1","dependencies":{"@modelcontextprotocol/sdk":"^1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/mcp-discovery-tool_1.1.0_1759615812108_0.006701726043755185","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@achieveai/mcp-discovery-tool","version":"1.1.1","description":"An MCP server that discovers and catalogs capabilities (tools, prompts, resources) of other MCP servers with intelligent detail level control to manage token usage","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"mcp-discovery":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","prepublishOnly":"npm run build","test":"echo \"Tests coming soon\"","lint":"echo \"Linting coming soon\"","format":"echo \"Formatting coming soon\""},"publishConfig":{"access":"public"},"keywords":["mcp","model-context-protocol","discovery","tools","capabilities","ai","llm"],"author":{"name":"Achieve.AI"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/achieveai/mcp-discovery-tool.git"},"homepage":"https://github.com/achieveai/mcp-discovery-tool#readme","bugs":{"url":"https://github.com/achieveai/mcp-discovery-tool/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4"},"devDependencies":{"@types/node":"^22.10.2","typescript":"^5.7.2","tsx":"^4.19.2"},"engines":{"node":">=18.0.0"},"_id":"@achieveai/mcp-discovery-tool@1.1.1","gitHead":"e51d4289b2ffb79c8f83ef075048b44dcb90d8d1","_nodeVersion":"22.17.1","_npmVersion":"11.5.2","dist":{"integrity":"sha512-pd6We2/y5Y2J2KOEgHCieoQ3VwBCPuUUgUdc0Wy7u2GCjlInF3zRGjqBPwN0FZpGfrE6Lg90PzFDww5U85v9Nw==","shasum":"aad3dacc916a88d98a0400c8cf9af8e15ba57c72","tarball":"https://registry.npmjs.org/@achieveai/mcp-discovery-tool/-/mcp-discovery-tool-1.1.1.tgz","fileCount":36,"unpackedSize":98466,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG9iIxef52cro7Y7BkuM9TrqKpeH5+P+l4LgXSIAVb2bAiEA3NS8MADtQd23TA3eSjF/F2yjq2KuxjZaUMj7tNlfypk="}]},"_npmUser":{"name":"g_mcqdb","email":"gautam@mcqdb.com"},"directories":{},"maintainers":[{"name":"g_mcqdb","email":"gautam@mcqdb.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-discovery-tool_1.1.1_1759616520031_0.6969335305013791"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-04T22:10:12.016Z","modified":"2025-10-04T22:22:00.406Z","1.1.0":"2025-10-04T22:10:12.306Z","1.1.1":"2025-10-04T22:22:00.208Z"},"bugs":{"url":"https://github.com/achieveai/mcp-discovery-tool/issues"},"author":{"name":"Achieve.AI"},"license":"MIT","homepage":"https://github.com/achieveai/mcp-discovery-tool#readme","keywords":["mcp","model-context-protocol","discovery","tools","capabilities","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/achieveai/mcp-discovery-tool.git"},"description":"An MCP server that discovers and catalogs capabilities (tools, prompts, resources) of other MCP servers with intelligent detail level control to manage token usage","maintainers":[{"name":"g_mcqdb","email":"gautam@mcqdb.com"}],"readme":"# MCP Discovery Tool\n\n**Programmatically discover and catalog the capabilities of Model Context Protocol (MCP) servers.**\n\nThe MCP Discovery Tool is itself an MCP server that exposes a powerful `discoverMCPCapabilities` tool. This tool can connect to any MCP-compliant server, interrogate it for its capabilities, and return comprehensive metadata including tools, prompts, resources, and detailed usage information.\n\n## 🌟 Features\n\n- 🔍 **Comprehensive Discovery**: Automatically discovers tools, prompts, and resources from any MCP server\n- 🚀 **Multi-Server Support**: Discover multiple servers in parallel for efficiency\n- 📊 **Enhanced Metadata**: Provides usage guidance, parameter details, and JSON schemas\n- 🛡️ **Robust Error Handling**: Gracefully handles failures with detailed error information\n- 🔧 **Flexible Configuration**: Support for config files, inline JSON, or direct server specs\n- 🌐 **Cross-Platform**: Works on Windows, macOS, and Linux\n- ⚡ **Multiple Server Types**: Supports Node.js (npx/node), Python, and custom executables\n- 🔒 **Type-Safe**: Built with TypeScript for full type safety\n\n## 📦 Installation\n\n```bash\nnpm install\nnpm run build\n```\n\n## 🚀 Quick Start\n\n### As an MCP Server\n\nAdd to your MCP client configuration (e.g., Claude Desktop, VS Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"discovery\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/mcp-discovery-tool/dist/index.js\"]\n    }\n  }\n}\n```\n\nOr use npx for direct execution:\n\n```json\n{\n  \"mcpServers\": {\n    \"discovery\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tsx\", \"path/to/mcp-discovery-tool/src/index.ts\"]\n    }\n  }\n}\n```\n\n## 📖 Usage\n\n### The `discoverMCPCapabilities` Tool\n\nOnce the MCP Discovery Tool is running as an MCP server, you can call its `discoverMCPCapabilities` tool to discover other servers.\n\n### Option 1: Discover from Configuration File\n\n**Configuration File** (`mcp-servers.json`):\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"]\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]\n    }\n  }\n}\n```\n\n**Tool Call**:\n```json\n{\n  \"name\": \"discoverMCPCapabilities\",\n  \"arguments\": {\n    \"configPath\": \"./mcp-servers.json\"\n  }\n}\n```\n\n### Option 2: Discover Single Server\n\n**Tool Call**:\n```json\n{\n  \"name\": \"discoverMCPCapabilities\",\n  \"arguments\": {\n    \"serverSpec\": {\n      \"name\": \"memory\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"]\n    }\n  }\n}\n```\n\n### Option 3: Discover with Inline JSON Configuration\n\n**Tool Call**:\n```json\n{\n  \"name\": \"discoverMCPCapabilities\",\n  \"arguments\": {\n    \"configJson\": \"{\\\"mcpServers\\\":{\\\"memory\\\":{\\\"command\\\":\\\"npx\\\",\\\"args\\\":[\\\"-y\\\",\\\"@modelcontextprotocol/server-memory\\\"]}}}\"\n  }\n}\n```\n\n### Option 4: Filtered Discovery\n\nDiscover only specific servers from a configuration:\n\n```json\n{\n  \"name\": \"discoverMCPCapabilities\",\n  \"arguments\": {\n    \"configPath\": \"./mcp-servers.json\",\n    \"servers\": [\"memory\"],\n    \"timeout\": 15000\n  }\n}\n```\n\n## 🔧 Tool Parameters\n\n### Configuration Sources (Choose ONE)\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `configPath` | string | Path to JSON configuration file containing MCP server definitions |\n| `configJson` | string | Inline JSON string with MCP server configuration |\n| `serverSpec` | object | Single server specification for quick discovery |\n\n### Discovery Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `servers` | string[] | - | Filter to specific server names from configuration |\n| `parallel` | boolean | true | Discover servers in parallel (false for sequential) |\n| `timeout` | number | 30000 | Timeout per server in milliseconds |\n| `includeResources` | boolean | true | Include resource details in output |\n| `includeSchema` | boolean | true | Include full JSON schemas for tools |\n\n## 📊 Output Format\n\nThe tool returns an array of `DiscoveryResult` objects, one per server:\n\n```json\n[\n  {\n    \"serverName\": \"memory\",\n    \"serverInfo\": {\n      \"name\": \"@modelcontextprotocol/server-memory\",\n      \"version\": \"1.0.0\",\n      \"protocolVersion\": \"2024-11-05\",\n      \"capabilities\": {\n        \"tools\": {}\n      }\n    },\n    \"tools\": [\n      {\n        \"name\": \"create_memory\",\n        \"description\": \"Create a new memory with text content\",\n        \"inputSchema\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"content\": {\n              \"type\": \"string\",\n              \"description\": \"Text content to remember\"\n            }\n          },\n          \"required\": [\"content\"]\n        },\n        \"whenToUse\": \"Use this tool when you need to create or write a new memory with text content\",\n        \"parameters\": [\n          {\n            \"name\": \"content\",\n            \"type\": \"string\",\n            \"description\": \"Text content to remember\",\n            \"required\": true\n          }\n        ],\n        \"requiredParameters\": [\"content\"]\n      }\n    ],\n    \"prompts\": [],\n    \"resources\": [],\n    \"discoveredAt\": \"2025-10-04T10:30:00.000Z\",\n    \"discoveryDuration\": 2543\n  }\n]\n```\n\n### DiscoveryResult Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `serverName` | string | Server name from specification |\n| `serverInfo` | object | Server metadata (name, version, protocol, capabilities) |\n| `tools` | array | Enhanced tool information with usage guidance |\n| `prompts` | array | Prompt information with arguments |\n| `resources` | array | Resource information with URIs and types |\n| `errors` | array | Errors encountered during discovery (if any) |\n| `discoveredAt` | string | ISO timestamp of discovery |\n| `discoveryDuration` | number | Discovery duration in milliseconds |\n\n### Enhanced Tool Information\n\nEach tool includes:\n- **name**: Tool identifier\n- **description**: What the tool does\n- **inputSchema**: Full JSON Schema for parameters\n- **whenToUse**: Usage guidance (automatically inferred)\n- **parameters**: Extracted parameter details\n- **requiredParameters**: List of required parameter names\n\n## 🔒 Server Configuration Format\n\n```json\n{\n  \"mcpServers\": {\n    \"server-name\": {\n      \"command\": \"npx | node | python | python3 | <custom>\",\n      \"args\": [\"array\", \"of\", \"arguments\"],\n      \"env\": {\n        \"OPTIONAL\": \"environment variables\"\n      },\n      \"cwd\": \"/optional/working/directory\"\n    }\n  }\n}\n```\n\n### Supported Server Types\n\n#### Node.js (via npx)\n```json\n{\n  \"memory\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"]\n  }\n}\n```\n\n#### Node.js (local script)\n```json\n{\n  \"custom\": {\n    \"command\": \"node\",\n    \"args\": [\"./dist/my-server.js\"]\n  }\n}\n```\n\n#### Python\n```json\n{\n  \"python-server\": {\n    \"command\": \"python\",\n    \"args\": [\"-m\", \"my_mcp_server\"]\n  }\n}\n```\n\n#### Custom with Environment Variables\n```json\n{\n  \"advanced\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"my-mcp-server\"],\n    \"env\": {\n      \"API_KEY\": \"secret\",\n      \"DEBUG\": \"true\"\n    },\n    \"cwd\": \"/path/to/working/dir\"\n  }\n}\n```\n\n## 🎯 Use Cases\n\n### 1. **MCP Server Registry/Index**\nBuild a searchable catalog of available MCP servers and their capabilities.\n\n### 2. **Automated Documentation**\nGenerate documentation for MCP servers by discovering their tools and capabilities.\n\n### 3. **AI Agent Tool Discovery**\nLet AI agents dynamically discover what tools are available before performing tasks.\n\n### 4. **Server Validation**\nValidate that MCP servers expose the expected tools and schemas.\n\n### 5. **Development & Debugging**\nQuickly inspect server capabilities during development.\n\n### 6. **Tool Composition**\nDiscover complementary tools across multiple servers for complex workflows.\n\n## 🛠️ Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Run in Development Mode\n\n```bash\nnpm run dev\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts                      # Main MCP server entry point\n├── types/\n│   ├── discovery.ts              # Type definitions\n│   └── index.ts                  # Type exports\n├── discovery/\n│   ├── orchestrator.ts           # Discovery orchestration\n│   ├── connection-manager.ts     # Server process management\n│   ├── mcp-client.ts            # MCP client wrapper\n│   └── metadata-aggregator.ts    # Metadata enhancement\n└── utils/\n    └── config-parser.ts          # Configuration parsing\n```\n\n## 🔍 How It Works\n\n1. **Parse Configuration**: Reads server specifications from file, JSON, or direct spec\n2. **Validate Specs**: Validates command safety and argument structure\n3. **Spawn Servers**: Starts each server process with appropriate command/args\n4. **Connect via Stdio**: Establishes MCP protocol connection over stdio\n5. **Initialize Protocol**: Performs MCP handshake to get server info\n6. **Discover Capabilities**: Calls `listTools()`, `listPrompts()`, `listResources()`\n7. **Enhance Metadata**: Adds usage guidance and extracts parameter details\n8. **Cleanup**: Gracefully disconnects and terminates server processes\n9. **Return Results**: Aggregates all discoveries into structured response\n\n## ⚠️ Error Handling\n\nThe tool handles errors gracefully:\n\n- **Connection Failures**: Returns error result for that server, continues with others\n- **Timeouts**: Configurable per-server timeout (default 30s)\n- **Partial Failures**: If one server fails, others still succeed\n- **Detailed Errors**: Error messages include type, message, and details\n\nExample error result:\n```json\n{\n  \"serverName\": \"problematic-server\",\n  \"serverInfo\": null,\n  \"tools\": [],\n  \"prompts\": [],\n  \"resources\": [],\n  \"errors\": [\n    {\n      \"type\": \"connection\",\n      \"message\": \"Failed to spawn process: command not found\",\n      \"details\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"@missing/package\"],\n        \"error\": \"ENOENT\"\n      }\n    }\n  ],\n  \"discoveredAt\": \"2025-10-04T10:30:00Z\",\n  \"discoveryDuration\": 5000\n}\n```\n\n## 🔐 Security Considerations\n\n### Command Validation\n- Commands are validated against an allowed list\n- Potentially dangerous arguments are detected\n- Full command logging for audit trails\n\n### Process Isolation\n- Each server runs in its own process\n- Configurable timeouts prevent hangs\n- Automatic cleanup on errors\n\n### Configuration Trust\n- User must explicitly provide configuration\n- No automatic execution of unknown code\n- Warning for non-standard commands\n\n## 🚦 Cross-Platform Support\n\nThe MCP Discovery Tool works seamlessly across **Windows, macOS, and Linux** with no platform-specific configuration required!\n\n### ✅ Key Compatibility Features\n\n- **Zero Platform-Specific Code**: Works identically on all platforms\n- **Smart Process Spawning**: Uses [`cross-spawn`](https://github.com/moxystudio/cross-spawn) (via MCP SDK) to handle platform differences automatically\n- **Cross-Platform Commands**: Use `\"npx\"` directly on all platforms—no need for `cmd /c` on Windows!\n- **Path Normalization**: Node.js automatically handles path separators\n- **Pure JavaScript**: No native dependencies or platform-specific binaries\n\n### 📋 Platform-Specific Notes\n\n#### Windows\n- ✅ `npx`, `node`, `python` commands work directly (no `cmd /c` wrapper needed)\n- ✅ Automatically handles `.cmd` and `.bat` files\n- ✅ Respects Windows environment variables (`APPDATA`, `LOCALAPPDATA`, etc.)\n\n#### macOS\n- ✅ Native Unix commands work out of the box\n- ✅ Uses standard PATH resolution\n- ✅ Full support for Python virtual environments\n\n#### Linux\n- ✅ All distributions supported (Ubuntu, Debian, Fedora, Arch, etc.)\n- ✅ Works in Docker containers\n- ✅ Compatible with WSL (Windows Subsystem for Linux)\n\n### 💡 Cross-Platform Configuration Tips\n\n**✅ DO**: Use commands available in PATH\n```json\n{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"]\n}\n```\n\n**✅ DO**: Use forward slashes or absolute paths\n```json\n{\n  \"command\": \"node\",\n  \"args\": [\"/home/user/server/index.js\"]\n}\n```\n\n**❌ DON'T**: Use platform-specific wrappers\n```json\n{\n  \"command\": \"cmd\",\n  \"args\": [\"/c\", \"npx\", \"...\"]  // ❌ Unnecessary on Windows!\n}\n```\n\n**❌ DON'T**: Use Windows-only paths in examples\n```json\n{\n  \"args\": [\"C:\\\\Program Files\\\\server\\\\index.js\"]  // ❌ Won't work on macOS/Linux\n}\n```\n\n### 🧪 Tested Platforms\n\n| Platform | Node.js Version | Status |\n|----------|----------------|--------|\n| Windows 10/11 | 18.x, 20.x, 22.x | ✅ Tested |\n| macOS 12+ | 18.x, 20.x, 22.x | ✅ Compatible |\n| Ubuntu 20.04+ | 18.x, 20.x, 22.x | ✅ Compatible |\n| Debian 11+ | 18.x, 20.x, 22.x | ✅ Compatible |\n| WSL 2 | 18.x, 20.x, 22.x | ✅ Compatible |\n\n## 📝 Examples\n\nSee the `examples/` directory for:\n- `mcp-servers-config.json` - Multi-server configuration\n- `single-server-example.json` - Single server discovery\n- `multi-server-example.json` - Parallel multi-server discovery\n- `filtered-discovery-example.json` - Filtered discovery\n\n## 🤝 Contributing\n\nContributions welcome! This tool is designed to be extensible:\n\n- Add new transport support (HTTP/SSE)\n- Enhance usage guidance generation\n- Improve error messages\n- Add caching mechanisms\n- Build visualization tools\n\n## 📄 License\n\nMIT\n\n## 🙏 Acknowledgments\n\nBuilt using:\n- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - Official MCP TypeScript SDK\n- TypeScript - Type-safe implementation\n- Node.js - Runtime environment\n\n---\n\n**Need help?** Check the examples or file an issue on GitHub.\n\n**Want to extend?** The modular architecture makes it easy to add features!\n","readmeFilename":"README.md"}