Poke-MCP

Instructions

Implementation Reference

• src/index.ts:360-435 (handler)

  Main execution logic for the 'pokemon-query' tool: parses natural language input, matches patterns for Pokémon ID, random, region, or type queries, delegates to helpers, or provides usage examples.

    async ({ query }, _extra) => {
      const normalizedQuery = query.toLowerCase();
  
      // Check for Pokémon number query
      const numberMatch =
        normalizedQuery.match(/pokemon\s+#?(\d+)/i) ||
        normalizedQuery.match(/what\s+is\s+pokemon\s+#?(\d+)/i);
      if (numberMatch) {
        const pokemonId = parseInt(numberMatch[1], 10);
        return await getPokemonById(pokemonId);
      }
  
      // Check for random Pokémon request
      if (
        normalizedQuery.includes("random pokemon") &&
        !normalizedQuery.includes("from") &&
        !normalizedQuery.includes("type")
      ) {
        return await getRandomPokemon();
      }
  
      // Check for random Pokémon from region
      const regionMatch = normalizedQuery.match(/random pokemon from (\w+)/i);
      if (regionMatch) {
        const region = regionMatch[1].toLowerCase();
        return await getRandomPokemonFromRegion(region);
      }
  
      // Check for random Pokémon by type
      const typeMatch =
        normalizedQuery.match(/random (\w+) pokemon/i) ||
        normalizedQuery.match(/random pokemon of type (\w+)/i);
      if (typeMatch) {
        const type = typeMatch[1].toLowerCase();
        // Check if the matched word is actually a type and not just any adjective
        const validTypes = [
          "normal",
          "fire",
          "water",
          "grass",
          "electric",
          "ice",
          "fighting",
          "poison",
          "ground",
          "flying",
          "psychic",
          "bug",
          "rock",
          "ghost",
          "dragon",
          "dark",
          "steel",
          "fairy",
        ];
        if (validTypes.includes(type)) {
          return await getRandomPokemonByType(type);
        }
      }
  
      // Default response for unrecognized queries
      return {
        content: [
          {
            type: "text",
            text: `
  I can help with Pokémon queries! Try asking:
  - "What is pokemon #25?"
  - "Give me a random Pokémon"
  - "Give me a random Pokémon from Kanto"
  - "Give me a random Fire Pokémon"
            `.trim(),
          },
        ],
      };
    }

• src/index.ts:357-359 (schema)

  Input schema defining the 'query' parameter as a string for natural language Pokémon questions.

  {
    query: z.string().describe("A natural language query about Pokémon"),
  },

• src/index.ts:354-436 (registration)

  Registers the 'pokemon-query' tool with the MCP server, including name, description, input schema, and handler reference.

  server.tool(
    "pokemon-query",
    "Answer natural language Pokémon queries",
    {
      query: z.string().describe("A natural language query about Pokémon"),
    },
    async ({ query }, _extra) => {
      const normalizedQuery = query.toLowerCase();
  
      // Check for Pokémon number query
      const numberMatch =
        normalizedQuery.match(/pokemon\s+#?(\d+)/i) ||
        normalizedQuery.match(/what\s+is\s+pokemon\s+#?(\d+)/i);
      if (numberMatch) {
        const pokemonId = parseInt(numberMatch[1], 10);
        return await getPokemonById(pokemonId);
      }
  
      // Check for random Pokémon request
      if (
        normalizedQuery.includes("random pokemon") &&
        !normalizedQuery.includes("from") &&
        !normalizedQuery.includes("type")
      ) {
        return await getRandomPokemon();
      }
  
      // Check for random Pokémon from region
      const regionMatch = normalizedQuery.match(/random pokemon from (\w+)/i);
      if (regionMatch) {
        const region = regionMatch[1].toLowerCase();
        return await getRandomPokemonFromRegion(region);
      }
  
      // Check for random Pokémon by type
      const typeMatch =
        normalizedQuery.match(/random (\w+) pokemon/i) ||
        normalizedQuery.match(/random pokemon of type (\w+)/i);
      if (typeMatch) {
        const type = typeMatch[1].toLowerCase();
        // Check if the matched word is actually a type and not just any adjective
        const validTypes = [
          "normal",
          "fire",
          "water",
          "grass",
          "electric",
          "ice",
          "fighting",
          "poison",
          "ground",
          "flying",
          "psychic",
          "bug",
          "rock",
          "ghost",
          "dragon",
          "dark",
          "steel",
          "fairy",
        ];
        if (validTypes.includes(type)) {
          return await getRandomPokemonByType(type);
        }
      }
  
      // Default response for unrecognized queries
      return {
        content: [
          {
            type: "text",
            text: `
  I can help with Pokémon queries! Try asking:
  - "What is pokemon #25?"
  - "Give me a random Pokémon"
  - "Give me a random Pokémon from Kanto"
  - "Give me a random Fire Pokémon"
            `.trim(),
          },
        ],
      };
    }
  );

• src/index.ts:300-315 (helper)

  Helper function called by pokemon-query handler to fetch and format details for a specific Pokémon by ID.

  async function getPokemonById(id: number): Promise<PokemonResponse> {
    const details = await getPokemonDetails(id.toString());
  
    if (!details) {
      return {
        content: [
          {
            type: "text",
            text: `No Pokémon found with ID #${id}.`,
          },
        ],
      };
    }
  
    return formatPokemonResponse(details.pokemon, details.species);
  }

• src/types.ts:64-70 (schema)

  Type definition for the output response format used by pokemon-query and its helpers.

  export interface PokemonResponse {
    content: {
      type: "text";
      text: string;
    }[];
  }