poe2-mcp-server

Instructions

Implementation Reference

• src/tools/currency.ts:121-187 (handler)

  Main handler function for poe2_currency_check tool. Fetches currency exchange data from poe.ninja API, performs case-insensitive partial name matching against currency IDs and names, calculates chaos-equivalent values, and returns formatted results with trade volumes.

  async ({ name, league }) => {
    try {
      const data = await getNinjaExchangeOverview(league, 'Currency');
      const query = name.toLowerCase();
  
      // Build lookup: id → human-readable name from core reference items
      const coreNames = new Map<string, string>();
      for (const item of data.core.items) {
        coreNames.set(item.id, item.name);
      }
  
      const chaosRate = data.core.rates[data.core.secondary] ?? 1;
  
      // Match against core item names and line ids
      const matches: Array<{
        id: string;
        name: string;
        chaosValue: number;
        volume: number;
      }> = [];
  
      for (const line of data.lines) {
        const itemName = coreNames.get(line.id);
        const matchesQuery =
          line.id.toLowerCase().includes(query) ||
          (itemName?.toLowerCase().includes(query) ?? false);
  
        if (matchesQuery) {
          matches.push({
            id: line.id,
            name: displayName(line.id, coreNames),
            chaosValue: line.primaryValue * chaosRate,
            volume: line.volumePrimaryValue ?? 0,
          });
        }
      }
  
      if (matches.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No currency found matching "${name}" in ${league}.\n\nTip: Try a shorter search term like "divine", "exalted", "chaos", etc.`,
            },
          ],
        };
      }
  
      const lines: string[] = [`## Currency: "${name}" — ${league}`, ''];
      for (const match of matches) {
        lines.push(`**${match.name}** (${match.id})`);
        lines.push(`- Chaos equivalent: ${match.chaosValue.toFixed(2)}`);
        lines.push(`- Trade volume: ${match.volume}`);
        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: `Error: ${msg}` }],
      };
    }
  },

• src/tools/currency.ts:93-120 (registration)

  Tool registration for poe2_currency_check, including title, description, input schema (name and league parameters), and annotations (readOnly, non-destructive, idempotent, openWorld hints).

    server.registerTool(
      'poe2_currency_check',
      {
        title: 'PoE2 Check Currency Value',
        description: `Look up the current value of a specific currency in Path of Exile 2.
  
  Searches by partial name match (case-insensitive) against currency ids and reference item names.
  
  Args:
    - name (string): Currency name or partial name, e.g. "exalted", "divine", "regal"
    - league (string): League name (default: "Fate of the Vaal")
  
  Returns: Matched currency with its chaos-equivalent value and trade volume.
  
  Examples:
    - "How much is a Divine Orb?" → name="divine"
    - "Price of Regal Orb" → name="regal"`,
        inputSchema: {
          name: z.string().min(2).describe('Currency name or partial match'),
          league: LeagueSchema,
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },

• src/tools/currency.ts:7-10 (schema)

  LeagueSchema definition using Zod validation with default league value 'Fate of the Vaal'.

  const LeagueSchema = z
    .string()
    .default(DEFAULT_LEAGUE)
    .describe('PoE2 league name, e.g. "Fate of the Vaal" or "Standard"');

• src/services/api.ts:105-111 (helper)

  API helper function getNinjaExchangeOverview that fetches PoE2 currency exchange data from poe.ninja with rate limiting support.

  export async function getNinjaExchangeOverview(
    league: string,
    type: string,
  ): Promise<NinjaExchangeResponse> {
    const url = `${NINJA_POE2_BASE}/exchange/current/overview?league=${encodeURIComponent(league)}&type=${encodeURIComponent(type)}`;
    return fetchJson<NinjaExchangeResponse>(url, ninjaLimiter);
  }

• src/tools/currency.ts:13-15 (helper)

  Helper function displayName that converts currency ID slugs to title-case format for display purposes.

  function displayName(id: string, coreNames: Map<string, string>): string {
    return coreNames.get(id) ?? id.charAt(0).toUpperCase() + id.slice(1);
  }