random-pokemon-by-type

Find a random Pokémon based on a specific type (e.g., fire, water, grass) using this tool. Ideal for discovering Pokémon by type for games, research, or entertainment.

Instructions

Get a random Pokémon of a specific type

Input Schema

TableJSON Schema

Name	Required	Description	Default
`type`	Yes	The Pokémon type (e.g., fire, water, grass, etc.)

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

Poke-MCP