Pokédex MCP Server

Instructions

Implementation Reference

• src/tools.ts:72-86 (handler)

  The handler function that implements the core logic of the search_pokemon tool: fetches a large list of Pokémon, filters by partial name match on the query, limits to top 20 results, and returns formatted search results or handles errors.

  async ({ query }) => {
    try {
      // Get a larger list to search through
      const pokemonList = await pokeAPI.getPokemonList(1500);
      const matches = pokemonList.results
        .filter((p) =>
          p.name.toLowerCase().includes(query.toLowerCase().trim()),
        )
        .slice(0, 20); // Limit to 20 results
  
      return formatPokemonSearchResults(query, matches);
    } catch (error) {
      return formatCaughtError(error, "searching Pokémon");
    }
  },

• src/tools.ts:71-71 (schema)

  Input schema using Zod validation for the 'query' parameter, requiring a non-empty string.

  { query: z.string().min(1).describe("Partial name to search for") },

• src/tools.ts:68-87 (registration)

  Registration of the search_pokemon tool with the MCP server, including name, description, schema, and handler.

  server.tool(
    "search_pokemon",
    "Search for Pokémon by partial name match",
    { query: z.string().min(1).describe("Partial name to search for") },
    async ({ query }) => {
      try {
        // Get a larger list to search through
        const pokemonList = await pokeAPI.getPokemonList(1500);
        const matches = pokemonList.results
          .filter((p) =>
            p.name.toLowerCase().includes(query.toLowerCase().trim()),
          )
          .slice(0, 20); // Limit to 20 results
  
        return formatPokemonSearchResults(query, matches);
      } catch (error) {
        return formatCaughtError(error, "searching Pokémon");
      }
    },
  );

• src/formatters.ts:159-189 (helper)

  Helper function that formats the search results (query and matching Pokémon list) into a user-friendly MCP text response, including numbered list with IDs and usage instructions.

  export function formatPokemonSearchResults(
    query: string,
    matches: Array<{ name: string; url: string }>
  ): MCPResponse {
    if (matches.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No Pokémon found matching "${query}". Try a different search term.`,
          },
        ],
      };
    }
  
    const resultText = matches
      .map((p, index) => {
        const id = p.url.split("/").filter(Boolean).pop();
        return `${index + 1}. ${p.name} (ID: ${id})`;
      })
      .join("\n");
  
    return {
      content: [
        {
          type: "text",
          text: `**Search results for "${query}":**\n\n${resultText}\n\n*Use fetch_pokemon with any of these names to get detailed information.*`,
        },
      ],
    };
  }