@index9/mcp 5.1.0 → 5.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @index9/mcp
 
-Search, inspect, and benchmark 300+ AI models from your editor
+Discover, shortlist, compare, cost-model, and live-test 300+ AI models from your editor
 
 ## Install
 
@@ -8,7 +8,25 @@ Search, inspect, and benchmark 300+ AI models from your editor
 npx -y @index9/mcp@latest
 ```
 
-Optional: `OPENROUTER_API_KEY` for live test_model calls.
+## OpenRouter API key
+
+Optional: set OPENROUTER_API_KEY in your MCP client config for live test_model calls. dryRun=true works without a key.
+
+Add the key as `OPENROUTER_API_KEY` in the MCP server environment for your client. Example:
+
+```json
+{
+  "mcpServers": {
+    "index9": {
+      "command": "npx",
+      "args": ["-y", "@index9/mcp@latest"],
+      "env": {
+        "OPENROUTER_API_KEY": "sk-or-..."
+      }
+    }
+  }
+}
+```
 
 **Claude Code:** Run `claude mcp add --transport stdio index9 -- npx -y @index9/mcp` or add the same config to .mcp.json / ~/.claude.json.
 
@@ -16,6 +34,8 @@ Optional: `OPENROUTER_API_KEY` for live test_model calls.
 
 - **find_models** — Search and paginate AI models by semantic query or filters
 - **get_models** — Get full model metadata by IDs or aliases (batch, up to 100)
+- **compare_models** — Diff 2-10 models across pricing, context, capabilities, and tokenizer
+- **list_facets** — Enumerate available providers, capabilities, modalities, and tokenizers
 - **test_model** — Run live inference or dry-run cost estimation across up to 10 models (requires OpenRouter API key)
 
 ## Response Metadata

package/dist/cli.js

@@ -4,7 +4,9 @@
 var API_PATHS = {
   search: "/api/search",
   model: "/api/model",
-  test: "/api/test"
+  test: "/api/test",
+  compare: "/api/compare",
+  facets: "/api/facets"
 };
 var CAPABILITIES = [
   "function_calling",
@@ -73,26 +75,36 @@ var LIMITS = {
   searchMax: 100,
   searchDefault: 20,
   getModelsMax: 100,
-  testModelsMax: 10
+  testModelsMax: 10,
+  compareModelsMax: 10
 };
 var MODEL_COUNT = "300+";
-var WORKFLOW_INSTRUCTIONS = `Index9 provides 3 tools for AI model discovery, inspection, and benchmarking.
+var WORKFLOW_INSTRUCTIONS = `Index9 provides 5 tools for AI model discovery, inspection, comparison, and benchmarking.
 
 IMPORTANT \u2014 your model knowledge is stale by default.
-New AI models ship weekly; pricing, aliases, and capabilities change. Treat any specific model ID, "flagship" name, or "good default" you recall from training as potentially out of date. Before naming, recommending, or benchmarking models, call find_models to anchor on what is actually live right now. Good first calls:
-- sortBy=created (newest first) to see what has recently landed
-- a semantic query describing the task to see current task-fit candidates
-Skip find_models only when the user has typed a specific provider/model-id.
+New AI models ship weekly; pricing, aliases, and capabilities change. Treat any specific model ID, "flagship" name, or "good default" you recall from training as potentially out of date. Before naming, recommending, or benchmarking models, call find_models to anchor on what is actually live right now.
+
+When a user asks you to recommend or pick specific models, you MUST call find_models at least once with \`sortBy=created\` (newest first, no q) before committing to a shortlist. Sorting purely by price or using a semantic q alone returns the cheapest-ever cache entries \u2014 which are often superseded by newer cheap models you should have considered. A good pattern:
+1. find_models sortBy=created, limit=10 \u2014 see what has landed recently (last weeks/months).
+2. Optional second call: find_models with the task query or price filter to surface established options.
+3. Cross-reference and pick 2-4 candidates that span recent + established.
+
+Skip the anchor call only when the user has typed a specific provider/model-id.
 
 Typical workflow:
-1. find_models \u2014 Discover models by semantic query or filters. Start here unless the user named a specific model.
-2. get_models \u2014 Full metadata for specific IDs or aliases. Use after search, or directly when the user names a model.
-3. test_model \u2014 Run live inference, or set dryRun=true to estimate token usage/cost without running inference.
+1. list_facets \u2014 Optional first call to learn the live filter vocabulary (providers, capabilities, modalities, tokenizers) before constructing find_models filters.
+2. find_models \u2014 Discover models by semantic query or filters. Start here unless the user named a specific model.
+3. get_models \u2014 Full metadata for specific IDs or aliases. Use after search, or directly when the user names a model.
+4. compare_models \u2014 Side-by-side diff of 2-10 candidates with cheapest/largest-context picks. Use when the user is choosing between specific finalists.
+5. test_model \u2014 Run live inference, or set dryRun=true to estimate token usage/cost without running inference.
 
 Key rules:
 - find_models requires \`q\` when \`sortBy=relevance\` (the default). Omit \`q\` only with \`sortBy=created\` or \`sortBy=price\`.
-- get_models accepts aliases (display names, short names) \u2014 not just full IDs. If a model you "know from memory" returns in missingIds, that is a signal to call find_models.
-- Use test_model with \`dryRun=true\` to estimate cost before live testing.
+- find_models price-asc tends to be dominated by free preview models \u2014 pass \`excludeFree=true\` when you want a paid SLA.
+- find_models flags \`meta.confidence: "low"\` when no candidate matched on keyword (BM25). When that fires, prefer \`meta.suggestion\` over the returned scores; weak hits are capped at score=30 so they don't masquerade as strong matches.
+- get_models accepts aliases (display names, short names) \u2014 not just full IDs. Unknown ids return in missingIds with \`suggestions\` (token-fuzzy or recency-anchored newest-from-provider). Retry with one of the suggested ids.
+- compare_models accepts the same alias formats as get_models. Use it instead of N parallel get_models calls when the user is comparing finalists.
+- Use test_model with \`dryRun=true\` to estimate cost before live testing. Pass \`expectedPromptTokens\` for capacity planning at sizes you don't want to paste in full.
 - test_model with \`dryRun=false\` (default) requires OPENROUTER_API_KEY and incurs real usage costs.
 - Reasoning-capable models (capabilities includes "reasoning") burn hidden reasoning tokens against \`maxTokens\` before emitting visible text. Leave \`maxTokens\` unset, or set it to at least 2000, when testing reasoning models \u2014 otherwise results may fail with finish_reason=length.
 - Cursors are opaque and tied to query/sort/filters. Reuse the same query/sort/filters when paginating. \`limit\` may change between pages.`;
@@ -101,25 +113,28 @@ var TOOLS = {
     name: "find_models",
     title: "Search AI models",
     summary: "Search and paginate AI models by semantic query or filters",
-    description: `Search and filter ${MODEL_COUNT} AI models. Returns ranked results with pricing, context windows, and capabilities.
+    description: `Filter ${MODEL_COUNT} AI models by structured constraints (capabilities, price, context, modality, provider). The semantic \`q\` is a soft tiebreaker on top of filters \u2014 trust filters first; weak \`q\`-only queries surface as \`meta.confidence: "low"\` with a hint to drop \`q\` and use \`sortBy=created\` or \`sortBy=price\` instead.
 
-Call this first unless the user named a specific model \u2014 your training-data list of "good" models is likely stale.
+Call this after list_facets (or directly when you already know the filters). Always include one call with sortBy=created (no q) when recommending models to the user \u2014 your training-data list of "good" models is likely stale, and sorting purely by price surfaces old tiny models and misses this month's cheap frontier.
 
-Extract filters from user queries. \`q\` drives semantic ranking; numeric and categorical constraints MUST go in structured filters. Shorthand: 1K=1000, 1M=1000000. Prices are USD per million input tokens.
+Extract filters from user queries. Numeric and categorical constraints MUST go in structured filters; \`q\` is for semantic flavor. Shorthand: 1K=1000, 1M=1000000. Prices are USD per million input tokens.
 
 Examples:
 - "1M context under $1" \u2192 q="model", minContext=1000000, maxPrice=1
 - "cheap vision model from openai" \u2192 q="cheap vision model", capabilitiesAll=["vision"], provider="openai"
 - "function calling under $0.50 with 128K" \u2192 q="function calling", capabilitiesAll=["function_calling"], maxPrice=0.5, minContext=128000
+- "cheapest paid model" \u2192 sortBy="price", sortOrder="asc", excludeFree=true
 - "best coding model" \u2192 q="best coding model"
 - "what's new" \u2192 sortBy="created" (no q needed)
 
 Valid capabilities: ${CAPABILITIES.join(", ")}.
 
-Each result: id, name, description, created (unix seconds), createdAt (ISO 8601), contextLength, maxOutputTokens, pricing.{promptPerMillion, completionPerMillion} (numbers, USD per million tokens), capabilities[], score.
+Each result: id, name, description, created (unix seconds), createdAt (ISO 8601), contextLength, maxOutputTokens, pricing.{promptPerMillion, completionPerMillion} (numbers, USD per million tokens), inputModalities[] / outputModalities[] (e.g. ["text","image"] \u2014 check at a glance to spot text-only vs multimodal models), capabilities[], score.
 
 \`score\` is 0-100: the best match per page scores 100; others scale proportionally. Combines semantic similarity and keyword matching. Null when sorting by price or date.
 
+\`q\` must be at least 2 characters when provided. \`meta.confidence\` is "low" when no candidate matched on keyword (BM25), meaning the ranker fell back to vector similarity alone \u2014 typo, gibberish, or a query the catalog can't answer. When low, \`meta.suggestion\` carries an actionable hint and \`score\` values are capped at 30 so weak hits don't masquerade as strong ones.
+
 Pass result.id to get_models for full specs or to test_model for live testing.`,
     requiresKey: false
   },
@@ -131,7 +146,7 @@ Pass result.id to get_models for full specs or to test_model for live testing.`,
 
 Call after find_models to inspect candidates, or directly when the user names a model (format: 'provider/model-name').
 
-Response: { results: (Model | null)[], missingIds: string[], resolvedAliases?: Record<alias, canonicalId>, ambiguousAliases?: Record<alias, candidateIds[]> }. Each non-null result has:
+Response: { results: (Model | null)[], missingIds: string[], resolvedAliases?: Record<alias, canonicalId>, ambiguousAliases?: Record<alias, candidateIds[]>, suggestions?: Record<unknownId, candidateIds[]> }. Each non-null result has:
 - id, canonicalSlug, name, description
 - created (unix seconds), createdAt (ISO 8601), knowledgeCutoff (ISO date or null)
 - contextLength (tokens), maxOutputTokens, isModerated
@@ -140,7 +155,35 @@ Response: { results: (Model | null)[], missingIds: string[], resolvedAliases?: R
 - capabilities[]: normalized capability flags (same values as find_models and capabilitiesAll/Any)
 - supportedParameters[]: OpenRouter parameters the model accepts (e.g., "temperature", "tools", "response_format")
 
-Entries in results are null when the id is unknown; those ids appear in missingIds. Ambiguous aliases appear in ambiguousAliases with candidate canonical ids \u2014 pass a canonical id to disambiguate.`,
+Entries in results are null when the id is unknown; those ids appear in missingIds. Ambiguous aliases appear in ambiguousAliases with candidate canonical ids \u2014 pass a canonical id to disambiguate. Unknown ids that partially match (e.g. "sonnet" \u2192 all Claude Sonnet variants) appear in suggestions with up to 5 candidate ids. When token-overlap finds nothing but the id is shaped like \`provider/<unknown>\` and the provider exists, suggestions falls back to the 5 newest models from that provider (real created timestamps, no hardcoded "popular" list). Retry with one of the suggested ids.`,
+    requiresKey: false
+  },
+  compare_models: {
+    name: "compare_models",
+    title: "Compare AI models side-by-side",
+    summary: "Diff 2-10 models across pricing, context, capabilities, and tokenizer",
+    description: `Compare 2-${LIMITS.compareModelsMax} models side-by-side. Returns each model's full metadata plus a diff matrix highlighting which fields are equal and which differ.
+
+Use this when the user asks "which is cheaper / has more context / supports X" across multiple specific models. Faster than calling get_models and diffing yourself.
+
+Response: { models: ModelResponse[], diff: { contextLength, maxOutputTokens, promptPricePerMillion, completionPricePerMillion, tokenizer, inputModalities, outputModalities, capabilities, supportedParameters }, cheapestForPromptPerMillion, largestContext, missingIds, resolvedAliases?, ambiguousAliases?, suggestions? }.
+
+Each numeric/string diff field has { allEqual: boolean, values: Record<id, value|null> }. Capability/parameter diffs have { commonAll: string[], uniquePerModel: Record<id, string[]> }. cheapestForPromptPerMillion / largestContext are convenience picks across the supplied models \u2014 null when the field is missing on every model.
+
+Optional: pass \`expectedPromptTokens\` AND \`expectedCompletionTokens\` to also receive \`workloadCosts\` (per-model totalCostUsd) and \`cheapestForRealisticWorkload\` \u2014 the actual cheapest given the user's expected token mix. This matters when prompt:completion price ratios diverge across models (e.g., a model with cheap prompt but expensive completion can lose against a flatter-priced sibling under heavy completions).
+
+Accepts the same alias formats as get_models. Unknown ids are returned in missingIds (with suggestions when partial matches exist).`,
+    requiresKey: false
+  },
+  list_facets: {
+    name: "list_facets",
+    title: "List filter vocabulary",
+    summary: "Enumerate available providers, capabilities, modalities, and tokenizers",
+    description: `Return the live vocabulary derived from the current model cache: providers (id-prefixes with model counts), capability flags (with counts), input/output modalities, and tokenizers.
+
+Use this once at the start of a session to learn what filter values find_models will accept, instead of trial-and-error against find_models.
+
+Response: { providers: { id, modelCount }[], capabilities: { id, modelCount }[], modalities: { input: string[], output: string[] }, tokenizers: string[], totalModels: number, updatedAt: string (ISO 8601) }. No inputs.`,
     requiresKey: false
   },
   test_model: {
@@ -152,13 +195,14 @@ Entries in results are null when the id is unknown; those ids appear in missingI
 When dryRun=true:
 - No OpenRouter API key required
 - No inference call is made
-- prompt is required
+- Either \`prompt\` OR \`expectedPromptTokens\` is required (use the latter for capacity planning at sizes you don't want to paste in full)
 - expectedCompletionTokens defaults to 256 when omitted
 
 Parameters:
 - models: 1-${LIMITS.testModelsMax} model IDs to test (all receive identical prompts)
-- prompt: Prompt text (required for dryRun; required for live unless userContent provided)
+- prompt: Prompt text (required for dryRun unless expectedPromptTokens is set; required for live unless userContent provided)
 - dryRun: If true, return cost estimates only
+- expectedPromptTokens: Estimated prompt-token count for dryRun cost estimation; overrides the prompt-string heuristic. Use to model "what would N-token requests cost?" without pasting N tokens.
 - expectedCompletionTokens: Optional completion token estimate used by dryRun
 - maxTokens, systemPrompt, temperature, topP, seed, responseFormat, enforceJson, retries: Live-testing controls (ignored when dryRun=true)
 
@@ -167,13 +211,15 @@ Results (live): each result carries modelId (the id you passed), resolvedModelId
   }
 };
 var PARAM_DESCRIPTIONS = {
-  q: "Natural language search query describing desired model characteristics (e.g., 'fast cheap coding model'). Uses semantic search with fuzzy matching. Optional - omit to use filters only.",
+  q: "Natural language search query describing desired model characteristics (e.g., 'fast cheap coding model'). Uses semantic search with fuzzy matching. Must be at least 2 characters when provided. Optional \u2014 omit (along with sortBy=created or sortBy=price) to use filters only.",
   sortBy: `Sort order for results. Options: 'relevance' (best semantic match, default), 'created' (newest models), 'price' (cheapest/most expensive, with sortOrder). Defaults to 'relevance'.`,
   cursor: `Opaque pagination cursor from a previous response's \`nextCursor\` field. IMPORTANT: cursors are bound to the exact query text, filters, and sort order that produced them. Reuse the same query+filters+sort when paginating. \`limit\` may change between pages. To start a new search, omit the cursor.`,
   capabilitiesAll: `Array of capabilities that must ALL be present on the model (AND logic). Valid values: ${CAPABILITIES.join(", ")}. Example: ["function_calling","vision"].`,
   capabilitiesAny: `Array of capabilities where at least ONE must be present (OR logic). Valid values: ${CAPABILITIES.join(", ")}. Example: ["vision","audio_input"].`,
   modality: `Required output modality. Filters on the model's output modalities, not input capabilities. For example, "image" finds image-generation models, while capabilitiesAll=["vision"] finds models that accept image input. Valid values: ${OUTPUT_MODALITIES.join(", ")}.`,
-  provider: `Provider prefix filter. Matches model IDs starting with this prefix (e.g., 'openai' matches 'openai/gpt-4o'). Common providers: ${COMMON_PROVIDERS.join(", ")}.`,
+  provider: `Provider prefix filter. Array of provider slugs \u2014 a model matches if its ID starts with any of them (e.g., ['openai'] matches 'openai/gpt-4o'; ['openai','anthropic'] matches both). Pass a single-element array for one provider. Common providers: ${COMMON_PROVIDERS.join(", ")}.`,
+  excludeFree: `When true, exclude models with id ending in ':free'. Useful for sortBy=price (which would otherwise be dominated by free-tier preview models) and when you want a paid SLA. Default false.`,
+  expectedPromptTokens: `Expected number of prompt tokens for dryRun cost estimation. When set, overrides the heuristic that counts characters from the literal \`prompt\` string \u2014 use this for capacity planning ("what would 6000-token reviews cost?") without pasting filler. If both are omitted, the prompt string is tokenized at ~4 chars/token.`,
   expectedCompletionTokens: `Expected number of completion tokens for cost estimation (default: 256). Typical ranges: 100-500 for quick tests, 1000-2000 for code generation, 4000+ for long-form content. This is a heuristic \u2014 actual billed tokens may differ.`
 };
 var SITE = {
@@ -184,56 +230,161 @@ var SITE = {
     install: "Install",
     faq: "FAQ",
     github: "GitHub",
-    githubLabel: "GitHub repository"
+    githubLabel: "GitHub repository",
+    installCta: "Install"
   },
   hero: {
-    titleLine1: "Test AI models on your actual prompts, ",
-    titleLine2: "not generic benchmarks",
-    subtitle: "Compare quality, speed, and cost across 300+ models \u2014 in Cursor, VS Code, or Claude Code.",
-    identity: "index9 is an MCP server that lets your AI coding assistant search, compare, and live-test models from inside your editor.",
-    audiencePrefix: "Built for",
-    audience: ["AI engineers", "Indie developers", "Teams standardizing on models"],
+    titleLine1: "Pick the right AI model",
+    titleLine2: "without leaving your editor",
+    subtitle: "Index9 is an MCP server. Your AI assistant searches, compares, and live-tests 300+ models on your prompt, so picks are measured, not guessed.",
+    proof: ["Live OpenRouter data", "300+ models, refreshed every 30 min"],
     pricingNote: "Free. You only pay OpenRouter for live model calls.",
-    getStarted: "Add to your editor",
-    seeHowItWorks: "See an example",
-    updatedBadge: "Model pricing & specs from OpenRouter \u2014 refreshed "
+    getStarted: "Add index9 to your editor",
+    seeHowItWorks: "See a real session",
+    updatedBadge: "OpenRouter data \xB7 refreshed "
   },
   howItWorks: {
     label: "How it works",
-    heading: "Your assistant picks the right model, automatically",
-    subtitle: "index9 runs as an MCP (Model Context Protocol) server. Your editor already speaks MCP \u2014 index9 just plugs in as three extra tools your assistant can call.",
+    heading: "Your assistant does the model-picking. You stay in the chat.",
+    subtitle: "Index9 adds five MCP tools to your editor. When you ask about models, your assistant calls them, and gets live data back.",
     steps: [
       {
         number: "1",
         title: "You ask your assistant",
-        body: '"Pick the cheapest model that can summarize this document well." You chat normally \u2014 no new UI to learn.'
+        body: '"Pick the cheapest model that can summarize this document well." Just chat. No new UI to learn.'
       },
       {
         number: "2",
         title: "Your assistant calls index9",
-        body: "It runs find_models, get_models, and test_model against live OpenRouter data. Results come back with latency, tokens, and cost for your prompt."
+        body: "It pulls live OpenRouter data: search results, full specs, cost diffs, and test outputs on your prompt."
       },
       {
         number: "3",
         title: "You get a measured recommendation",
-        body: "The assistant compares real outputs on your real prompt, then recommends the model that fits your constraints. Evidence, not guesswork."
+        body: "The assistant compares actual outputs and recommends the model that fits your constraints. Evidence, not guesswork."
       }
     ]
   },
+  caseStudy: {
+    label: "Case study",
+    heading: "A real session, not a mock",
+    subheading: "A Claude Code session picking a TypeScript code-review model. Actual tool calls, decisions, and final pick. Captured 2026-04-24.",
+    prompt: {
+      title: "The prompt",
+      body: "Pick 3 models for a TypeScript code-review bot. Test them on a sample PR diff and recommend the best one. Quality matters more than price."
+    },
+    toolCalls: {
+      title: "Selection path",
+      subtitle: "in order",
+      calls: [
+        {
+          tool: "find_models",
+          params: "sortBy=created, limit=10",
+          note: "recent releases"
+        },
+        {
+          tool: "find_models",
+          params: 'q="code review reasoning", structured_output',
+          note: "task fit"
+        },
+        {
+          tool: "find_models",
+          params: 'q="not frontier price", maxPrice=6',
+          note: "budget filter"
+        },
+        { tool: "get_models", params: "\xD7 12 candidates", note: "metadata lookup" },
+        {
+          tool: "compare_models",
+          params: "ids=[3 finalists], expectedPromptTokens=6000",
+          note: "workload-cost flip"
+        },
+        { tool: "test_model", params: "dryRun \xD7 2", note: "cost estimate" },
+        {
+          tool: "test_model",
+          params: "live \xD7 2, enforceJson=true",
+          note: "real inference"
+        }
+      ]
+    },
+    consideredTitle: "Every recent model, evaluated",
+    consideredSubtitle: "Recent releases were checked with explicit accept, test, or skip decisions.",
+    consideredRows: [
+      {
+        id: "openai/gpt-5.5-pro",
+        age: "6h ago",
+        decision: "skip",
+        reason: "too expensive for every PR"
+      },
+      {
+        id: "openai/gpt-5.5",
+        age: "6h ago",
+        decision: "skip",
+        reason: "frontier-priced vs Codex"
+      },
+      {
+        id: "deepseek/deepseek-v4-pro",
+        age: "14h ago",
+        decision: "tested",
+        reason: "live test hit upstream 429 twice"
+      },
+      {
+        id: "deepseek/deepseek-v4-flash",
+        age: "14h ago",
+        decision: "skip",
+        reason: "cheaper sibling, lower quality expected"
+      },
+      {
+        id: "xiaomi/mimo-v2.5-pro",
+        age: "2d ago",
+        decision: "shortlisted",
+        reason: "recent + reasoning + structured output"
+      },
+      {
+        id: "inclusionai/ling-2.6-1t:free",
+        age: "1d ago",
+        decision: "skip",
+        reason: "no reasoning capability flag"
+      },
+      {
+        id: "arcee-ai/trinity-large-thinking",
+        age: "3w ago",
+        decision: "skip",
+        reason: "MiMo Pro had stronger positioning"
+      }
+    ],
+    verdict: {
+      title: "The final pick",
+      model: "openai/gpt-5.3-codex",
+      body: "The only tested model that caught both sample bugs. About $0.015 per PR: higher than budget models, far below frontier rates."
+    },
+    quote: {
+      body: "The cheapest candidate ran 4\xD7 cheaper than Codex, and missed both bugs in the sample diff. The only way to know was a live test.",
+      attribution: "index9 session trace, 2026-04-24"
+    }
+  },
   toolsSection: {
     label: "Tools",
-    heading: "Search, inspect, and run live tests",
-    subheading: "Three MCP tools your assistant can call. Each maps to one clear job your assistant can do without leaving the chat.",
+    heading: "Five MCP tools, composable in any client",
+    subheading: "Discover, shortlist, compare, cost-model, and live-test. Your assistant chains them together to make a measured pick.",
     openRouterKey: "OpenRouter API key (live tests only)",
     noKeyRequired: "No API key required",
     requiresLabel: "Requires ",
     cards: [
+      {
+        name: "list_facets",
+        action: "Discover",
+        displayName: "list_facets",
+        fullName: null,
+        description: "List the live filter vocabulary (providers, capabilities, modalities) before constructing a search.",
+        badge: null,
+        requiresKey: false
+      },
       {
         name: "find_models",
-        action: "Search",
+        action: "Shortlist",
         displayName: "find_models",
         fullName: null,
-        description: `Search ${MODEL_COUNT} models by what you need \u2014 price, speed, context window, or capabilities like vision and function calling.`,
+        description: `Filter ${MODEL_COUNT} models by price, context, and capabilities. Natural-language search refines the ranking.`,
         badge: null,
         requiresKey: false
       },
@@ -242,7 +393,16 @@ var SITE = {
         action: "Inspect",
         displayName: "get_models",
         fullName: null,
-        description: "Get current pricing, limits, and capabilities for any model. Synced from OpenRouter every 30 minutes.",
+        description: "Inspect current pricing, limits, and capabilities for any model.",
+        badge: null,
+        requiresKey: false
+      },
+      {
+        name: "compare_models",
+        action: "Compare",
+        displayName: "compare_models",
+        fullName: null,
+        description: "Side-by-side spec, capability, and workload-cost diff for 2\u201310 finalists.",
         badge: null,
         requiresKey: false
       },
@@ -251,7 +411,7 @@ var SITE = {
         action: "Run live tests",
         displayName: "test_model",
         fullName: null,
-        description: "Send your prompt to multiple models. Compare outputs, latency, and cost \u2014 measured, not estimated.",
+        description: "Run one prompt across models and compare output, latency, and cost.",
         badge: "Live Testing",
         requiresKey: true
       }
@@ -263,35 +423,45 @@ var SITE = {
     items: [
       {
         question: "What is MCP?",
-        answer: "MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. Adding index9 gives your assistant model discovery and testing tools inside any MCP-compatible client.",
+        answer: "MCP (Model Context Protocol) lets AI assistants call external tools. index9 adds five composable tools (list_facets, find_models, get_models, compare_models, test_model) to any MCP-compatible client.",
         link: {
           label: "Learn more about MCP",
           url: "https://modelcontextprotocol.io"
         }
       },
+      {
+        question: "Who is index9 for?",
+        answer: "Developers using AI coding assistants (Claude Code, Cursor, Codex, VS Code) who want their assistant to pick models based on live cost and quality data, not training-data guesses.",
+        link: null
+      },
       {
         question: "How does live testing work?",
-        answer: `When you use test_model with dryRun=false (default), your prompt is sent to 1\u2013${LIMITS.testModelsMax} models via OpenRouter. Results include the full output plus latency, token usage, and cost. This requires an OpenRouter API key, which index9 forwards per-request and does not store or log. With dryRun=true, no inference call is made and no key is required \u2014 you get estimated token usage and projected cost only.`,
+        answer: `test_model sends your prompt to 1\u2013${LIMITS.testModelsMax} models via OpenRouter and returns output, latency, token usage, and cost. Live tests require an OpenRouter key; dryRun=true only estimates cost (pass expectedPromptTokens to model larger workloads without pasting filler).`,
         link: null
       },
       {
         question: "Does index9 recommend which model to use?",
-        answer: "index9 provides the raw results \u2014 outputs, latency, cost, and specs. Your assistant can then recommend a model based on those results and your specific constraints.",
+        answer: "index9 returns outputs, latency, cost, and specs. Your assistant uses those results to make the recommendation.",
+        link: null
+      },
+      {
+        question: "How is compare_models different from calling get_models on each candidate?",
+        answer: "compare_models returns a diff matrix (which fields are equal, which differ), plus convenience picks: cheapestForPromptPerMillion, largestContext, and (when you pass expectedPromptTokens + expectedCompletionTokens) cheapestForRealisticWorkload accounting for prompt:completion ratio differences. One call instead of N parallel get_models calls plus manual diffing.",
         link: null
       },
       {
         question: "What models are available?",
-        answer: `index9 provides access to ${MODEL_COUNT} models via OpenRouter, including OpenAI, Anthropic, Google, Meta, Mistral, and many others. Model metadata is continuously synced from OpenRouter so you have current pricing, context windows, and capabilities.`,
+        answer: `index9 covers ${MODEL_COUNT} OpenRouter models, including OpenAI, Anthropic, Google, Meta, Mistral, and others. Metadata refreshes every 30 minutes.`,
         link: null
       },
       {
         question: "What's the project status?",
-        answer: "index9 is live and used daily. Core tools are stable. Improvements ship through changesets on GitHub; issues and feedback are welcome there.",
+        answer: "The hosted API and MCP server are stable and in active use. Issues and feature requests welcome on GitHub.",
         link: null
       },
       {
         question: "Is my data stored?",
-        answer: "No. index9 does not store or log your prompts, outputs, or API keys. For live tests, requests are proxied to OpenRouter to run inference.",
+        answer: "No. index9 does not store prompts, outputs, or API keys. Live tests are proxied to OpenRouter.",
         link: null
       }
     ]
@@ -299,17 +469,31 @@ var SITE = {
   install: {
     label: "Setup",
     heading: "Add index9 to your editor",
-    subheading: "One line of config for Cursor, VS Code, or Claude Code. Your assistant can start using it immediately.",
+    subheading: "Choose your client and copy the config.",
     configs: [
       {
-        id: "cursor-vscode",
-        label: "Cursor / VS Code",
-        paths: [".cursor/mcp.json", ".vscode/mcp.json"],
+        id: "cursor",
+        label: "Cursor",
+        paths: [".cursor/mcp.json"],
         config: `{
   "mcpServers": {
     "index9": {
       "command": "npx",
-      "args": ["-y", "@index9/mcp"]
+      "args": ["-y", "@index9/mcp@latest"]
+    }
+  }
+}`
+      },
+      {
+        id: "vscode",
+        label: "VS Code",
+        paths: [".vscode/mcp.json"],
+        config: `{
+  "servers": {
+    "index9": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@index9/mcp@latest"]
     }
   }
 }`
@@ -317,141 +501,37 @@ var SITE = {
       {
         id: "claude-code",
         label: "Claude Code",
-        paths: ["Run in terminal (adds to ~/.claude.json)"],
-        config: `claude mcp add --transport stdio index9 -- npx -y @index9/mcp`,
+        paths: ["Terminal command"],
+        config: `claude mcp add --transport stdio index9 -- npx -y @index9/mcp@latest`,
         copyHint: "# Run in terminal (adds to ~/.claude.json)"
+      },
+      {
+        id: "codex",
+        label: "Codex",
+        paths: ["Terminal command"],
+        config: `codex mcp add index9 -- npx -y @index9/mcp@latest`,
+        copyHint: "# Run in terminal (adds to ~/.codex/config.toml)"
       }
     ],
-    workflowHeading: "Recommended workflow",
-    workflowIntro: "Add these to your assistant rules to guide model selection:",
-    workflowRulesLabel: ".cursor/rules or AGENTS.md",
-    workflowRules: [
-      "Use find_models to shortlist candidates based on task requirements (cost, speed, context window, capabilities).",
-      "Use get_models to confirm pricing, limits, and capabilities for the shortlist.",
-      "Use test_model with dryRun=true to estimate cost, then run live tests with a task-representative prompt. Compare outputs first, then optimize for speed/cost."
-    ],
     copyButton: "Copy",
     copiedButton: "Copied",
     copyAriaLabel: "Copy configuration",
-    openRouterNote: " (for live tests) requires an ",
-    openRouterLink: "OpenRouter API key",
-    openRouterUrl: "https://openrouter.ai/keys",
-    openRouterNoteSuffix: ". Add OPENROUTER_API_KEY to your config env for live tests. dryRun=true does not require a key; keys are passed per-request and never stored or logged."
-  },
-  comparison: {
-    label: "Comparison",
-    heading: "Evidence over intuition",
-    subheading: "Benchmark on your real prompts \u2014 not someone else's.",
-    withoutLabel: "Without index9",
-    withLabel: "With index9",
-    withoutItems: [
-      "Model pricing and specs may be weeks old",
-      "Quality based on generic benchmarks, not your task",
-      "Testing a model means a throwaway script or manual switching"
-    ],
-    withItems: [
-      "Models synced from OpenRouter every 30 minutes",
-      "Quality measured on prompts for your specific task",
-      "Test and compare in your editor \u2014 no scripts, no switching"
-    ],
-    sampleTableLabel: 'Sample comparison \u2014 "Extract the action items from this meeting transcript"',
-    tableHeaders: {
-      model: "Model",
-      latency: "Latency",
-      cost: "Cost",
-      notes: "Notes"
-    },
-    sampleRows: [
-      {
-        model: "gpt-4.1-nano",
-        latency: "310ms",
-        tokens: "96",
-        cost: "$0.0001",
-        note: "Fastest; missed one implicit action item"
-      },
-      {
-        model: "gemini-2.5-flash",
-        latency: "560ms",
-        tokens: "142",
-        cost: "$0.0004",
-        note: "Caught all items; good balance"
-      },
-      {
-        model: "claude-sonnet-4.5",
-        latency: "1,120ms",
-        tokens: "189",
-        cost: "$0.0018",
-        note: "Most thorough; grouped items by owner"
-      }
-    ],
-    tableNote: "The right model depends on the task."
+    setupNote: "Need live tests or custom setup?",
+    setupLink: "Set up live testing",
+    setupUrl: "https://github.com/index9-org/mcp#openrouter-api-key"
   },
   footer: {
     brand: "index9",
-    tagline1: "Model data synced from OpenRouter",
-    tagline2: "Search, testing, and MCP tools by index9",
-    copyright: "\xA9 2026 index9",
+    tagline: "MCP-native model picker. Live data from OpenRouter.",
+    copyrightSuffix: "index9",
     github: "GitHub",
     privacy: "Privacy",
     terms: "Terms"
-  },
-  terminalDemo: {
-    sectionLabel: "Example",
-    titleBar: "Cursor \u2014 assistant chat",
-    userLabel: "You",
-    assistantLabel: "Assistant",
-    userPrompt: "Find the cheapest, most capable model for my use case.",
-    assistantReplyPrefix: "I'll check your ",
-    assistantReplyFile: "summarize-ticket.ts",
-    assistantReplySuffix: " handler, search for suitable models, then test the top 3.",
-    findModelsCall: {
-      label: "find_models",
-      suffix: " \u2014 search by use case",
-      queryLabel: "q:",
-      queryContent: '"cheap fast summarization model"',
-      sortByLabel: "sortBy:",
-      sortByValue: "price"
-    },
-    testModelsCall: {
-      label: "test_model",
-      suffix: " \u2014 top 3 from find_models (via OpenRouter)",
-      modelsLabel: "models:",
-      modelsContent: "gemini-2.5-flash-lite, gpt-4.1-mini, claude-haiku-4.5",
-      promptLabel: "prompt:",
-      promptContent: '"Checkout fails on iPhone Safari. Payment subdomain SSL cert expired."'
-    },
-    resultsLabel: "Results",
-    conclusionPrefix: "Best fit: ",
-    conclusionModel: "gemini-2.5-flash-lite",
-    conclusionSuffix: " \u2014 cheapest and fastest, with comparable quality.",
-    resultCards: [
-      {
-        model: "gemini-2.5-flash-lite",
-        latency: "480ms",
-        cost: "$0.00005",
-        tokens: 124,
-        output: "Mobile Safari checkout failed \u2014 expired SSL cert on payment subdomain. Renewed; customer confirmed."
-      },
-      {
-        model: "gpt-4.1-mini",
-        latency: "720ms",
-        cost: "$0.0002",
-        tokens: 138,
-        output: "Checkout failures on mobile Safari. Root cause: expired SSL cert on payment subdomain. Resolved; fix confirmed."
-      },
-      {
-        model: "claude-haiku-4.5",
-        latency: "980ms",
-        cost: "$0.0008",
-        tokens: 155,
-        output: "Repeated checkout failures on iPhone Safari traced to expired payment subdomain SSL cert. Renewed; customer verified."
-      }
-    ]
   }
 };
 var README = {
-  tagline: `Landing page, API, and MCP server for searching, inspecting, and benchmarking ${MODEL_COUNT} AI models.`,
-  mcpDescription: `Search, inspect, and benchmark ${MODEL_COUNT} AI models from your editor`,
+  tagline: `Landing page, API, and MCP server for discovering, shortlisting, comparing, cost-modeling, and live-testing ${MODEL_COUNT} AI models.`,
+  mcpDescription: `Discover, shortlist, compare, cost-model, and live-test ${MODEL_COUNT} AI models from your editor`,
   monorepoLayout: {
     appsWeb: "apps/web \u2014 Next.js 16 app (UI + API routes)",
     packagesCore: "packages/core \u2014 Shared Zod schemas, types, constants (@index9/core)",
@@ -466,7 +546,7 @@ var README = {
   envNote: "Copy apps/web/.env.example to apps/web/.env.local and fill in values for local development.",
   mcpInstall: {
     cli: "npx -y @index9/mcp@latest",
-    envNote: "Optional: OPENROUTER_API_KEY for live test_model calls.",
+    envNote: "Optional: set OPENROUTER_API_KEY in your MCP client config for live test_model calls. dryRun=true works without a key.",
     claudeCode: "Claude Code: Run `claude mcp add --transport stdio index9 -- npx -y @index9/mcp` or add the same config to .mcp.json / ~/.claude.json."
   },
   release: {
@@ -496,7 +576,8 @@ var SearchQuerySchema = z2.object({
   capabilitiesAll: z2.array(z2.enum(CAPABILITIES)).optional(),
   capabilitiesAny: z2.array(z2.enum(CAPABILITIES)).optional(),
   modality: z2.enum(OUTPUT_MODALITIES).optional(),
-  provider: z2.string().min(1).optional()
+  provider: z2.array(z2.string().min(1)).optional(),
+  excludeFree: z2.boolean().optional()
 }).strict();
 var SearchResultSchema = z2.object({
   id: z2.string(),
@@ -510,6 +591,8 @@ var SearchResultSchema = z2.object({
     promptPerMillion: z2.number().nullable(),
     completionPerMillion: z2.number().nullable()
   }),
+  inputModalities: z2.array(z2.string()),
+  outputModalities: z2.array(z2.string()),
   capabilities: z2.array(z2.string()),
   score: z2.number().nullable()
 });
@@ -524,7 +607,9 @@ var SearchResponseSchema = z2.object({
   }),
   meta: z2.object({
     queryMode: z2.enum(["semantic", "filter_only"]),
-    ranking: z2.literal("hybrid_rrf")
+    ranking: z2.literal("hybrid_rrf"),
+    confidence: z2.enum(["high", "low"]).optional(),
+    suggestion: z2.string().optional()
   })
 });
 var FindModelsToolResultSchema = SearchResponseSchema.extend({
@@ -569,42 +654,122 @@ var BatchModelLookupResponseSchema = z3.object({
   results: z3.array(ModelResponseSchema.nullable()),
   missingIds: z3.array(z3.string()),
   resolvedAliases: z3.record(z3.string(), z3.string()).optional(),
-  ambiguousAliases: z3.record(z3.string(), z3.array(z3.string())).optional()
+  ambiguousAliases: z3.record(z3.string(), z3.array(z3.string())).optional(),
+  suggestions: z3.record(z3.string(), z3.array(z3.string())).optional()
 }).strict();
 var GetModelsToolResultSchema = z3.object({
   results: z3.array(ModelResponseSchema.nullable()),
   missingIds: z3.array(z3.string()),
   resolvedAliases: z3.record(z3.string(), z3.string()).optional(),
   ambiguousAliases: z3.record(z3.string(), z3.array(z3.string())).optional(),
+  suggestions: z3.record(z3.string(), z3.array(z3.string())).optional(),
   _index9: Index9MetaSchema
 });
 
-// ../core/dist/schemas/test.js
+// ../core/dist/schemas/compare.js
 import { z as z4 } from "zod";
-var ResponseFormatSchema = z4.object({
-  type: z4.string().min(1)
-}).catchall(z4.unknown()).optional();
-var TestRequestSchema = z4.object({
-  prompt: z4.string().min(1).optional(),
-  userContent: z4.array(UserContentPartSchema).min(1).optional(),
-  dryRun: z4.boolean().optional(),
-  expectedCompletionTokens: z4.number().int().positive().optional(),
-  models: z4.array(z4.string().min(1)).min(1, "Models are required").max(LIMITS.testModelsMax, `Models must contain between 1 and ${LIMITS.testModelsMax} model IDs`),
-  timeoutMs: z4.number().int().positive().optional(),
-  maxTokens: z4.number().int().positive().optional(),
-  systemPrompt: z4.string().min(1).optional(),
-  temperature: z4.number().min(0).max(2).optional(),
-  topP: z4.number().gt(0).lte(1).optional(),
-  seed: z4.number().int().optional(),
+var CompareRequestSchema = z4.object({
+  ids: z4.array(z4.string().min(1)).min(2, "compare requires at least 2 ids").max(LIMITS.compareModelsMax, `ids must contain between 2 and ${LIMITS.compareModelsMax} model IDs`),
+  expectedPromptTokens: z4.number().int().positive().optional(),
+  expectedCompletionTokens: z4.number().int().positive().optional()
+}).strict();
+var NumericDiffField = z4.object({
+  allEqual: z4.boolean(),
+  values: z4.record(z4.string(), z4.number().nullable())
+});
+var StringDiffField = z4.object({
+  allEqual: z4.boolean(),
+  values: z4.record(z4.string(), z4.string().nullable())
+});
+var StringArrayDiffField = z4.object({
+  allEqual: z4.boolean(),
+  values: z4.record(z4.string(), z4.array(z4.string()))
+});
+var SetDiffField = z4.object({
+  commonAll: z4.array(z4.string()),
+  uniquePerModel: z4.record(z4.string(), z4.array(z4.string()))
+});
+var CompareDiffSchema = z4.object({
+  contextLength: NumericDiffField,
+  maxOutputTokens: NumericDiffField,
+  promptPricePerMillion: NumericDiffField,
+  completionPricePerMillion: NumericDiffField,
+  tokenizer: StringDiffField,
+  inputModalities: StringArrayDiffField,
+  outputModalities: StringArrayDiffField,
+  capabilities: SetDiffField,
+  supportedParameters: SetDiffField
+});
+var CompareWorkloadCostSchema = z4.object({
+  modelId: z4.string(),
+  promptTokens: z4.number().int().nonnegative(),
+  completionTokens: z4.number().int().nonnegative(),
+  totalCostUsd: z4.number().nullable()
+});
+var CompareResponseSchema = z4.object({
+  models: z4.array(ModelResponseSchema),
+  diff: CompareDiffSchema,
+  cheapestForPromptPerMillion: z4.string().nullable(),
+  largestContext: z4.string().nullable(),
+  cheapestForRealisticWorkload: z4.string().nullable().optional(),
+  workloadCosts: z4.array(CompareWorkloadCostSchema).optional(),
+  resolvedAliases: z4.record(z4.string(), z4.string()).optional(),
+  missingIds: z4.array(z4.string()),
+  suggestions: z4.record(z4.string(), z4.array(z4.string())).optional(),
+  ambiguousAliases: z4.record(z4.string(), z4.array(z4.string())).optional()
+}).strict();
+var CompareModelsToolResultSchema = CompareResponseSchema.extend({
+  _index9: Index9MetaSchema
+});
+
+// ../core/dist/schemas/facets.js
+import { z as z5 } from "zod";
+var FacetCount = z5.object({
+  id: z5.string(),
+  modelCount: z5.number().int().nonnegative()
+});
+var FacetsResponseSchema = z5.object({
+  providers: z5.array(FacetCount),
+  capabilities: z5.array(FacetCount),
+  modalities: z5.object({
+    input: z5.array(z5.string()),
+    output: z5.array(z5.string())
+  }),
+  tokenizers: z5.array(z5.string()),
+  totalModels: z5.number().int().nonnegative(),
+  updatedAt: z5.string()
+}).strict();
+var ListFacetsToolResultSchema = FacetsResponseSchema.extend({
+  _index9: Index9MetaSchema
+});
+
+// ../core/dist/schemas/test.js
+import { z as z6 } from "zod";
+var ResponseFormatSchema = z6.object({
+  type: z6.string().min(1)
+}).catchall(z6.unknown()).optional();
+var TestRequestSchema = z6.object({
+  prompt: z6.string().min(1).optional(),
+  userContent: z6.array(UserContentPartSchema).min(1).optional(),
+  dryRun: z6.boolean().optional(),
+  expectedPromptTokens: z6.number().int().positive().optional(),
+  expectedCompletionTokens: z6.number().int().positive().optional(),
+  models: z6.array(z6.string().min(1)).min(1, "Models are required").max(LIMITS.testModelsMax, `Models must contain between 1 and ${LIMITS.testModelsMax} model IDs`),
+  timeoutMs: z6.number().int().positive().optional(),
+  maxTokens: z6.number().int().positive().optional(),
+  systemPrompt: z6.string().min(1).optional(),
+  temperature: z6.number().min(0).max(2).optional(),
+  topP: z6.number().gt(0).lte(1).optional(),
+  seed: z6.number().int().optional(),
   responseFormat: ResponseFormatSchema,
-  enforceJson: z4.boolean().optional(),
-  retries: z4.number().int().min(0).max(3).optional()
+  enforceJson: z6.boolean().optional(),
+  retries: z6.number().int().min(0).max(3).optional()
 }).strict().superRefine((data, ctx) => {
   if (data.dryRun === true) {
-    if (!data.prompt) {
+    if (!data.prompt && data.expectedPromptTokens === void 0) {
       ctx.addIssue({
-        code: z4.ZodIssueCode.custom,
-        message: "Prompt is required when dryRun is true",
+        code: z6.ZodIssueCode.custom,
+        message: "dryRun requires either prompt or expectedPromptTokens",
         path: ["prompt"]
       });
     }
@@ -612,72 +777,72 @@ var TestRequestSchema = z4.object({
   }
   if (!data.prompt && !data.userContent?.length) {
     ctx.addIssue({
-      code: z4.ZodIssueCode.custom,
+      code: z6.ZodIssueCode.custom,
       message: "Prompt or userContent is required",
       path: ["prompt"]
     });
   }
 });
-var UsageTokensSchema = z4.object({
-  prompt: z4.number().min(0),
-  completion: z4.number().min(0)
+var UsageTokensSchema = z6.object({
+  prompt: z6.number().min(0),
+  completion: z6.number().min(0)
 });
-var TestPricingUsedSchema = z4.object({
-  promptPerToken: z4.number().nullable().optional(),
-  completionPerToken: z4.number().nullable().optional(),
-  promptPerMillion: z4.number().nullable().optional(),
-  completionPerMillion: z4.number().nullable().optional()
+var TestPricingUsedSchema = z6.object({
+  promptPerToken: z6.number().nullable().optional(),
+  completionPerToken: z6.number().nullable().optional(),
+  promptPerMillion: z6.number().nullable().optional(),
+  completionPerMillion: z6.number().nullable().optional()
 });
-var TestModelMetadataSchema = z4.object({
-  id: z4.string(),
-  name: z4.string(),
-  created: z4.number().nullable().optional(),
-  createdAt: z4.string().nullable().optional(),
+var TestModelMetadataSchema = z6.object({
+  id: z6.string(),
+  name: z6.string(),
+  created: z6.number().nullable().optional(),
+  createdAt: z6.string().nullable().optional(),
   pricingUsed: TestPricingUsedSchema.optional()
 });
-var TestResultSuccessSchema = z4.object({
-  modelId: z4.string(),
-  resolvedModelId: z4.string().optional(),
-  ok: z4.literal(true),
+var TestResultSuccessSchema = z6.object({
+  modelId: z6.string(),
+  resolvedModelId: z6.string().optional(),
+  ok: z6.literal(true),
   model: TestModelMetadataSchema,
-  response: z4.string(),
-  latencyMs: z4.number().min(0),
+  response: z6.string(),
+  latencyMs: z6.number().min(0),
   tokens: UsageTokensSchema,
-  cost: z4.number().nullable().optional(),
-  truncated: z4.boolean().optional()
+  cost: z6.number().nullable().optional(),
+  truncated: z6.boolean().optional()
 });
-var TestResultFailureSchema = z4.object({
-  modelId: z4.string(),
-  resolvedModelId: z4.string().optional(),
-  ok: z4.literal(false),
+var TestResultFailureSchema = z6.object({
+  modelId: z6.string(),
+  resolvedModelId: z6.string().optional(),
+  ok: z6.literal(false),
   model: TestModelMetadataSchema,
-  error: z4.string(),
-  latencyMs: z4.number().min(0)
+  error: z6.string(),
+  latencyMs: z6.number().min(0)
 });
-var TestResultSchema = z4.discriminatedUnion("ok", [
+var TestResultSchema = z6.discriminatedUnion("ok", [
   TestResultSuccessSchema,
   TestResultFailureSchema
 ]);
-var TestEstimateResultSchema = z4.object({
-  modelId: z4.string(),
-  resolvedModelId: z4.string().optional(),
+var TestEstimateResultSchema = z6.object({
+  modelId: z6.string(),
+  resolvedModelId: z6.string().optional(),
   model: TestModelMetadataSchema,
   tokens: UsageTokensSchema,
-  estimatedCost: z4.number().nullable().optional()
+  estimatedCost: z6.number().nullable().optional()
 });
-var TestDryRunResponseSchema = z4.object({
-  dryRun: z4.literal(true),
-  results: z4.array(TestEstimateResultSchema),
-  disclaimer: z4.string()
+var TestDryRunResponseSchema = z6.object({
+  dryRun: z6.literal(true),
+  results: z6.array(TestEstimateResultSchema),
+  disclaimer: z6.string()
 });
-var TestLiveResponseSchema = z4.object({
-  results: z4.array(TestResultSchema)
+var TestLiveResponseSchema = z6.object({
+  results: z6.array(TestResultSchema)
 });
-var TestResponseSchema = z4.union([TestDryRunResponseSchema, TestLiveResponseSchema]);
+var TestResponseSchema = z6.union([TestDryRunResponseSchema, TestLiveResponseSchema]);
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z5 } from "zod";
+import { z as z7 } from "zod";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://index9.dev";
@@ -859,7 +1024,8 @@ async function handleSearchModels(ctx, args) {
   if (q.capabilitiesAll?.length) params.capabilitiesAll = q.capabilitiesAll.join(",");
   if (q.capabilitiesAny?.length) params.capabilitiesAny = q.capabilitiesAny.join(",");
   if (q.modality) params.modality = q.modality;
-  if (q.provider) params.provider = q.provider;
+  if (q.provider?.length) params.provider = q.provider.join(",");
+  if (q.excludeFree === true) params.excludeFree = "true";
   return callApi(
     ctx,
     buildUrl(ctx.baseUrl, API_PATHS.search, params),
@@ -879,6 +1045,26 @@ async function handleGetModels(ctx, args) {
     BatchModelLookupResponseSchema
   );
 }
+async function handleCompareModels(ctx, args) {
+  const parsed = CompareRequestSchema.safeParse(args);
+  if (!parsed.success) {
+    return toResponse({ error: parsed.error.message }, true);
+  }
+  return callApi(
+    ctx,
+    `${ctx.baseUrl}${API_PATHS.compare}`,
+    { method: "POST", headers: baseHeaders(ctx), body: JSON.stringify(parsed.data) },
+    CompareResponseSchema
+  );
+}
+async function handleListFacets(ctx, _args) {
+  return callApi(
+    ctx,
+    `${ctx.baseUrl}${API_PATHS.facets}`,
+    { method: "GET", headers: baseHeaders(ctx) },
+    FacetsResponseSchema
+  );
+}
 async function handleTestModels(ctx, args) {
   const parsed = TestRequestSchema.safeParse(args);
   if (!parsed.success) {
@@ -917,20 +1103,21 @@ async function createServer() {
       title: TOOLS.find_models.title,
       description: TOOLS.find_models.description,
       inputSchema: {
-        q: z5.string().min(1).optional().describe(PARAM_DESCRIPTIONS.q),
-        limit: z5.number().int().min(1).max(100).default(20).describe("Page size (1-100, default 20)."),
-        cursor: z5.string().min(1).optional().describe(PARAM_DESCRIPTIONS.cursor),
-        sortBy: z5.enum(["relevance", "created", "price"]).default("relevance").describe(PARAM_DESCRIPTIONS.sortBy),
-        sortOrder: z5.enum(["asc", "desc"]).optional().describe("Sort order. Defaults by sortBy."),
-        createdAfter: z5.string().optional().describe("Lower bound for model created timestamp."),
-        createdBefore: z5.string().optional().describe("Upper bound for model created timestamp."),
-        minPrice: z5.number().min(0).optional().describe("Minimum prompt price in USD per million tokens."),
-        maxPrice: z5.number().min(0).optional().describe("Maximum prompt price in USD per million tokens."),
-        minContext: z5.number().int().min(1).optional().describe("Minimum context window in tokens."),
-        capabilitiesAll: z5.array(z5.enum(CAPABILITIES)).optional().describe(PARAM_DESCRIPTIONS.capabilitiesAll),
-        capabilitiesAny: z5.array(z5.enum(CAPABILITIES)).optional().describe(PARAM_DESCRIPTIONS.capabilitiesAny),
-        modality: z5.enum(OUTPUT_MODALITIES).optional().describe(PARAM_DESCRIPTIONS.modality),
-        provider: z5.string().min(1).optional().describe(PARAM_DESCRIPTIONS.provider)
+        q: z7.string().min(1).optional().describe(PARAM_DESCRIPTIONS.q),
+        limit: z7.number().int().min(1).max(100).default(20).describe("Page size (1-100, default 20)."),
+        cursor: z7.string().min(1).optional().describe(PARAM_DESCRIPTIONS.cursor),
+        sortBy: z7.enum(["relevance", "created", "price"]).default("relevance").describe(PARAM_DESCRIPTIONS.sortBy),
+        sortOrder: z7.enum(["asc", "desc"]).optional().describe("Sort order. Defaults by sortBy."),
+        createdAfter: z7.string().optional().describe("Lower bound for model created timestamp."),
+        createdBefore: z7.string().optional().describe("Upper bound for model created timestamp."),
+        minPrice: z7.number().min(0).optional().describe("Minimum prompt price in USD per million tokens."),
+        maxPrice: z7.number().min(0).optional().describe("Maximum prompt price in USD per million tokens."),
+        minContext: z7.number().int().min(1).optional().describe("Minimum context window in tokens."),
+        capabilitiesAll: z7.array(z7.enum(CAPABILITIES)).optional().describe(PARAM_DESCRIPTIONS.capabilitiesAll),
+        capabilitiesAny: z7.array(z7.enum(CAPABILITIES)).optional().describe(PARAM_DESCRIPTIONS.capabilitiesAny),
+        modality: z7.enum(OUTPUT_MODALITIES).optional().describe(PARAM_DESCRIPTIONS.modality),
+        provider: z7.array(z7.string().min(1)).optional().describe(PARAM_DESCRIPTIONS.provider),
+        excludeFree: z7.boolean().optional().describe(PARAM_DESCRIPTIONS.excludeFree)
       },
       outputSchema: FindModelsToolResultSchema.shape,
       annotations: { readOnlyHint: true }
@@ -943,40 +1130,73 @@ async function createServer() {
       title: TOOLS.get_models.title,
       description: TOOLS.get_models.description,
       inputSchema: {
-        ids: z5.array(z5.string().min(1)).min(1).max(100).describe("Model identifiers or aliases. Up to 100."),
-        maxDescriptionChars: z5.number().int().min(0).max(2e3).optional().describe("Truncate descriptions to this many characters.")
+        ids: z7.array(z7.string().min(1)).min(1).max(100).describe("Model identifiers or aliases. Up to 100."),
+        maxDescriptionChars: z7.number().int().min(0).max(2e3).optional().describe("Truncate descriptions to this many characters.")
       },
       outputSchema: GetModelsToolResultSchema.shape,
       annotations: { readOnlyHint: true }
     },
     async (args) => handleGetModels(ctx, args)
   );
+  server.registerTool(
+    "compare_models",
+    {
+      title: TOOLS.compare_models.title,
+      description: TOOLS.compare_models.description,
+      inputSchema: {
+        ids: z7.array(z7.string().min(1)).min(2).max(LIMITS.compareModelsMax).describe(
+          `Model identifiers or aliases to compare (2-${LIMITS.compareModelsMax}). Same alias formats as get_models.`
+        ),
+        expectedPromptTokens: z7.number().int().min(1).optional().describe(
+          "Optional. When set with expectedCompletionTokens, computes total per-call cost for each model and picks cheapestForRealisticWorkload \u2014 closes the gap where promptPerMillion alone misleads when prompt:completion price ratios diverge."
+        ),
+        expectedCompletionTokens: z7.number().int().min(1).optional().describe(
+          "Optional. Pair with expectedPromptTokens to surface workloadCosts and cheapestForRealisticWorkload. Both must be set to enable workload costing."
+        )
+      },
+      outputSchema: CompareModelsToolResultSchema.shape,
+      annotations: { readOnlyHint: true }
+    },
+    async (args) => handleCompareModels(ctx, args)
+  );
+  server.registerTool(
+    "list_facets",
+    {
+      title: TOOLS.list_facets.title,
+      description: TOOLS.list_facets.description,
+      inputSchema: {},
+      outputSchema: ListFacetsToolResultSchema.shape,
+      annotations: { readOnlyHint: true }
+    },
+    async (args) => handleListFacets(ctx, args)
+  );
   server.registerTool(
     "test_model",
     {
       title: TOOLS.test_model.title,
       description: TOOLS.test_model.description,
       inputSchema: {
-        prompt: z5.string().min(1).optional().describe("Prompt sent to each model."),
-        userContent: z5.array(UserContentPartSchema).min(1).optional().describe("Multimodal user content. At least one of prompt or userContent required."),
-        dryRun: z5.boolean().optional().describe(
+        prompt: z7.string().min(1).optional().describe("Prompt sent to each model."),
+        userContent: z7.array(UserContentPartSchema).min(1).optional().describe("Multimodal user content. At least one of prompt or userContent required."),
+        dryRun: z7.boolean().optional().describe(
           "When true, returns estimated token usage and cost without calling OpenRouter (no API key required)."
         ),
-        expectedCompletionTokens: z5.number().int().min(1).optional().describe(PARAM_DESCRIPTIONS.expectedCompletionTokens),
-        models: z5.array(z5.string().min(1)).min(1).max(LIMITS.testModelsMax).describe(`Model IDs to evaluate (1-${LIMITS.testModelsMax}).`),
-        timeoutMs: z5.number().int().min(1).optional().describe("Per-model timeout in ms (default 15000, max 60000)."),
-        maxTokens: z5.number().int().min(1).optional().describe(
+        expectedPromptTokens: z7.number().int().min(1).optional().describe(PARAM_DESCRIPTIONS.expectedPromptTokens),
+        expectedCompletionTokens: z7.number().int().min(1).optional().describe(PARAM_DESCRIPTIONS.expectedCompletionTokens),
+        models: z7.array(z7.string().min(1)).min(1).max(LIMITS.testModelsMax).describe(`Model IDs to evaluate (1-${LIMITS.testModelsMax}).`),
+        timeoutMs: z7.number().int().min(1).optional().describe("Per-model timeout in ms (default 15000, max 60000)."),
+        maxTokens: z7.number().int().min(1).optional().describe(
           "Completion token cap. For reasoning-capable models, set \u2265 2000 (or omit) \u2014 reasoning tokens count against this before visible output, and too-low caps cause finish_reason=length."
         ),
-        systemPrompt: z5.string().min(1).optional().describe("System instruction prepended to prompt."),
-        temperature: z5.number().min(0).max(2).optional().describe("Sampling temperature (0-2)."),
-        topP: z5.number().gt(0).max(1).optional().describe("Nucleus sampling (0-1]."),
-        seed: z5.number().int().optional().describe("Seed for repeatable outputs."),
+        systemPrompt: z7.string().min(1).optional().describe("System instruction prepended to prompt."),
+        temperature: z7.number().min(0).max(2).optional().describe("Sampling temperature (0-2)."),
+        topP: z7.number().gt(0).max(1).optional().describe("Nucleus sampling (0-1]."),
+        seed: z7.number().int().optional().describe("Seed for repeatable outputs."),
         responseFormat: ResponseFormatSchema.describe(
           "Structured output shape request forwarded to OpenRouter (e.g., { type: 'json_object' })."
         ),
-        enforceJson: z5.boolean().optional().describe("When true, output must parse as JSON."),
-        retries: z5.number().int().min(0).max(3).optional().describe("Retries for transient failures.")
+        enforceJson: z7.boolean().optional().describe("When true, output must parse as JSON."),
+        retries: z7.number().int().min(0).max(3).optional().describe("Retries for transient failures.")
       },
       // No outputSchema: test_model returns a z.union of dry-run and live shapes.
       // The SDK supports only ZodRawShape | AnySchema for outputSchema; a discriminated-union

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": "0.3",
   "name": "index9",
-  "version": "5.0.0",
-  "description": "Search, inspect, and benchmark 300+ AI models from your editor",
+  "version": "5.2.0",
+  "description": "Discover, shortlist, compare, cost-model, and live-test 300+ AI models from your editor",
   "author": {
     "name": "Index9"
   },
@@ -28,6 +28,14 @@
       "name": "get_models",
       "description": "Get full model metadata by IDs or aliases (batch, up to 100)"
     },
+    {
+      "name": "compare_models",
+      "description": "Diff 2-10 models across pricing, context, capabilities, and tokenizer"
+    },
+    {
+      "name": "list_facets",
+      "description": "Enumerate available providers, capabilities, modalities, and tokenizers"
+    },
     {
       "name": "test_model",
       "description": "Run live inference or dry-run cost estimation across up to 10 models"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@index9/mcp",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "tsup": "^8.5.1",
     "typescript": "6.0.3",
     "vitest": "^4.1.5",
-    "@index9/core": "2.3.1"
+    "@index9/core": "2.3.2"
   },
   "engines": {
     "node": ">=20"