poe2-mcp-server

Instructions

Implementation Reference

• src/tools/items.ts:148-207 (handler)

  Main implementation of poe2_exchange_top tool handler. Contains the tool registration, input schema (type, limit, league), and async handler function that fetches data from poe.ninja and returns the top N most valuable items in a given exchange category sorted by chaos-equivalent value.

    // ── poe2_exchange_top ─────────────────────────────────────────────
    server.registerTool(
      'poe2_exchange_top',
      {
        title: 'PoE2 Top Exchange Items',
        description: `Get the most valuable items in a given exchange category in Path of Exile 2.
  
  Args:
    - type (string): Exchange category — Currency, Fragments, Essences, SoulCores, Idols, Runes, etc.
    - limit (number): How many to return (default: 10, max: 30)
    - league (string): League name (default: "Fate of the Vaal")
  
  Returns: Top N most valuable items sorted by chaos-equivalent value.`,
        inputSchema: {
          type: z.enum(EXCHANGE_TYPES).describe('Exchange category'),
          limit: z.number().int().min(1).max(30).default(10).describe('Number of results'),
          league: z.string().default(DEFAULT_LEAGUE),
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async ({ type, limit, league }) => {
        try {
          const data = await getNinjaExchangeOverview(league, type);
  
          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 sorted = [...data.lines].sort((a, b) => b.primaryValue - a.primaryValue);
          const top = sorted.slice(0, limit);
  
          const lines: string[] = [`## Top ${limit} ${type} — ${league}`, ''];
          for (let i = 0; i < top.length; i++) {
            const item = top[i]!;
            const name = displayName(item.id, coreNames);
            const chaosValue = (item.primaryValue * chaosRate).toFixed(1);
            const volume = item.volumePrimaryValue ?? 0;
            lines.push(`${i + 1}. **${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: ${msg}` }],
          };
        }
      },
    );

• src/tools/items.ts:161-165 (schema)

  Input validation schema for poe2_exchange_top using zod: type (enum of EXCHANGE_TYPES), limit (int, 1-30, default 10), league (string, default 'Fate of the Vaal').

  inputSchema: {
    type: z.enum(EXCHANGE_TYPES).describe('Exchange category'),
    limit: z.number().int().min(1).max(30).default(10).describe('Number of results'),
    league: z.string().default(DEFAULT_LEAGUE),
  },

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

  Helper function getNinjaExchangeOverview that fetches PoE2 exchange overview data from poe.ninja API with rate limiting. Returns NinjaExchangeResponse with core item data and pricing lines.

  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/services/api.ts:73-76 (schema)

  Type definition NinjaExchangeResponse defining the structure of API responses from poe.ninja exchange overview endpoint, used by poe2_exchange_top handler.

  export interface NinjaExchangeResponse {
    core: NinjaExchangeCore;
    lines: NinjaExchangeLine[];
  }

• src/tools/items.ts:7-21 (schema)

  EXCHANGE_TYPES constant array defining valid exchange categories (Currency, Fragments, Abyss, UncutGems, etc.) used for input validation in poe2_exchange_top schema.

  const EXCHANGE_TYPES = [
    'Currency',
    'Fragments',
    'Abyss',
    'UncutGems',
    'LineageSupportGems',
    'Essences',
    'SoulCores',
    'Idols',
    'Runes',
    'Ritual',
    'Expedition',
    'Delirium',
    'Breach',
  ] as const;