poe2-mcp-server

Instructions

Implementation Reference

• src/tools/currency.ts:46-89 (handler)

  The main handler function that executes the poe2_currency_prices tool logic - fetches currency data from poe.ninja API, calculates chaos-equivalent values, sorts by value, and formats the output as a markdown list with trade volumes.

  async ({ league }) => {
    try {
      const data = await getNinjaExchangeOverview(league, 'Currency');
  
      // 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;
  
      const lines: string[] = [`## Currency Prices — ${league}`, ''];
  
      // Sort by chaos value descending
      const sorted = [...data.lines].sort((a, b) => {
        const chaosA = a.primaryValue * chaosRate;
        const chaosB = b.primaryValue * chaosRate;
        return chaosB - chaosA;
      });
  
      for (const line of sorted) {
        const name = displayName(line.id, coreNames);
        const chaosValue = (line.primaryValue * chaosRate).toFixed(2);
        const volume = line.volumePrimaryValue ?? 0;
        lines.push(`- **${name}**: ${chaosValue} chaos (volume: ${volume})`);
      }
  
      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 fetching currency prices for league "${league}": ${msg}\n\nAvailable PoE2 leagues: "Fate of the Vaal", "Standard". League names are case-sensitive.`,
          },
        ],
      };
    }
  },

• src/tools/currency.ts:19-90 (registration)

  Tool registration that defines the poe2_currency_prices tool with its title, description, input schema, annotations, and handler function.

    server.registerTool(
      'poe2_currency_prices',
      {
        title: 'PoE2 Currency Prices',
        description: `Get current currency exchange rates for Path of Exile 2 from poe.ninja.
  
  Returns prices of all currencies with chaos-equivalent values computed from exchange rates.
  Data refreshes approximately every hour on poe.ninja.
  
  Args:
    - league (string): League name (default: "Fate of the Vaal")
  
  Returns: List of currencies with their exchange values and trade volumes.
  
  Examples:
    - "How much is an Exalted Orb worth?" → call with default league
    - "Currency prices in Standard" → call with league="Standard"`,
        inputSchema: {
          league: LeagueSchema,
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async ({ league }) => {
        try {
          const data = await getNinjaExchangeOverview(league, 'Currency');
  
          // 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;
  
          const lines: string[] = [`## Currency Prices — ${league}`, ''];
  
          // Sort by chaos value descending
          const sorted = [...data.lines].sort((a, b) => {
            const chaosA = a.primaryValue * chaosRate;
            const chaosB = b.primaryValue * chaosRate;
            return chaosB - chaosA;
          });
  
          for (const line of sorted) {
            const name = displayName(line.id, coreNames);
            const chaosValue = (line.primaryValue * chaosRate).toFixed(2);
            const volume = line.volumePrimaryValue ?? 0;
            lines.push(`- **${name}**: ${chaosValue} chaos (volume: ${volume})`);
          }
  
          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 fetching currency prices for league "${league}": ${msg}\n\nAvailable PoE2 leagues: "Fate of the Vaal", "Standard". League names are case-sensitive.`,
              },
            ],
          };
        }
      },
    );

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

  Zod schema defining the input validation for the league parameter, which is used as the inputSchema for poe2_currency_prices.

  const LeagueSchema = z
    .string()
    .default(DEFAULT_LEAGUE)
    .describe('PoE2 league name, e.g. "Fate of the Vaal" or "Standard"');
  
  /** Title-case a slug id for display (e.g. "alch" → "Alch"). */
  function displayName(id: string, coreNames: Map<string, string>): string {
    return coreNames.get(id) ?? id.charAt(0).toUpperCase() + id.slice(1);
  }
  
  export function registerCurrencyTools(server: McpServer): void {
    // ── poe2_currency_prices ──────────────────────────────────────────
    server.registerTool(
      'poe2_currency_prices',
      {
        title: 'PoE2 Currency Prices',
        description: `Get current currency exchange rates for Path of Exile 2 from poe.ninja.
  
  Returns prices of all currencies with chaos-equivalent values computed from exchange rates.
  Data refreshes approximately every hour on poe.ninja.
  
  Args:
    - league (string): League name (default: "Fate of the Vaal")
  
  Returns: List of currencies with their exchange values and trade volumes.
  
  Examples:
    - "How much is an Exalted Orb worth?" → call with default league
    - "Currency prices in Standard" → call with league="Standard"`,
        inputSchema: {
          league: LeagueSchema,
        },

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

  Helper function that fetches PoE2 exchange data from poe.ninja API with rate limiting - used by poe2_currency_prices handler to retrieve currency price data.

  /**
   * Fetch PoE2 exchange overview from poe.ninja.
   * @param league — Full league display name, e.g. "Fate of the Vaal"
   * @param type — Exchange category, e.g. "Currency", "Fragments", "Essences"
   */
  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);
  }