Pokédex MCP Server

Instructions

Implementation Reference

• src/tools.ts:55-64 (handler)

  The asynchronous handler function for the get_pokemon_encounters MCP tool. It fetches the Pokémon data and encounters using pokeAPI.getPokemonWithEncounters and formats the response with formatPokemonEncounters, catching and formatting any errors.

  async ({ name }) => {
    try {
      const { pokemon, encounters } = await pokeAPI.getPokemonWithEncounters(
        name.toLowerCase().trim(),
      );
      return formatPokemonEncounters(pokemon, encounters);
    } catch (error) {
      return formatCaughtError(error, "fetching encounter information");
    }
  },

• src/tools.ts:51-65 (registration)

  Registers the get_pokemon_encounters tool with the MCP server, providing the tool name, description, input schema (name parameter), and the handler function.

  server.tool(
    "get_pokemon_encounters",
    "Get location encounter information for a Pokémon",
    { name: z.string().min(1).describe("The name or ID of the Pokémon") },
    async ({ name }) => {
      try {
        const { pokemon, encounters } = await pokeAPI.getPokemonWithEncounters(
          name.toLowerCase().trim(),
        );
        return formatPokemonEncounters(pokemon, encounters);
      } catch (error) {
        return formatCaughtError(error, "fetching encounter information");
      }
    },
  );

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

  Zod schema for the tool input, requiring a non-empty string for the Pokémon name or ID.

  { name: z.string().min(1).describe("The name or ID of the Pokémon") },

• src/client.ts:236-246 (helper)

  PokeAPIClient helper method that fetches both the Pokémon details and its location area encounters concurrently using Promise.all.

  async getPokemonWithEncounters(idOrName: string | number): Promise<{
    pokemon: Pokemon;
    encounters: LocationAreaEncounter[];
  }> {
    const [pokemon, encounters] = await Promise.all([
      this.getPokemon(idOrName),
      this.getPokemonEncounters(idOrName)
    ]);
  
    return { pokemon, encounters };
  }

• src/formatters.ts:108-154 (helper)

  Formatter helper that converts the Pokémon object and array of LocationAreaEncounter into a formatted MCPResponse text content, handling cases with no encounters and formatting location/version details.

  export function formatPokemonEncounters(
    pokemon: Pokemon,
    encounters: LocationAreaEncounter[]
  ): MCPResponse {
    if (encounters.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `**${pokemon.name}** has no recorded wild encounters. This Pokémon might be:
  - A starter Pokémon
  - Obtained through evolution
  - A legendary/mythical Pokémon
  - Only available through special events`,
          },
        ],
      };
    }
  
    const locationInfo = encounters
      .map((encounter) => {
        const locationName = encounter.location_area.name.replace("-", " ");
        const versions = encounter.version_details
          .map((vd) => {
            const encounterMethods = vd.encounter_details
              .map(
                (ed) =>
                  `${ed.method.name} (Lv.${ed.min_level}-${ed.max_level}, ${ed.chance}% chance)`,
              )
              .join(", ");
            return `${vd.version.name}: ${encounterMethods}`;
          })
          .join("\n  ");
  
        return `**${locationName}:**\n  ${versions}`;
      })
      .join("\n\n");
  
    return {
      content: [
        {
          type: "text",
          text: `**${pokemon.name} Encounter Locations:**\n\n${locationInfo}`,
        },
      ],
    };
  }