MCP Compass

Instructions

Implementation Reference

• src/index.ts:123-145 (handler)

  Handler logic for executing the 'recommend-mcp-servers' tool: parses input, fetches recommendations from COMPASS API, handles empty results, formats output as markdown text.
  if (name === "recommend-mcp-servers") { const { query } = GeneralArgumentsSchema.parse(args); const servers = await makeCOMPASSRequest(query); if (!servers || servers.length === 0) { return { content: [{ type: "text", text: "No matching MCP servers found for your query. Try being more specific about the platform, operation, or service you need.", }], }; } const serversText = await toServersText(servers); return { content: [ { type: "text", text: serversText, }, ], };
• src/index.ts:36-72 (registration)

  Tool registration in the ListTools response, including name, detailed description, and input schema definition.
  { name: "recommend-mcp-servers", description: ` Use this tool when there is a need to findn external MCP tools. It explores and recommends existing MCP servers from the internet, based on the description of the MCP Server needed. It returns a list of MCP servers with their IDs, descriptions, GitHub URLs, and similarity scores. `, inputSchema: { type: "object", properties: { query: { type: "string", description: ` Description for the MCP Server needed. It should be specific and actionable, e.g.: GOOD: - 'MCP Server for AWS Lambda Python3.9 deployment' - 'MCP Server for United Airlines booking API' - 'MCP Server for Stripe refund webhook handling' BAD: - 'MCP Server for cloud' (too vague) - 'MCP Server for booking' (which booking system?) - 'MCP Server for payment' (which payment provider?) Query should explicitly specify: 1. Target platform/vendor (e.g. AWS, Stripe, MongoDB) 2. Exact operation/service (e.g. Lambda deployment, webhook handling) 3. Additional context if applicable (e.g. Python, refund events) `, }, }, required: ["query"], }, },
• src/index.ts:15-17 (schema)

  Zod schema for validating the tool's input arguments (query string). Used in handler for parsing.
  const GeneralArgumentsSchema = z.object({ query: z.string().min(1), });
• src/index.ts:84-98 (helper)

  Helper function to make API request to COMPASS for MCP server recommendations based on query.
  const makeCOMPASSRequest = async (query: string): Promise<MCPServerResponse[]> => { try { const response = await fetch(`${COMPASS_API_BASE}/recommend?description=${encodeURIComponent(query)}`); if (!response.ok) { throw new Error(`COMPASS API request failed with status ${response.status}`); } const data = await response.json(); return data as MCPServerResponse[]; } catch (error) { console.error('Error fetching from COMPASS API:', error); throw error; } };
• src/index.ts:100-116 (helper)

  Helper function to format the list of recommended MCP servers into a readable text string with titles, descriptions, URLs, and similarity scores.
  const toServersText = async (servers: MCPServerResponse[]): Promise<string> => { if (servers.length === 0) { return "No MCP servers found."; } return servers.map((server, index) => { const similarityPercentage = (server.similarity * 100).toFixed(1); return [ `Server ${index + 1}:`, `Title: ${server.title}`, `Description: ${server.description}`, `GitHub URL: ${server.github_url}`, `Similarity: ${similarityPercentage}%`, '' ].join('\n'); }).join('\n'); };