{"_id":"@anygpt/mcp-discovery-server","name":"@anygpt/mcp-discovery-server","dist-tags":{"latest":"0.3.2"},"versions":{"0.3.2":{"name":"@anygpt/mcp-discovery-server","version":"0.3.2","description":"MCP Discovery Server - PRIMARY interface for AI agents to discover and execute tools","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","bin":{"mcp-discovery-server":"dist/cli.js"},"exports":{"./package.json":"./package.json",".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"repository":{"type":"git","url":"git+https://github.com/genai-tools/anygpt.git","directory":"packages/mcp-discovery-server"},"keywords":["mcp","discovery","server","tools","ai","gateway","protocol"],"author":{"name":"AnyGPT Contributors"},"license":"MIT","bugs":{"url":"https://github.com/genai-tools/anygpt/issues"},"homepage":"https://github.com/genai-tools/anygpt#readme","publishConfig":{"access":"public"},"scripts":{"build:dts":"tsc --project tsconfig.lib.json"},"dependencies":{"@anygpt/config":"3.0.1","@anygpt/mcp-discovery":"0.3.2","@anygpt/mcp-logger":"0.3.0","@modelcontextprotocol/sdk":"1.20.0"},"gitHead":"694856d0f9aa5bafc05fbf934367a8add2fddb59","_id":"@anygpt/mcp-discovery-server@0.3.2","_nodeVersion":"24.10.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-4FgUSWeTc0TMujRAcKbwiv+2hR3bgplnrmLmrNOIelIVXG75dfyD5OgF3YOsqkxCuKeCkMoyYWbVUPxVJKr91w==","shasum":"d7bd9becfadd46f7948c33ae26163b2ae3db572a","tarball":"https://registry.npmjs.org/@anygpt/mcp-discovery-server/-/mcp-discovery-server-0.3.2.tgz","fileCount":10,"unpackedSize":253855,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCP+Hj4QQW0oKfxKZtvrSb77Fepko9dAzBteOCiSFTVNQIhAKJfhbOHtqZACYpKD37Uoa+IG6KnEzfWlMwjHWj28TbH"}]},"_npmUser":{"name":"theplenkov-npm","email":"petr.plenkov@gmail.com"},"directories":{},"maintainers":[{"name":"theplenkov-npm","email":"petr.plenkov@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-discovery-server_0.3.2_1761046525619_0.969024767235648"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-21T11:35:25.536Z","0.3.2":"2025-10-21T11:35:25.823Z","modified":"2025-10-21T11:35:26.130Z"},"maintainers":[{"name":"theplenkov-npm","email":"petr.plenkov@gmail.com"}],"description":"MCP Discovery Server - PRIMARY interface for AI agents to discover and execute tools","homepage":"https://github.com/genai-tools/anygpt#readme","keywords":["mcp","discovery","server","tools","ai","gateway","protocol"],"repository":{"type":"git","url":"git+https://github.com/genai-tools/anygpt.git","directory":"packages/mcp-discovery-server"},"author":{"name":"AnyGPT Contributors"},"bugs":{"url":"https://github.com/genai-tools/anygpt/issues"},"license":"MIT","readme":"# @anygpt/mcp-discovery-server\n\n> **⚠️ WORK IN PROGRESS**: This package is under active development. APIs and meta-tools may change significantly. Use at your own risk in production environments.\n\n**MCP Discovery Server** - PRIMARY interface for AI agents to discover and execute tools from 100+ MCP servers without loading everything into context.\n\n## Overview\n\nThis is an MCP protocol server that exposes the Discovery Engine via 5 meta-tools and comprehensive usage prompts, enabling AI agents to:\n\n- Discover available MCP servers\n- Search for tools using free-text queries\n- List tools from specific servers\n- Get detailed tool information on-demand\n- **Execute tools from any MCP server (gateway capability!)**\n- **Access comprehensive usage instructions via prompts**\n\n**Key Capability**: Reduces token consumption from 100,000+ tokens to ~600 tokens per message (99% reduction).\n\n## Installation\n\n```bash\nnpm install -g @anygpt/mcp-discovery-server\n```\n\nOr use directly with npx (no installation needed):\n\n```bash\nnpx -y @anygpt/mcp-discovery-server\n```\n\n## Zero-Configuration Setup\n\nAdd to your IDE's MCP configuration:\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"anygpt-discovery\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@anygpt/mcp-discovery-server\"]\n    }\n  }\n}\n```\n\n### Windsurf\n\nEdit `.windsurf/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"anygpt-discovery\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@anygpt/mcp-discovery-server\"]\n    }\n  }\n}\n```\n\n### VS Code / Cursor\n\nEdit `.vscode/mcp.json` or `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"anygpt-discovery\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@anygpt/mcp-discovery-server\"]\n    }\n  }\n}\n```\n\n## The 5 Meta-Tools\n\n### 1. list_mcp_servers\n\nList all available MCP servers.\n\n**Parameters**: None\n\n**Returns**: Array of server metadata\n\n**Example**:\n\n```typescript\n// AI agent calls\nlist_mcp_servers()\n\n// Returns\n{\n  \"servers\": [\n    {\n      \"name\": \"github\",\n      \"description\": \"GitHub API tools\",\n      \"toolCount\": 25,\n      \"enabledCount\": 25,\n      \"status\": \"connected\"\n    },\n    {\n      \"name\": \"filesystem\",\n      \"description\": \"File system operations\",\n      \"toolCount\": 15,\n      \"enabledCount\": 15,\n      \"status\": \"connected\"\n    }\n  ]\n}\n```\n\n### 2. search_tools\n\nSearch for tools using free-text query with relevance scoring.\n\n**Parameters**:\n\n- `query` (string, required): Search query\n- `server` (string, optional): Filter by server name\n- `limit` (number, optional): Maximum results (default: 10)\n\n**Returns**: Array of matching tools with relevance scores\n\n**Example**:\n\n```typescript\n// AI agent calls\nsearch_tools({\n  query: \"github issue\",\n  limit: 5\n})\n\n// Returns\n{\n  \"results\": [\n    {\n      \"server\": \"github\",\n      \"tool\": \"create_issue\",\n      \"summary\": \"Create a new GitHub issue\",\n      \"relevance\": 0.95,\n      \"tags\": [\"github\", \"issues\", \"create\"]\n    },\n    {\n      \"server\": \"github\",\n      \"tool\": \"update_issue\",\n      \"summary\": \"Update an existing GitHub issue\",\n      \"relevance\": 0.87,\n      \"tags\": [\"github\", \"issues\", \"update\"]\n    }\n  ]\n}\n```\n\n### 3. list_tools\n\nList all tools from a specific MCP server.\n\n**Parameters**:\n\n- `server` (string, required): Server name\n- `includeDisabled` (boolean, optional): Include disabled tools\n\n**Returns**: Array of tool summaries\n\n**Example**:\n\n```typescript\n// AI agent calls\nlist_tools({\n  server: \"github\"\n})\n\n// Returns\n{\n  \"tools\": [\n    {\n      \"server\": \"github\",\n      \"name\": \"create_issue\",\n      \"summary\": \"Create a new GitHub issue\",\n      \"enabled\": true,\n      \"tags\": [\"github\", \"issues\"]\n    },\n    // ... more tools\n  ]\n}\n```\n\n### 4. get_tool_details\n\nGet detailed information about a specific tool.\n\n**Parameters**:\n\n- `server` (string, required): Server name\n- `tool` (string, required): Tool name\n\n**Returns**: Full tool description with parameters\n\n**Example**:\n\n```typescript\n// AI agent calls\nget_tool_details({\n  server: \"github\",\n  tool: \"create_issue\"\n})\n\n// Returns\n{\n  \"tool\": {\n    \"server\": \"github\",\n    \"name\": \"create_issue\",\n    \"summary\": \"Create a new GitHub issue\",\n    \"description\": \"Creates a new issue in a GitHub repository...\",\n    \"enabled\": true,\n    \"tags\": [\"github\", \"issues\", \"create\"],\n    \"parameters\": [\n      {\n        \"name\": \"repo\",\n        \"type\": \"string\",\n        \"description\": \"Repository name (owner/repo)\",\n        \"required\": true\n      },\n      {\n        \"name\": \"title\",\n        \"type\": \"string\",\n        \"description\": \"Issue title\",\n        \"required\": true\n      },\n      {\n        \"name\": \"body\",\n        \"type\": \"string\",\n        \"description\": \"Issue body\",\n        \"required\": false\n      }\n    ]\n  }\n}\n```\n\n### 5. execute_tool (Gateway Capability!)\n\nExecute a tool from any MCP server through the discovery server.\n\n**Parameters**:\n\n- `server` (string, required): Server name\n- `tool` (string, required): Tool name\n- `arguments` (object, required): Tool arguments\n\n**Returns**: Execution result or error\n\n**Example**:\n\n```typescript\n// AI agent calls\nexecute_tool({\n  server: \"github\",\n  tool: \"create_issue\",\n  arguments: {\n    repo: \"owner/repo\",\n    title: \"Bug report\",\n    body: \"Description of the bug\"\n  }\n})\n\n// Returns\n{\n  \"success\": true,\n  \"result\": {\n    \"issue_number\": 123,\n    \"url\": \"https://github.com/owner/repo/issues/123\"\n  }\n}\n```\n\n## 📖 Usage Guide Prompt\n\nThe server exposes a comprehensive usage guide via MCP prompts that AI agents can access for detailed instructions.\n\n### Accessing the Guide\n\n**In Claude Desktop / Windsurf / Cursor:**\n- The prompt appears as \"MCP Discovery Server - Complete Usage Guide\"\n- AI agents can reference it to understand best practices\n- Contains extensive examples and workflow patterns\n\n### What's Included\n\nThe usage guide provides:\n\n1. **Critical Workflow Rules**\n   - Rule #1: Always use `search_tools` as primary discovery method\n   - Rule #2: `search_tools` is your fallback for unknown tools\n   - Rule #3: Be specific in search queries\n   - Rule #4: Use `list_mcp_servers` to understand capabilities\n   - Rule #5: Use `list_tools` only when you know the server\n\n2. **The 5 Meta-Tools Documentation**\n   - Detailed purpose, parameters, and return values\n   - When to use each tool\n   - Pro tips for effective usage\n\n3. **Best Practices**\n   - Discovery Pattern (Search → Details → Execute)\n   - Exploration Pattern (List → Inspect → Use)\n   - Error Recovery Pattern (Fail → Verify → Retry)\n\n4. **Common Scenarios**\n   - File operations examples\n   - GitHub operations examples\n   - Command execution examples\n   - \"What can you do?\" responses\n\n5. **Common Mistakes to Avoid**\n   - Don't assume tools don't exist - search first!\n   - Don't use `list_tools` as primary discovery\n   - Don't execute without getting details\n   - Don't give up if first search fails\n   - Don't use overly broad searches\n\n6. **Token Efficiency Guidelines**\n   - Understanding the 99%+ token savings\n   - How to maintain efficiency through smart searching\n\n### Key Principle: search_tools First\n\nThe guide emphasizes that AI agents should **ALWAYS** use `search_tools` as their primary discovery method:\n\n```\nUser: \"Read the package.json file\"\n\n❌ Bad: \"I don't have file system access\"\n✅ Good: search_tools({ query: \"read file\" })\n  → Finds: filesystem:read_file, file:read_file, etc.\n```\n\nThis ensures agents discover available tools instead of assuming limitations.\n\n## Agentic Discovery Workflow\n\nAI agents can autonomously discover and use tools:\n\n```\nUser: \"Read the README.md file and create a GitHub issue if there are any TODOs\"\n\nAI Agent:\n1. search_tools({ query: \"read file\" })\n   → Finds \"filesystem:read_file\"\n\n2. get_tool_details({ server: \"filesystem\", tool: \"read_file\" })\n   → Gets parameters\n\n3. execute_tool({\n     server: \"filesystem\",\n     tool: \"read_file\",\n     arguments: { path: \"README.md\" }\n   })\n   → Reads file content\n\n4. search_tools({ query: \"create github issue\" })\n   → Finds \"github:create_issue\"\n\n5. execute_tool({\n     server: \"github\",\n     tool: \"create_issue\",\n     arguments: { repo: \"owner/repo\", title: \"TODO\", body: \"...\" }\n   })\n   → Creates issue\n```\n\n**Token Usage**: ~1,000 tokens vs 500,000+ tokens (99.8% savings)\n\n## Features\n\n- **Zero Configuration**: Automatically discovers MCP servers\n- **Intelligent Search**: Free-text search with relevance scoring\n- **Gateway Capability**: Execute tools from any MCP server\n- **Caching**: TTL-based caching for performance\n- **Pattern Filtering**: Glob and regex patterns for tool filtering\n- **MCP Protocol**: Full MCP protocol compliance\n\n## Architecture\n\n```\nAI Agent (Claude Desktop, Windsurf, Cursor)\n    ↓ MCP Protocol (stdio)\nMCP Discovery Server (5 meta-tools)\n    ↓ Uses Discovery Engine\nDiscovery Engine (search, cache, filter)\n    ↓ Proxies to actual MCP servers\nActual MCP Servers (github, filesystem, etc)\n```\n\n## Token Savings\n\n| Scenario              | Without Discovery | With Discovery | Savings |\n| --------------------- | ----------------- | -------------- | ------- |\n| 10 servers, 150 tools | 100,000+ tokens   | 600 tokens     | 99.4%   |\n| Single tool execution | 100,000+ tokens   | 1,000 tokens   | 99.0%   |\n| Multi-tool workflow   | 500,000+ tokens   | 2,000 tokens   | 99.6%   |\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Start server locally\nnode dist/cli.js\n```\n\n## License\n\nMIT\n\n## Links\n\n- [GitHub Repository](https://github.com/genai-tools/anygpt)\n- [Documentation](https://github.com/genai-tools/anygpt/tree/main/packages/mcp-discovery-server)\n- [MCP Protocol](https://modelcontextprotocol.io)\n","readmeFilename":"README.md","_rev":"1-5b264507d54d9bf6493e91141f2d5e8b"}