recommend-mcp-servers

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');
  };