@index9/mcp 4.0.1 → 5.0.0

package/dist/cli.js

@@ -109,19 +109,30 @@ Parameters:
 - limit: Page size
 - cursor: Opaque pagination cursor
 
-Scores: Results include a 'score' field (0-100). Higher = more relevant. The best match in each page scores 100; others are scaled proportionally. Combines semantic similarity and keyword matching. Null when sorting by price or date.
+Each result has: id, name, description, created (unix seconds), createdAt (ISO 8601), contextLength, maxOutputTokens, pricing.{promptPerMillion, completionPerMillion} (USD per million tokens, numbers), capabilities[], score.
 
-Use model IDs from results with get_models for full specs or test_model for live testing.`,
+Scores: 0-100, higher = more relevant. The best match in each page scores 100; others are scaled proportionally. Combines semantic similarity and keyword matching. Null when sorting by price or date.
+
+Pass result.id to get_models for full specs or to test_model for live testing.`,
     requiresKey: false
   },
   get_models: {
     name: "get_models",
     summary: "Get full model metadata by IDs or aliases (batch, up to 100)",
-    description: `Get complete specs for a model by ID. Returns pricing, context window, capabilities, architecture, and per-request limits.
+    description: `Get full specs for one or more models by id or alias. Accepts up to ${LIMITS.getModelsMax} ids per call \u2014 use this for batch comparison.
+
+Call after find_models to inspect candidates, or directly when the user names a model (format: 'provider/model-name').
 
-Call after find_models to get full details, or when the user provides a model ID (format: 'provider/model-name').
+Response: { results: (Model | null)[], missingIds: string[], resolvedAliases?: Record<alias, canonicalId>, ambiguousAliases?: Record<alias, 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
+- pricing: { promptPerMillion, completionPerMillion, requestUsd, imageUsd } \u2014 all USD, all numbers. Token prices are per million tokens; request/image are per unit.
+- architecture: { inputModalities[], outputModalities[], tokenizer, instructType }
+- capabilities[]: normalized capability flags (same values as find_models and capabilitiesAll/Any)
+- supportedParameters[]: OpenRouter parameters the model accepts (e.g., "temperature", "tools", "response_format")
 
-Returns 404 if model not found. Use find_models to discover valid IDs.`,
+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.`,
     requiresKey: false
   },
   test_model: {
@@ -140,9 +151,9 @@ Parameters:
 - prompt: Prompt text (required for dryRun; required for live unless userContent provided)
 - dryRun: If true, return cost estimates only
 - expectedCompletionTokens: Optional completion token estimate used by dryRun
-- max_tokens, systemPrompt, temperature, topP, seed, responseFormat, enforceJson, retries: Live-testing controls (ignored when dryRun=true)
+- maxTokens, systemPrompt, temperature, topP, seed, responseFormat, enforceJson, retries: Live-testing controls (ignored when dryRun=true)
 
-Use find_models or get_models first to identify model IDs.`,
+Results (live): each result carries modelId (the id you passed), resolvedModelId (canonical id, present when the input was an alias), ok, response, latencyMs, tokens { prompt, completion }, cost (USD; live from OpenRouter when available, else estimated from cached pricing), and truncated=true when finish_reason is "length". Use find_models or get_models first to identify model ids.`,
     requiresKey: true
   }
 };
@@ -150,15 +161,17 @@ 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.",
   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: `Comma-separated capabilities that must ALL be present on the model (AND logic). Valid values: ${CAPABILITIES.join(", ")}. Example: 'function_calling,vision'. Invalid values silently filter to zero results.`,
-  capabilitiesAny: `Comma-separated capabilities where at least ONE must be present (OR logic). Valid values: ${CAPABILITIES.join(", ")}. Example: 'vision,audio_input'. Invalid values silently filter to zero results.`,
-  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(", ")}.`,
+  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(", ")}.`,
   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 = {
   nav: {
     brand: "index9",
+    tools: "Tools",
+    howItWorks: "How it works",
     install: "Install",
     faq: "FAQ",
     github: "GitHub",
@@ -168,19 +181,47 @@ var SITE = {
     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.",
-    getStarted: "Install index9",
+    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"],
+    pricingNote: "Free. You only pay OpenRouter for live model calls.",
+    getStarted: "Add to your editor",
     seeHowItWorks: "See an example",
-    updatedBadge: "Pricing & specs refreshed "
+    updatedBadge: "Model pricing & specs from OpenRouter \u2014 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.",
+    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.'
+      },
+      {
+        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."
+      },
+      {
+        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."
+      }
+    ]
   },
   toolsSection: {
     label: "Tools",
-    heading: "Search, test, and compare",
+    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.",
     openRouterKey: "OpenRouter API key (live tests only)",
     noKeyRequired: "No API key required",
     requiresLabel: "Requires ",
     cards: [
       {
         name: "find_models",
+        action: "Search",
         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.`,
@@ -189,14 +230,16 @@ var SITE = {
       },
       {
         name: "get_models",
+        action: "Inspect",
         displayName: "get_models",
         fullName: null,
-        description: "Get current pricing, limits, and capabilities for any model. Updated from OpenRouter every 30 minutes.",
+        description: "Get current pricing, limits, and capabilities for any model. Synced from OpenRouter every 30 minutes.",
         badge: null,
         requiresKey: false
       },
       {
         name: "test_model",
+        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.",
@@ -234,7 +277,7 @@ var SITE = {
       },
       {
         question: "What's the project status?",
-        answer: "index9 is in active development. The core tools are stable and ready for daily use, and improvements ship regularly. Issues and feedback are tracked on GitHub.",
+        answer: "index9 is live and used daily. Core tools are stable. Improvements ship through changesets on GitHub; issues and feedback are welcome there.",
         link: null
       },
       {
@@ -246,7 +289,8 @@ var SITE = {
   },
   install: {
     label: "Setup",
-    heading: "Add to your MCP config",
+    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.",
     configs: [
       {
         id: "cursor-vscode",
@@ -288,6 +332,7 @@ var SITE = {
   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: [
@@ -439,16 +484,16 @@ var SearchQuerySchema = z2.object({
   minPrice: z2.number().min(0).optional(),
   maxPrice: z2.number().min(0).optional(),
   minContext: z2.number().int().min(1).optional(),
-  capabilitiesAll: z2.array(z2.string().min(1)).optional(),
-  capabilitiesAny: z2.array(z2.string().min(1)).optional(),
-  modality: z2.string().min(1).optional(),
+  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()
 }).strict();
 var SearchResultSchema = z2.object({
-  modelId: z2.string(),
+  id: z2.string(),
   name: z2.string(),
   description: z2.string(),
-  createdUnix: z2.number().nullable(),
+  created: z2.number().nullable(),
   createdAt: z2.string().nullable(),
   contextLength: z2.number().nullable(),
   maxOutputTokens: z2.number().nullable(),
@@ -480,7 +525,34 @@ var BatchModelLookupRequestSchema = z3.object({
   ids: z3.array(z3.string().min(1)).min(1, "ids are required").max(LIMITS.getModelsMax, `ids must contain between 1 and ${LIMITS.getModelsMax} model IDs`),
   maxDescriptionChars: z3.number().int().min(0).max(2e3).optional()
 }).strict();
-var ModelResponseSchema = z3.record(z3.string(), z3.unknown());
+var ModelPricingSchema = z3.object({
+  promptPerMillion: z3.number().nullable(),
+  completionPerMillion: z3.number().nullable(),
+  requestUsd: z3.number().nullable(),
+  imageUsd: z3.number().nullable()
+});
+var ModelArchitectureSchema = z3.object({
+  inputModalities: z3.array(z3.string()),
+  outputModalities: z3.array(z3.string()),
+  tokenizer: z3.string().nullable(),
+  instructType: z3.string().nullable()
+});
+var ModelResponseSchema = z3.object({
+  id: z3.string(),
+  canonicalSlug: z3.string().nullable(),
+  name: z3.string(),
+  description: z3.string(),
+  created: z3.number().nullable(),
+  createdAt: z3.string().nullable(),
+  knowledgeCutoff: z3.string().nullable(),
+  contextLength: z3.number().nullable(),
+  maxOutputTokens: z3.number().nullable(),
+  isModerated: z3.boolean().nullable(),
+  pricing: ModelPricingSchema,
+  architecture: ModelArchitectureSchema,
+  capabilities: z3.array(z3.string()),
+  supportedParameters: z3.array(z3.string())
+});
 var BatchModelLookupResponseSchema = z3.object({
   results: z3.array(ModelResponseSchema.nullable()),
   missingIds: z3.array(z3.string()),
@@ -540,7 +612,7 @@ var TestPricingUsedSchema = z4.object({
 var TestModelMetadataSchema = z4.object({
   id: z4.string(),
   name: z4.string(),
-  createdUnix: z4.number().nullable().optional(),
+  created: z4.number().nullable().optional(),
   createdAt: z4.string().nullable().optional(),
   pricingUsed: TestPricingUsedSchema.optional()
 });
@@ -552,7 +624,8 @@ var TestResultSuccessSchema = z4.object({
   response: z4.string(),
   latencyMs: z4.number().min(0),
   tokens: UsageTokensSchema,
-  cost: z4.number().nullable().optional()
+  cost: z4.number().nullable().optional(),
+  truncated: z4.boolean().optional()
 });
 var TestResultFailureSchema = z4.object({
   modelId: z4.string(),
@@ -593,6 +666,13 @@ function loadConfig() {
   const env = process.env.INDEX9_API_BASE_URL?.trim();
   const baseUrl = env || DEFAULT_BASE_URL;
   const normalized = baseUrl.replace(/\/$/, "");
+  try {
+    new URL(normalized);
+  } catch {
+    throw new Error(
+      `Invalid INDEX9_API_BASE_URL: ${normalized}. Expected an absolute URL such as https://index9.dev`
+    );
+  }
   return {
     baseUrl: normalized,
     apiToken: process.env.INDEX9_API_TOKEN?.trim() || void 0,
@@ -602,23 +682,62 @@ function loadConfig() {
 
 // src/client.ts
 var RETRY_DELAYS_MS = [1e3, 2e3, 4e3];
+var ATTEMPT_TIMEOUT_MS = 3e4;
 function isRetryable(status) {
   return status === 429 || status >= 500;
 }
 async function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+function isRetryableError(error) {
+  if (!(error instanceof Error)) return false;
+  if (error.name === "AbortError" || error.name === "TimeoutError") return true;
+  return error instanceof TypeError;
+}
+function toErrorMessage(error) {
+  if (error instanceof Error && error.message.trim()) return error.message;
+  return "Unknown error";
+}
 async function fetchWithRetry(url, options) {
   let lastResponse = null;
+  let lastError;
   for (let i = 0; i <= RETRY_DELAYS_MS.length; i++) {
-    const res = await fetch(url, options);
-    lastResponse = res;
-    if (res.ok || !isRetryable(res.status)) return res;
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => {
+      timeoutController.abort(new DOMException("Request timed out", "AbortError"));
+    }, ATTEMPT_TIMEOUT_MS);
+    const externalSignal = options.signal;
+    const onAbort = () => {
+      timeoutController.abort(
+        externalSignal?.reason ?? new DOMException("Request aborted", "AbortError")
+      );
+    };
+    if (externalSignal?.aborted) {
+      onAbort();
+    } else {
+      externalSignal?.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+      const res = await fetch(url, { ...options, signal: timeoutController.signal });
+      lastResponse = res;
+      if (res.ok || !isRetryable(res.status)) return res;
+    } catch (error) {
+      lastError = error;
+      if (!isRetryableError(error)) {
+        throw new Error(`Request failed: ${toErrorMessage(error)}`);
+      }
+    } finally {
+      clearTimeout(timeoutId);
+      externalSignal?.removeEventListener("abort", onAbort);
+    }
     if (i < RETRY_DELAYS_MS.length) {
       await sleep(RETRY_DELAYS_MS[i]);
     }
   }
-  return lastResponse;
+  if (lastResponse) return lastResponse;
+  throw new Error(
+    `Request failed after ${RETRY_DELAYS_MS.length + 1} attempts: ${toErrorMessage(lastError)}`
+  );
 }
 function buildUrl(baseUrl, path, params) {
   const url = new URL(path, baseUrl);
@@ -784,9 +903,9 @@ async function createServer() {
         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.string()).optional().describe(PARAM_DESCRIPTIONS.capabilitiesAll),
-        capabilitiesAny: z5.array(z5.string()).optional().describe(PARAM_DESCRIPTIONS.capabilitiesAny),
-        modality: z5.string().optional().describe(PARAM_DESCRIPTIONS.modality),
+        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)
       },
       annotations: { readOnlyHint: true }

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "index9",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Search, inspect, and benchmark 300+ AI models from your editor",
   "author": {
     "name": "Index9"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@index9/mcp",
-  "version": "4.0.1",
+  "version": "5.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,13 +20,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.6.0",
     "tsup": "^8.5.1",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
+    "vitest": "^4.1.5",
     "@index9/core": "2.3.1"
   },
   "engines": {
@@ -37,6 +38,6 @@
     "clean": "rm -rf dist",
     "lint": "tsc --noEmit",
     "start": "node dist/cli.js",
-    "test": "echo 'No tests in @index9/mcp'"
+    "test": "vitest run"
   }
 }