@aggc/or-info 0.2.6 → 0.2.8

package/README.md

@@ -7,6 +7,7 @@ to make informed decisions about which model to use.
 
 [![npm version](https://img.shields.io/npm/v/@aggc/or-info.svg)](https://www.npmjs.com/package/@aggc/or-info)
 [![CI](https://github.com/jmtrs/or-info/actions/workflows/ci.yml/badge.svg)](https://github.com/jmtrs/or-info/actions/workflows/ci.yml)
+[![smithery badge](https://smithery.ai/badge/aggc/or-info)](https://smithery.ai/servers/aggc/or-info)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 ## Install
@@ -180,12 +181,17 @@ or-info refresh         # Force-refresh OpenRouter catalog + LMArena ELO
 
 | Tool | Description |
 |------|-------------|
-| `get_model_info` | Pricing, context, architecture, features and LMArena ELO for a model |
-| `list_models` | List models with optional filter, sort and limit |
-| `get_benchmarks` | LMArena ELO score, global rank, vote count and confidence interval for a model |
-| `compare_models` | Side-by-side comparison of two models |
-| `best_for_task` | Ranked top models for coding/reasoning/general/vision/cheap |
-| `refresh_cache` | Force-refresh OpenRouter catalog + LMArena ELO |
+| `models.get` | Pricing, context, architecture, features and LMArena ELO for a model |
+| `models.list` | List models with optional filter, sort and limit |
+| `models.compare` | Side-by-side comparison of two models |
+| `models.top` | Ranked top models for coding/reasoning/general/vision/cheap |
+| `benchmarks.get` | LMArena ELO score, global rank, vote count and confidence interval for a model |
+| `cache.refresh` | Force-refresh OpenRouter catalog + LMArena ELO |
+
+Legacy flat names (`get_model_info`, `list_models`, `get_benchmarks`,
+`compare_models`, `best_for_task`, `refresh_cache`) are still advertised in
+`tools/list` as deprecated aliases (same schemas, prefixed `[Deprecated]`)
+and remain callable. The dot-notation names are the canonical ones.
 
 ### Register in Claude Code
 

package/mcp/server.mjs

@@ -6,9 +6,38 @@ import { getElo, getAllElo, loadLeaderboard } from '../lib/lmarena.mjs';
 import { rankModels } from '../lib/scorer.mjs';
 import { getApiKey } from '../lib/secrets.mjs';
 
-const TOOLS = [
+const MODEL_SUMMARY_SCHEMA = {
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    name: { type: 'string' },
+    input_per_m: { type: ['number', 'null'], description: 'Input price per 1M tokens (USD)' },
+    output_per_m: { type: ['number', 'null'], description: 'Output price per 1M tokens (USD)' },
+    image_per_m: { type: ['number', 'null'] },
+    cache_read_per_m: { type: ['number', 'null'] },
+    context_length: { type: ['integer', 'null'] },
+    features: { type: 'array', items: { type: 'string' } },
+    modality: { type: ['string', 'null'] },
+    tokenizer: { type: ['string', 'null'] },
+    max_output_tokens: { type: ['integer', 'null'] },
+    supported_parameters: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+const ELO_SCHEMA = { type: ['object', 'null'], description: 'LMArena ELO entry or null when not tracked' };
+
+const TOOL_ALIASES = {
+  get_model_info: 'models.get',
+  list_models: 'models.list',
+  compare_models: 'models.compare',
+  best_for_task: 'models.top',
+  get_benchmarks: 'benchmarks.get',
+  refresh_cache: 'cache.refresh',
+};
+
+const CANONICAL_TOOLS = [
   {
-    name: 'get_model_info',
+    name: 'models.get',
     description: 'Get pricing, context length, architecture and features for a specific OpenRouter model',
     inputSchema: {
       type: 'object',
@@ -17,9 +46,19 @@ const TOOLS = [
       },
       required: ['model_id'],
     },
+    outputSchema: {
+      type: 'object',
+      properties: { ...MODEL_SUMMARY_SCHEMA.properties, lmarena_elo: ELO_SCHEMA },
+    },
+    annotations: {
+      title: 'Get model',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
   },
   {
-    name: 'list_models',
+    name: 'models.list',
     description: 'List OpenRouter models with pricing. Optionally filter by name/id, sort, and limit results.',
     inputSchema: {
       type: 'object',
@@ -30,9 +69,23 @@ const TOOLS = [
         free_only: { type: 'boolean', description: 'Return only free models' },
       },
     },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        total: { type: 'integer' },
+        models: { type: 'array', items: MODEL_SUMMARY_SCHEMA },
+      },
+      required: ['total', 'models'],
+    },
+    annotations: {
+      title: 'List models',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
   },
   {
-    name: 'get_benchmarks',
+    name: 'benchmarks.get',
     description: 'Get LMArena ELO ranking for a model: score, global rank, vote count and confidence interval',
     inputSchema: {
       type: 'object',
@@ -41,9 +94,23 @@ const TOOLS = [
       },
       required: ['model_id'],
     },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        model_id: { type: 'string' },
+        lmarena_elo: ELO_SCHEMA,
+      },
+      required: ['model_id'],
+    },
+    annotations: {
+      title: 'Get benchmark',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
   },
   {
-    name: 'compare_models',
+    name: 'models.compare',
     description: 'Side-by-side comparison of two models: pricing, context, benchmarks and features',
     inputSchema: {
       type: 'object',
@@ -53,9 +120,23 @@ const TOOLS = [
       },
       required: ['model_a', 'model_b'],
     },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        a: { type: 'object', properties: { ...MODEL_SUMMARY_SCHEMA.properties, lmarena_elo: ELO_SCHEMA } },
+        b: { type: 'object', properties: { ...MODEL_SUMMARY_SCHEMA.properties, lmarena_elo: ELO_SCHEMA } },
+      },
+      required: ['a', 'b'],
+    },
+    annotations: {
+      title: 'Compare models',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
   },
   {
-    name: 'best_for_task',
+    name: 'models.top',
     description: 'Rank the best models for a specific task, optionally within a price budget',
     inputSchema: {
       type: 'object',
@@ -73,14 +154,68 @@ const TOOLS = [
       },
       required: ['task'],
     },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        task: { type: 'string' },
+        results: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: { ...MODEL_SUMMARY_SCHEMA.properties, score: { type: 'number' }, lmarena_elo: ELO_SCHEMA },
+          },
+        },
+      },
+      required: ['task', 'results'],
+    },
+    annotations: {
+      title: 'Top models for task',
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
   },
   {
-    name: 'refresh_cache',
+    name: 'cache.refresh',
     description: 'Force-refresh the local cache: OpenRouter model catalog + LMArena ELO data',
     inputSchema: { type: 'object', properties: {} },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        refreshed: { type: 'boolean' },
+        models_count: { type: 'integer' },
+        elo_entries: { type: 'integer' },
+      },
+      required: ['refreshed', 'models_count', 'elo_entries'],
+    },
+    annotations: {
+      title: 'Refresh cache',
+      readOnlyHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
   },
 ];
 
+// Legacy flat names kept advertised in tools/list for discoverability,
+// derived from the canonical tools so input/output schemas stay in sync.
+const LEGACY_BY_CANONICAL = Object.fromEntries(
+  Object.entries(TOOL_ALIASES).map(([legacy, canonical]) => [canonical, legacy])
+);
+
+const LEGACY_TOOLS = CANONICAL_TOOLS.flatMap((tool) => {
+  const legacyName = LEGACY_BY_CANONICAL[tool.name];
+  if (!legacyName) return [];
+  return [{
+    ...tool,
+    name: legacyName,
+    description: `[Deprecated] Alias of \`${tool.name}\`. Use \`${tool.name}\` instead.`,
+    annotations: { ...tool.annotations, title: `[Deprecated] ${tool.annotations.title}` },
+  }];
+});
+
+const TOOLS = [...CANONICAL_TOOLS, ...LEGACY_TOOLS];
+
 function safeModelSummary(model) {
   const price = pricePerMillion(model);
   return {
@@ -99,8 +234,11 @@ function safeModelSummary(model) {
   };
 }
 
-function textContent(obj) {
-  return [{ type: 'text', text: JSON.stringify(obj, null, 2) }];
+function result(obj) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }],
+    structuredContent: obj,
+  };
 }
 
 function errorContent(msg) {
@@ -108,19 +246,22 @@ function errorContent(msg) {
 }
 
 async function handleTool(name, args) {
+  // Accept legacy flat names (get_model_info, list_models, ...) by mapping
+  // them to the dot-notation canonical names exposed in tools/list.
+  name = TOOL_ALIASES[name] ?? name;
   const key = await getApiKey();
 
-  if (name === 'get_model_info') {
+  if (name === 'models.get') {
     const { model_id } = args;
     if (!model_id || typeof model_id !== 'string') return errorContent('model_id is required');
     const models = await fetchModels({ apiKey: key });
     const model = findModel(models, model_id);
     if (!model) return errorContent(`Model not found: ${model_id}`);
     const elo = await getElo(model_id);
-    return { content: textContent({ ...safeModelSummary(model), lmarena_elo: elo ?? null }) };
+    return result({ ...safeModelSummary(model), lmarena_elo: elo ?? null });
   }
 
-  if (name === 'list_models') {
+  if (name === 'models.list') {
     const filter = String(args.filter ?? '').toLowerCase();
     const sortBy = args.sort_by ?? 'name';
     const limit = Math.min(200, Math.max(1, args.limit ?? 50));
@@ -135,17 +276,17 @@ async function handleTool(name, args) {
     else models.sort((a, b) => a.id.localeCompare(b.id));
 
     models = models.slice(0, limit);
-    return { content: textContent({ total: models.length, models: models.map(safeModelSummary) }) };
+    return result({ total: models.length, models: models.map(safeModelSummary) });
   }
 
-  if (name === 'get_benchmarks') {
+  if (name === 'benchmarks.get') {
     const { model_id } = args;
     if (!model_id || typeof model_id !== 'string') return errorContent('model_id is required');
     const elo = await getElo(model_id);
-    return { content: textContent({ model_id, lmarena_elo: elo ?? null }) };
+    return result({ model_id, lmarena_elo: elo ?? null });
   }
 
-  if (name === 'compare_models') {
+  if (name === 'models.compare') {
     const { model_a, model_b } = args;
     if (!model_a || !model_b) return errorContent('model_a and model_b are required');
     const [models, eloA, eloB] = await Promise.all([
@@ -157,25 +298,25 @@ async function handleTool(name, args) {
     const mB = findModel(models, model_b);
     if (!mA) return errorContent(`Model not found: ${model_a}`);
     if (!mB) return errorContent(`Model not found: ${model_b}`);
-    return { content: textContent({ a: { ...safeModelSummary(mA), lmarena_elo: eloA }, b: { ...safeModelSummary(mB), lmarena_elo: eloB } }) };
+    return result({ a: { ...safeModelSummary(mA), lmarena_elo: eloA }, b: { ...safeModelSummary(mB), lmarena_elo: eloB } });
   }
 
-  if (name === 'best_for_task') {
+  if (name === 'models.top') {
     const task = args.task ?? 'general';
     const limit = Math.min(20, Math.max(1, args.limit ?? 5));
     const maxPrice = args.max_price_per_m_output ?? undefined;
 
     const [models, allElo] = await Promise.all([fetchModels({ apiKey: key }), getAllElo()]);
     const ranked = rankModels(models, allElo, { task, maxPricePerMOutput: maxPrice, limit });
-    return { content: textContent({ task, results: ranked.map((r) => ({ ...safeModelSummary(r.model), score: r.score, lmarena_elo: r.eloEntry })) }) };
+    return result({ task, results: ranked.map((r) => ({ ...safeModelSummary(r.model), score: r.score, lmarena_elo: r.eloEntry })) });
   }
 
-  if (name === 'refresh_cache') {
+  if (name === 'cache.refresh') {
     const [models, elo] = await Promise.all([
       fetchModels({ force: true, apiKey: key }),
       loadLeaderboard({ force: true }),
     ]);
-    return { content: textContent({ refreshed: true, models_count: models.length, elo_entries: elo.length }) };
+    return result({ refreshed: true, models_count: models.length, elo_entries: elo.length });
   }
 
   return errorContent(`Unknown tool: ${name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aggc/or-info",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "CLI + MCP server for OpenRouter models: prices, benchmarks, context and comparisons",
   "type": "module",
   "engines": {