poe2-mcp-server

Instructions

Implementation Reference

• src/tools/wiki.ts:132-219 (handler)

  The main handler implementation for 'poe2_db_lookup' tool. It registers the tool with its schema, description, and handler function that fetches data from poe2db.tw, strips HTML, and returns formatted text output.

    server.registerTool(
      'poe2_db_lookup',
      {
        title: 'PoE2 Database Lookup',
        description: `Look up detailed game data from poe2db.tw — items, gems, mods, passives.
  
  poe2db.tw contains datamined information directly from game files, including exact stat values, gem scaling, mod tiers, and more.
  
  Also useful for finding Russian translations of game terms: use lang="ru" to get Russian page.
  
  IMPORTANT: Skills, passives, and ascendancy nodes with ranks use Roman numerals in poe2db, not Arabic.
  Convert rank numbers: 1→I, 2→II, 3→III, 4→IV, 5→V.
  Always include the rank suffix if the user mentions a specific rank.
  
  Args:
    - term (string): English name of an item, gem, mod, etc. Use underscores for spaces, e.g. "Essence_Drain", "Chaos_Bolt". For ranked skills/passives, append Roman numeral: "Urgent_Totems_II", "War_Cry_III".
    - lang ("us" | "fr"): Language — "us" for English (default), "fr" for French, etc.
  
  Returns: Raw page content from poe2db (HTML stripped to text, truncated at 6000 chars).
  
  Examples:
    - Gem details: term="Essence_Drain"
    - Passive rank 2: term="Urgent_Totems_II" (NOT "Urgent_Totems_2" or "Urgent_Totems")
    - Ascendancy node rank 3: term="War_Cry_III"
    - Russian name: term="Chaos_Bolt", lang="ru"
    - Unique item: term="Atziri's_Rule"`,
        inputSchema: {
          term: z
            .string()
            .min(1)
            .describe(
              'Search term with underscores for spaces. Use Roman numerals for ranks, e.g. "Urgent_Totems_II", "Essence_Drain"',
            ),
          lang: z.enum(['us', 'ru']).default('us').describe('Language: us=English, ru=Russian'),
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async ({ term, lang }) => {
        try {
          const html = await getPoe2dbPage(term, lang);
  
          // Strip HTML to get meaningful text
          let text = html
            .replace(/<script[\s\S]*?<\/script>/gi, '')
            .replace(/<style[\s\S]*?<\/style>/gi, '')
            .replace(/<nav[\s\S]*?<\/nav>/gi, '')
            .replace(/<footer[\s\S]*?<\/footer>/gi, '')
            .replace(/<header[\s\S]*?<\/header>/gi, '')
            .replace(/<[^>]+>/g, ' ')
            .replace(/ /g, ' ')
            .replace(/&/g, '&')
            .replace(/</g, '<')
            .replace(/>/g, '>')
            .replace(/\s+/g, ' ')
            .trim();
  
          if (text.length > 6000) {
            text = text.slice(0, 6000) + '\n\n... [truncated]';
          }
  
          const url = `https://poe2db.tw/${lang}/${term.replace(/\s+/g, '_')}`;
          return {
            content: [
              {
                type: 'text',
                text: `## poe2db: ${term} (${lang})\n🔗 ${url}\n\n${text}`,
              },
            ],
          };
        } catch (error) {
          const msg = error instanceof Error ? error.message : String(error);
          return {
            isError: true,
            content: [
              {
                type: 'text',
                text: `Error looking up "${term}" on poe2db: ${msg}\n\nTips:\n- Use English names with underscores, e.g. "Essence_Drain", "Orb_of_Augmentation"\n- For ranked skills/passives, use Roman numerals: "Urgent_Totems_II", not "Urgent_Totems_2"\n- Always include the rank suffix (I, II, III, etc.) if looking up a specific rank`,
              },
            ],
          };
        }
      },
    );

• src/tools/wiki.ts:158-166 (schema)

  Input schema definition for 'poe2_db_lookup' tool using zod validation. Defines 'term' as a required string with underscores for spaces, and 'lang' as an enum ('us' | 'ru') defaulting to 'us'.

  inputSchema: {
    term: z
      .string()
      .min(1)
      .describe(
        'Search term with underscores for spaces. Use Roman numerals for ranks, e.g. "Urgent_Totems_II", "Essence_Drain"',
      ),
    lang: z.enum(['us', 'ru']).default('us').describe('Language: us=English, ru=Russian'),
  },

• src/services/api.ts:154-171 (helper)

  Helper function that fetches HTML page from poe2db.tw for a given term and language. Includes automatic normalization of trailing Arabic numerals to Roman numerals with retry logic.

  export async function getPoe2dbPage(term: string, lang: 'us' | 'ru' = 'us'): Promise<string> {
    const slug = term.replace(/\s+/g, '_');
    const normalizedSlug = normalizeTrailingArabicToRoman(slug);
    const headers = { 'User-Agent': USER_AGENT, Accept: 'text/html' };
  
    const res = await fetch(`https://poe2db.tw/${lang}/${normalizedSlug}`, {
      headers,
    });
  
    if (res.ok) return res.text();
  
    if (res.status === 404 && normalizedSlug !== slug) {
      const retry = await fetch(`https://poe2db.tw/${lang}/${slug}`, { headers });
      if (retry.ok) return retry.text();
    }
  
    throw new Error(`poe2db returned ${res.status} for "${term}"`);
  }

• src/services/api.ts:142-147 (helper)

  Helper function that converts trailing Arabic numerals to Roman numerals (e.g., 'Urgent_Totems_2' → 'Urgent_Totems_II') to match poe2db.tw naming conventions.

  export function normalizeTrailingArabicToRoman(slug: string): string {
    const match = /^(.+_)(\d+)$/.exec(slug);
    if (!match) return slug;
    const roman = ARABIC_TO_ROMAN[match[2]!];
    return roman ? match[1]! + roman : slug;
  }