poe2-mcp-server

Instructions

Implementation Reference

• src/tools/wiki.ts:32-68 (handler)

  Main handler function for poe2_wiki_search tool. Executes the wiki search by calling searchWiki API, formats results with titles/snippets/URLs, handles empty results and errors.

  async ({ query }) => {
    try {
      const results = await searchWiki(query);
      if (results.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No wiki articles found for "${query}". Try different keywords.`,
            },
          ],
        };
      }
  
      const lines: string[] = [`## Wiki Search: "${query}"`, ''];
      for (const r of results) {
        // Strip HTML tags from snippet
        const clean = r.snippet.replace(/<[^>]+>/g, '');
        lines.push(`### ${r.title}`);
        lines.push(`${clean}`);
        lines.push(
          `🔗 https://www.poe2wiki.net/wiki/${encodeURIComponent(r.title.replace(/ /g, '_'))}`,
        );
        lines.push('');
      }
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
      };
    } catch (error) {
      const msg = error instanceof Error ? error.message : String(error);
      return {
        isError: true,
        content: [{ type: 'text', text: `Wiki search error: ${msg}` }],
      };
    }
  },

• src/tools/wiki.ts:22-24 (schema)

  Input schema definition for poe2_wiki_search using zod. Defines the query parameter as a string with min 2 and max 200 characters.

  inputSchema: {
    query: z.string().min(2).max(200).describe('Search query for the wiki'),
  },

• src/tools/wiki.ts:7-69 (registration)

  Complete registration of poe2_wiki_search tool using server.registerTool(). Includes tool metadata, title, description, input schema, annotations, and the handler function.

    server.registerTool(
      'poe2_wiki_search',
      {
        title: 'PoE2 Wiki Search',
        description: `Search the Path of Exile 2 community wiki (poe2wiki.net) for game mechanics, items, skills, and other information.
  
  Args:
    - query (string): Search term — skill name, mechanic, item, monster, etc.
  
  Returns: Up to 5 matching wiki articles with titles and snippets.
  
  Examples:
    - "How does Contagion spread?" → query="Contagion"
    - "Energy Shield mechanics" → query="Energy Shield"
    - "Lich ascendancy" → query="Lich ascendancy"`,
        inputSchema: {
          query: z.string().min(2).max(200).describe('Search query for the wiki'),
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async ({ query }) => {
        try {
          const results = await searchWiki(query);
          if (results.length === 0) {
            return {
              content: [
                {
                  type: 'text',
                  text: `No wiki articles found for "${query}". Try different keywords.`,
                },
              ],
            };
          }
  
          const lines: string[] = [`## Wiki Search: "${query}"`, ''];
          for (const r of results) {
            // Strip HTML tags from snippet
            const clean = r.snippet.replace(/<[^>]+>/g, '');
            lines.push(`### ${r.title}`);
            lines.push(`${clean}`);
            lines.push(
              `🔗 https://www.poe2wiki.net/wiki/${encodeURIComponent(r.title.replace(/ /g, '_'))}`,
            );
            lines.push('');
          }
  
          return {
            content: [{ type: 'text', text: lines.join('\n') }],
          };
        } catch (error) {
          const msg = error instanceof Error ? error.message : String(error);
          return {
            isError: true,
            content: [{ type: 'text', text: `Wiki search error: ${msg}` }],
          };
        }
      },
    );

• src/services/api.ts:184-188 (helper)

  searchWiki helper function that performs the actual HTTP request to poe2wiki.net's MediaWiki API and returns the search results as WikiSearchResult[] array.

  export async function searchWiki(query: string): Promise<WikiSearchResult[]> {
    const url = `https://www.poe2wiki.net/w/api.php?action=query&list=search&srsearch=${encodeURIComponent(query)}&format=json&srlimit=5`;
    const data = await fetchJson<{ query?: { search?: WikiSearchResult[] } }>(url);
    return data.query?.search ?? [];
  }