atom-mcp-server 1.1.0

package/src/server.ts

@@ -0,0 +1,278 @@
+// ============================================================
+// ATOM MCP Server — Tool Registration
+// ============================================================
+// Registers all 8 tools with the MCP SDK's McpServer.
+// Each tool handler resolves the caller's tier from the API key
+// passed via the _atom_api_key field.
+// ============================================================
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { resolveTier } from "./auth.js";
+
+// Tool imports
+import { searchModelsSchema, handleSearchModels } from "./tools/search-models.js";
+import { getModelDetailSchema, handleGetModelDetail } from "./tools/get-model-detail.js";
+import { comparePricesSchema, handleComparePrices } from "./tools/compare-prices.js";
+import { getVendorCatalogSchema, handleGetVendorCatalog } from "./tools/get-vendor-catalog.js";
+import { getMarketStatsSchema, handleGetMarketStats } from "./tools/get-market-stats.js";
+import { getIndexBenchmarksSchema, handleGetIndexBenchmarks } from "./tools/get-index-benchmarks.js";
+import { getKpisSchema, handleGetKpis } from "./tools/get-kpis.js";
+import { listVendorsSchema, handleListVendors } from "./tools/list-vendors.js";
+
+// Common API key field injected into every tool's schema
+const apiKeyField = {
+  _atom_api_key: z
+    .string()
+    .optional()
+    .describe("Your ATOM API key for full access. Omit for free tier (redacted data)."),
+};
+
+export function createServer(): McpServer {
+  const server = new McpServer({
+    name: "atom-mcp-server",
+    version: "1.0.0",
+  });
+
+  // ----------------------------------------------------------
+  // 1. search_models
+  // ----------------------------------------------------------
+  server.registerTool(
+    "search_models",
+    {
+      title: "Search AI Models",
+      description: `Search and filter AI inference models across 40+ vendors and 1,600+ SKUs.
+
+Query by modality (Text, Image, Audio, Video, Multimodal), vendor, creator, model family, open-source status, price range, context window, and parameter count.
+
+Returns matching models with pricing. Free tier shows count + price range; paid tier shows full details.
+
+Examples:
+  - "Find open-source text models under $1/M tokens" → open_source=true, modality="Text", max_price=0.001
+  - "What multimodal models does Google offer?" → vendor="Google", modality="Multimodal"
+  - "Models with 128K+ context window" → min_context_window=128000`,
+      inputSchema: { ...searchModelsSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleSearchModels(params, tier);
+    }
+  );
+
+  // ----------------------------------------------------------
+  // 2. get_model_detail
+  // ----------------------------------------------------------
+  server.registerTool(
+    "get_model_detail",
+    {
+      title: "Get Model Details",
+      description: `Deep dive on a single AI model: technical specs + pricing across all vendors.
+
+Returns model_registry data (context window, parameters, open-source status, training cutoff, model family) plus all SKU pricing across every vendor that offers this model.
+
+Examples:
+  - "Tell me everything about GPT-4o" → model_name="GPT-4o"
+  - "Claude Sonnet 4.5 specs and pricing" → model_name="Claude Sonnet 4.5"`,
+      inputSchema: { ...getModelDetailSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleGetModelDetail(params, tier);
+    }
+  );
+
+  // ----------------------------------------------------------
+  // 3. compare_prices
+  // ----------------------------------------------------------
+  server.registerTool(
+    "compare_prices",
+    {
+      title: "Compare Prices Across Vendors",
+      description: `Cross-vendor price comparison for a specific model or model family.
+
+Shows the same model (or family) priced across different vendors, sorted cheapest first. Essential for cost optimization and vendor selection.
+
+Examples:
+  - "Compare Llama 3.1 70B pricing across vendors" → model_name="Llama 3.1 70B"
+  - "Cheapest GPT-4 family output pricing" → model_family="GPT-4", direction="Output"
+  - "Claude pricing comparison" → model_family="Claude"`,
+      inputSchema: { ...comparePricesSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleComparePrices(params, tier);
+    }
+  );
+
+  // ----------------------------------------------------------
+  // 4. get_vendor_catalog
+  // ----------------------------------------------------------
+  server.registerTool(
+    "get_vendor_catalog",
+    {
+      title: "Get Vendor Catalog",
+      description: `Full catalog for a specific vendor: all models, modalities, and pricing.
+
+Returns vendor metadata (country, region, pricing page URL) plus every model and SKU they offer.
+
+Examples:
+  - "What does Together AI sell?" → vendor="Together AI"
+  - "OpenAI's text model pricing" → vendor="OpenAI", modality="Text"
+  - "Amazon Bedrock catalog" → vendor="Amazon Bedrock"`,
+      inputSchema: { ...getVendorCatalogSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleGetVendorCatalog(params, tier);
+    }
+  );
+
+  // ----------------------------------------------------------
+  // 5. get_market_stats
+  // ----------------------------------------------------------
+  server.registerTool(
+    "get_market_stats",
+    {
+      title: "Get Market Statistics",
+      description: `Aggregate AI inference market intelligence.
+
+Returns total vendor/model/SKU counts, price distribution (median, mean, quartiles, min/max), and modality breakdown. Optionally filter by modality.
+
+Examples:
+  - "AI inference market overview" → (no params)
+  - "Text model pricing statistics" → modality="Text"
+  - "Image generation market stats" → modality="Image"`,
+      inputSchema: { ...getMarketStatsSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleGetMarketStats(params, tier);
+    }
+  );
+
+  // ----------------------------------------------------------
+  // 6. get_index_benchmarks
+  // ----------------------------------------------------------
+  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 benchmark prices across index families (Text, Image, Audio, Video, Multimodal, Composite) with input, cached, 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="Text"
+  - "Show me all AIPI indexes" → (no params)
+  - "AIPI-TXT-GLB history" → index_code="AIPI-TXT-GLB"`,
+      inputSchema: { ...getIndexBenchmarksSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleGetIndexBenchmarks(params, tier);
+    }
+  );
+
+  // ----------------------------------------------------------
+  // 7. get_kpis
+  // ----------------------------------------------------------
+  server.registerTool(
+    "get_kpis",
+    {
+      title: "Get Market KPIs",
+      description: `ATOM Inference Price Index (AIPI) market-level KPIs.
+
+Returns 6 key performance indicators derived from 1,600+ SKUs:
+- Output Premium: how much more output tokens cost vs input
+- Caching Savings: average discount for cached input pricing
+- Open Source Advantage: price difference between open-source and proprietary
+- Context Cost Curve: price multiplier for larger context windows
+- Caching Availability: % of models offering cached pricing
+- Size Spread: price ratio between largest and smallest models
+
+These KPIs are available to all tiers — they demonstrate ATOM's market intelligence.`,
+      inputSchema: { ...getKpisSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleGetKpis(params, tier);
+    }
+  );
+
+  // ----------------------------------------------------------
+  // 8. list_vendors
+  // ----------------------------------------------------------
+  server.registerTool(
+    "list_vendors",
+    {
+      title: "List All Vendors",
+      description: `List all 41 AI inference vendors tracked by ATOM.
+
+Returns vendor name, country, region, and pricing page URL. Optionally filter by region or country.
+
+Examples:
+  - "List all vendors" → (no params)
+  - "European AI vendors" → region="Europe"
+  - "Chinese AI vendors" → country="China"`,
+      inputSchema: { ...listVendorsSchema, ...apiKeyField },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      const tier = resolveTier(params._atom_api_key);
+      return handleListVendors(params, tier);
+    }
+  );
+
+  return server;
+}

package/src/supabase.ts

@@ -0,0 +1,125 @@
+// ============================================================
+// ATOM MCP Server — Supabase REST Client
+// ============================================================
+// Lightweight fetch-based client for Supabase PostgREST API.
+// No Supabase JS SDK dependency — keeps the binary small.
+// ============================================================
+
+const SUPABASE_URL = process.env.SUPABASE_URL || "";
+const SUPABASE_ANON_KEY = process.env.SUPABASE_ANON_KEY || "";
+
+if (!SUPABASE_URL || !SUPABASE_ANON_KEY) {
+  console.error(
+    "ATOM MCP: SUPABASE_URL and SUPABASE_ANON_KEY must be set in environment variables."
+  );
+}
+
+const BASE = `${SUPABASE_URL}/rest/v1`;
+
+const headers: Record<string, string> = {
+  apikey: SUPABASE_ANON_KEY,
+  Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+  "Content-Type": "application/json",
+  Prefer: "return=representation",
+};
+
+// ------------------------------------------------------------
+// Generic query builder
+// ------------------------------------------------------------
+
+interface QueryOptions {
+  table: string;
+  select?: string;
+  filters?: string[]; // PostgREST filter strings e.g. "vendor_name=eq.OpenAI"
+  order?: string; // e.g. "normalized_price.asc"
+  limit?: number;
+  offset?: number;
+  count?: "exact" | "planned" | "estimated";
+}
+
+export async function query<T>(opts: QueryOptions): Promise<{ data: T[]; count: number | null }> {
+  const params = new URLSearchParams();
+
+  if (opts.select) params.set("select", opts.select);
+  if (opts.order) params.set("order", opts.order);
+  if (opts.limit) params.set("limit", String(opts.limit));
+  if (opts.offset) params.set("offset", String(opts.offset));
+
+  let url = `${BASE}/${opts.table}?${params.toString()}`;
+
+  // Append filters directly (PostgREST uses column=operator.value syntax)
+  if (opts.filters && opts.filters.length > 0) {
+    for (const f of opts.filters) {
+      url += `&${f}`;
+    }
+  }
+
+  const reqHeaders = { ...headers };
+  if (opts.count) {
+    reqHeaders["Prefer"] = `count=${opts.count}`;
+  }
+
+  const response = await fetch(url, { headers: reqHeaders });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Supabase query failed (${response.status}): ${body}`);
+  }
+
+  const data = (await response.json()) as T[];
+  const contentRange = response.headers.get("content-range");
+  let count: number | null = null;
+  if (contentRange) {
+    const match = contentRange.match(/\/(\d+|\*)/);
+    if (match && match[1] !== "*") {
+      count = parseInt(match[1], 10);
+    }
+  }
+
+  return { data, count };
+}
+
+// ------------------------------------------------------------
+// RPC call helper (for Supabase functions / views)
+// ------------------------------------------------------------
+
+export async function rpc<T>(functionName: string, body?: Record<string, unknown>): Promise<T[]> {
+  const url = `${SUPABASE_URL}/rest/v1/rpc/${functionName}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Supabase RPC ${functionName} failed (${response.status}): ${text}`);
+  }
+
+  return (await response.json()) as T[];
+}
+
+// ------------------------------------------------------------
+// Convenience helpers for common tables
+// ------------------------------------------------------------
+
+export async function queryTable<T>(
+  table: string,
+  filters: string[] = [],
+  options: Partial<QueryOptions> = {}
+): Promise<T[]> {
+  const result = await query<T>({
+    table,
+    filters,
+    ...options,
+  });
+  return result.data;
+}
+
+export async function queryView<T>(
+  viewName: string,
+  filters: string[] = [],
+  options: Partial<QueryOptions> = {}
+): Promise<T[]> {
+  return queryTable<T>(viewName, filters, options);
+}

package/src/tools/compare-prices.ts

@@ -0,0 +1,175 @@
+// ============================================================
+// Tool: compare_prices
+// Cross-vendor price comparison for a model or model family.
+// ============================================================
+
+import { z } from "zod";
+import { queryTable } from "../supabase.js";
+import { gateResults, freeTierNote } from "../auth.js";
+import type { Tier, SkuIndex } from "../types.js";
+
+export const comparePricesSchema = {
+  model_name: z
+    .string()
+    .optional()
+    .describe("Model name to compare prices for, e.g. 'GPT-4o', 'Llama 3.1 70B'"),
+  model_family: z
+    .string()
+    .optional()
+    .describe("Model family to compare, e.g. 'GPT-4o', 'Claude 3.5'"),
+  direction: z
+    .enum(["Input", "Output", "Cached Input"])
+    .optional()
+    .describe("Filter by pricing direction"),
+  modality: z
+    .string()
+    .optional()
+    .describe("Filter by modality: Text, Image, Audio, etc."),
+  limit: z
+    .coerce.number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(50)
+    .describe("Maximum results (default 50)"),
+};
+
+export async function handleComparePrices(
+  params: z.infer<z.ZodObject<typeof comparePricesSchema>>,
+  tier: Tier
+) {
+  if (!params.model_name && !params.model_family) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify({
+            tool: "compare_prices",
+            error: "Please provide either model_name or model_family to compare.",
+          }),
+        },
+      ],
+    };
+  }
+
+  const filters: string[] = [];
+  if (params.model_name) filters.push(`model_name=ilike.*${params.model_name}*`);
+  if (params.direction) filters.push(`direction=eq.${params.direction}`);
+  if (params.modality) filters.push(`modality=ilike.*${params.modality}*`);
+  filters.push("normalized_price=gt.0");
+
+  let skus = await queryTable<SkuIndex>("sku_index", filters, {
+    select: "sku_id,vendor_name,model_name,modality,direction,normalized_price,normalized_price_unit,billing_method",
+    order: "normalized_price.asc",
+    limit: params.limit,
+  });
+
+  // If model_family was provided, filter by model registry
+  if (params.model_family && !params.model_name) {
+    const models = await queryTable<{ model_id: string }>("model_registry", [
+      `model_family=ilike.*${params.model_family}*`,
+    ], {
+      select: "model_id",
+    });
+    const modelIds = new Set(models.map((m) => m.model_id));
+
+    // Re-query SKUs without model_name filter
+    const familyFilters: string[] = [];
+    if (params.direction) familyFilters.push(`direction=eq.${params.direction}`);
+    if (params.modality) familyFilters.push(`modality=ilike.*${params.modality}*`);
+    familyFilters.push("normalized_price=gt.0");
+
+    const allSkus = await queryTable<SkuIndex>("sku_index", familyFilters, {
+      select: "sku_id,model_id,vendor_name,model_name,modality,direction,normalized_price,normalized_price_unit,billing_method",
+      order: "normalized_price.asc",
+      limit: 200,
+    });
+
+    skus = allSkus.filter((s) => modelIds.has(s.model_id)).slice(0, params.limit);
+  }
+
+  if (skus.length === 0) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify({
+            tool: "compare_prices",
+            error: `No pricing data found for '${params.model_name || params.model_family}'.`,
+          }),
+        },
+      ],
+    };
+  }
+
+  const prices = skus
+    .map((s) => s.normalized_price)
+    .filter((p): p is number => p !== null && p > 0);
+
+  let results: unknown;
+
+  if (tier === "paid") {
+    results = {
+      comparisons: skus,
+      stats: {
+        total: skus.length,
+        vendors: [...new Set(skus.map((s) => s.vendor_name))].length,
+        cheapest: prices.length > 0 ? prices[0] : null,
+        most_expensive: prices.length > 0 ? prices[prices.length - 1] : null,
+        spread_ratio:
+          prices.length >= 2
+            ? +(prices[prices.length - 1] / prices[0]).toFixed(2)
+            : null,
+      },
+    };
+  } else {
+    results = {
+      summary: {
+        total_vendors: [...new Set(skus.map((s) => s.vendor_name))].length,
+        total_skus: skus.length,
+        price_range: {
+          min: prices.length > 0 ? prices[0] : null,
+          max: prices.length > 0 ? prices[prices.length - 1] : null,
+        },
+        spread_ratio:
+          prices.length >= 2
+            ? +(prices[prices.length - 1] / prices[0]).toFixed(2)
+            : null,
+        directions: [...new Set(skus.map((s) => s.direction))],
+      },
+      sample: gateResults(
+        skus.slice(0, 3) as unknown as Record<string, unknown>[],
+        "free"
+      ),
+      upgrade_message:
+        "Full vendor-by-vendor comparison requires ATOM MCP Pro ($49/mo). Visit https://a7om.com/mcp",
+    };
+  }
+
+  const content: { type: "text"; text: string }[] = [
+    {
+      type: "text" as const,
+      text: JSON.stringify(
+        {
+          tool: "compare_prices",
+          tier,
+          query: {
+            model_name: params.model_name,
+            model_family: params.model_family,
+            direction: params.direction,
+            modality: params.modality,
+          },
+          results,
+        },
+        null,
+        2
+      ),
+    },
+  ];
+
+  if (tier === "free") {
+    content.push(freeTierNote("Full vendor-by-vendor price comparison"));
+  }
+
+  return { content };
+}

package/src/tools/get-index-benchmarks.ts

@@ -0,0 +1,122 @@
+// ============================================================
+// Tool: get_index_benchmarks
+// AIPI index family benchmarks — public market intelligence.
+// ============================================================
+
+import { z } from "zod";
+import { queryTable } from "../supabase.js";
+import type { Tier, IndexValues } from "../types.js";
+
+export const getIndexBenchmarksSchema = {
+  index_code: z
+    .string()
+    .optional()
+    .describe(
+      "Filter by specific AIPI index code, e.g. 'AIPI-TXT-GLB', 'AIPI-IMG-GLB'. Omit to see all indexes."
+    ),
+  index_category: z
+    .string()
+    .optional()
+    .describe(
+      "Filter by index category, e.g. 'Text', 'Image', 'Audio', 'Video', 'Multimodal', 'Composite'"
+    ),
+  limit: z
+    .coerce.number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(25)
+    .describe("Maximum results to return (default 25)"),
+};
+
+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
+        ),
+      },
+    ],
+  };
+}