Poke-MCP

Instructions

Implementation Reference

• src/index.ts:237-297 (handler)

  Core handler function that fetches type-specific Pokémon list from PokeAPI, selects a random one, retrieves details, and formats the response with type, stats, abilities, and description.

  async function getRandomPokemonByType(type: string): Promise<PokemonResponse> {
    const normalizedType = type.toLowerCase();
  
    // Get all Pokémon of this type
    const typeData = await fetchFromPokeAPI<TypeData>(`/type/${normalizedType}`);
  
    if (!typeData || !typeData.pokemon || typeData.pokemon.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `Unknown type: ${type} or no Pokémon found of this type.`,
          },
        ],
      };
    }
  
    // Select a random Pokémon
    const randomPokemon = getRandomItem(typeData.pokemon);
  
    // Get detailed information about this Pokémon
    const details = await getPokemonDetails(randomPokemon.pokemon.name);
  
    if (!details) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to retrieve details for the selected ${normalizedType} Pokémon.`,
          },
        ],
      };
    }
  
    // Add type information to the response
    const types = formatPokemonTypes(details.pokemon.types);
    const abilities = formatPokemonAbilities(details.pokemon.abilities);
    const flavorText = getEnglishFlavorText(details.species);
  
    return {
      content: [
        {
          type: "text",
          text: `
  # Random ${capitalizeFirstLetter(
            normalizedType
          )} Pokémon: ${capitalizeFirstLetter(details.pokemon.name)} (#${
            details.pokemon.id
          })
  
  **Types:** ${types}
  **Height:** ${details.pokemon.height / 10}m
  **Weight:** ${details.pokemon.weight / 10}kg
  **Abilities:** ${abilities}
  
  **Description:** ${flavorText}
          `.trim(),
        },
      ],
    };
  }

• src/index.ts:340-351 (registration)

  Registers the 'random-pokemon-by-type' tool with MCP server, defining input schema and linking to the handler function.

  server.tool(
    "random-pokemon-by-type",
    "Get a random Pokémon of a specific type",
    {
      type: z
        .string()
        .describe("The Pokémon type (e.g., fire, water, grass, etc.)"),
    },
    async ({ type }, _extra) => {
      return await getRandomPokemonByType(type);
    }
  );

• src/index.ts:343-347 (schema)

  Zod input schema for the tool, validating the 'type' parameter as a string.

  {
    type: z
      .string()
      .describe("The Pokémon type (e.g., fire, water, grass, etc.)"),
  },

• src/types.ts:54-61 (schema)

  TypeScript interface defining the structure of PokeAPI type data response used in the handler.

  export interface TypeData {
    pokemon: {
      pokemon: {
        name: string;
        url: string;
      };
    }[];
  }

• src/index.ts:87-99 (helper)

  Helper function to fetch detailed Pokémon data including species information, used by the handler.

  async function getPokemonDetails(pokemonNameOrId: string) {
    const pokemon = await fetchFromPokeAPI<Pokemon>(
      `/pokemon/${pokemonNameOrId.toLowerCase()}`
    );
    if (!pokemon) return null;
  
    const species = await fetchFromPokeAPI<PokemonSpeciesDetails>(
      `/pokemon-species/${pokemon.id}`
    );
    if (!species) return null;
  
    return { pokemon, species };
  }