atom-mcp-server

Instructions

Implementation Reference

• src/tools/get-index-benchmarks.ts:32-122 (handler)

  The main handler function that executes the get_index_benchmarks tool logic. It filters index benchmarks by index_code and index_category, queries the database, and formats the response with benchmark data, summary statistics, and methodology information.

  export async function handleGetIndexBenchmarks(
    params: z.infer<z.ZodObject<typeof getIndexBenchmarksSchema>>,
    tier: Tier
  ) {
    // Index benchmarks are fully public — no tier gating
    const filters: string[] = [];
    if (params.index_code && params.index_code.trim() !== "")
      filters.push(`index_code=eq.${params.index_code.trim()}`);
    if (
      params.index_category &&
      params.index_category.trim() !== "" &&
      params.index_category !== "(any)"
    )
      filters.push(`index_category=ilike.*${params.index_category}*`);
  
    const rows = await queryTable<IndexValues>("index_values", filters, {
      order: "date.desc,index_code.asc",
      limit: params.limit,
    });
  
    if (rows.length === 0) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              tool: "get_index_benchmarks",
              error: params.index_code
                ? `No index found for '${params.index_code}'. Omit index_code to see all available indexes.`
                : "No index data available.",
            }),
          },
        ],
      };
    }
  
    // Extract unique index codes for summary
    const indexCodes = [...new Set(rows.map((r) => r.index_code))];
    const dates = [...new Set(rows.map((r) => r.date))].sort().reverse();
  
    // Group by date for structured output
    const byDate: Record<string, IndexValues[]> = {};
    for (const row of rows) {
      if (!byDate[row.date]) byDate[row.date] = [];
      byDate[row.date].push(row);
    }
  
    // Format each entry
    const formatted = rows.map((r) => ({
      index_code: r.index_code,
      index_category: r.index_category,
      description: r.index_description,
      date: r.date,
      unit: r.unit,
      input_price: r.input_price,
      cached_price: r.cached_price,
      output_price: r.output_price,
      sku_count: r.sku_count,
    }));
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              tool: "get_index_benchmarks",
              tier,
              description:
                "AIPI (ATOM Inference Price Index) — chained matched-model price benchmarks for AI inference.",
              summary: {
                total_indexes: indexCodes.length,
                indexes_available: indexCodes,
                date_range: {
                  latest: dates[0],
                  earliest: dates[dates.length - 1],
                  total_periods: dates.length,
                },
              },
              benchmarks: formatted,
              methodology:
                "Chained matched-model index. Only SKUs present in consecutive periods are compared, eliminating composition bias. See https://a7om.com/methodology",
              source: "https://a7om.com",
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/get-index-benchmarks.ts:10-30 (schema)

  Zod schema defining the input parameters for get_index_benchmarks tool: optional index_code filter, optional index_category filter, and limit parameter with default of 25.

  export const getIndexBenchmarksSchema = {
    index_code: z
      .string()
      .optional()
      .describe(
        "Filter by specific AIPI index code, e.g. 'AIPI TXT GLB', 'AIPI DEV GLB', 'AIPI OSS GLB'. Omit to see all indexes."
      ),
    index_category: z
      .string()
      .optional()
      .describe(
        "Filter by index category: 'Modality', 'Channel', 'Tier', 'Special'"
      ),
    limit: z
      .coerce.number()
      .int()
      .min(1)
      .max(100)
      .default(25)
      .describe("Maximum results to return (default 25)"),
  };

• src/server.ts:186-222 (registration)

  Tool registration where get_index_benchmarks is registered with the MCP server. Includes title, detailed description with examples, input schema composition, annotations (readOnly, idempotent), and the wrapper handler that resolves tier and calls handleGetIndexBenchmarks.

    server.registerTool(
      "get_index_benchmarks",
      {
        title: "Get AIPI Index Benchmarks",
        description: `AIPI (ATOM Inference Price Index) — chained matched-model price benchmarks for AI inference.
  
  Returns 14 benchmark indexes across four categories:
  - Modality (6): Text, Multimodal, Image, Audio, Video, Voice — what does this type of inference cost?
  - Channel (4): Model Developers, Cloud Marketplaces, Inference Platforms, Neoclouds — where should you buy?
  - Tier (3): Frontier, Budget, Reasoning — what's the premium for capability?
  - Special (1): Open-Source — how much cheaper is open-weight inference?
  
  Each index includes input, cached input, and output pricing per period.
  
  These are market-wide benchmarks, not individual vendor prices. Use them to understand where the market is and how it's moving.
  
  Fully public — available to all tiers.
  
  Examples:
    - "What's the current benchmark for text inference?" → index_category="Modality"
    - "Show me all AIPI indexes" → (no params)
    - "Neocloud pricing benchmark" → index_code="AIPI NCL GLB"
    - "Channel pricing comparison" → index_category="Channel"
    - "Open-source vs market pricing" → index_code="AIPI OSS GLB"`,
        inputSchema: { ...getIndexBenchmarksSchema, ...apiKeyField },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: false,
        },
      },
      async (params) => {
        const tier = await resolveTier(params._atom_api_key);
        return handleGetIndexBenchmarks(params, tier);
      }
    );