@agentic.artists/modelshortlist 0.2.1

package/lib/openrouter.js

@@ -0,0 +1,276 @@
+import { fetchJson } from './http.js'
+
+const MODELS_URL = 'https://openrouter.ai/api/v1/models'
+const ZDR_URL = 'https://openrouter.ai/api/v1/endpoints/zdr'
+
+function requireApiKey() {
+  const apiKey = process.env.OPENROUTER_API_KEY
+  if (!apiKey) {
+    throw new Error('OPENROUTER_API_KEY is not configured')
+  }
+  return apiKey
+}
+
+function authHeaders() {
+  return {
+    authorization: `Bearer ${requireApiKey()}`,
+    accept: 'application/json',
+  }
+}
+
+export async function fetchOpenRouterModels() {
+  const { body } = await fetchJson(MODELS_URL, { headers: authHeaders() })
+
+  if (!Array.isArray(body?.data)) {
+    throw new Error('Unexpected OpenRouter models response: data is not an array')
+  }
+
+  return body.data
+}
+
+export async function fetchOpenRouterZdrEndpoints() {
+  const { body } = await fetchJson(ZDR_URL, { headers: authHeaders() })
+
+  if (!Array.isArray(body?.data)) {
+    throw new Error('Unexpected OpenRouter ZDR response: data is not an array')
+  }
+
+  return body.data
+}
+
+function finiteNumbers(values) {
+  return values
+    .filter((value) => value !== null && value !== undefined && value !== '')
+    .map(Number)
+    .filter(Number.isFinite)
+}
+
+function minOrNull(values) {
+  const nums = finiteNumbers(values)
+  return nums.length ? Math.min(...nums) : null
+}
+
+function maxOrNull(values) {
+  const nums = finiteNumbers(values)
+  return nums.length ? Math.max(...nums) : null
+}
+
+function medianOrNull(values) {
+  const nums = finiteNumbers(values).sort((a, b) => a - b)
+  if (!nums.length) return null
+  const mid = Math.floor(nums.length / 2)
+  return nums.length % 2 ? nums[mid] : (nums[mid - 1] + nums[mid]) / 2
+}
+
+function pricePerMillion(value) {
+  if (value === null || value === undefined || value === '') return null
+  const n = Number(value)
+  return Number.isFinite(n) ? n * 1_000_000 : null
+}
+
+function supportsToolUse(parameters = []) {
+  const set = new Set(parameters.map((v) => String(v).toLowerCase()))
+  return set.has('tools') || set.has('tool_choice')
+}
+
+function numberOrNull(value) {
+  if (value === null || value === undefined || value === '') return null
+  const n = Number(value)
+  return Number.isFinite(n) ? n : null
+}
+
+function compactZdrEndpoint(row) {
+  return {
+    provider: row.provider_name ?? null,
+    context_length: numberOrNull(row.context_length),
+    max_prompt_tokens: numberOrNull(row.max_prompt_tokens),
+    max_completion_tokens: numberOrNull(row.max_completion_tokens),
+    supports_tools: supportsToolUse(row.supported_parameters),
+    supported_parameters: (row.supported_parameters ?? []).map(String).sort(),
+    pricing_usd_per_1m_tokens: {
+      input: pricePerMillion(row.pricing?.prompt),
+      output: pricePerMillion(row.pricing?.completion),
+    },
+    performance: {
+      latency_p50_seconds: numberOrNull(row.latency_last_30m?.p50),
+      throughput_p50_tokens_per_second:
+        numberOrNull(row.throughput_last_30m?.p50),
+      uptime_last_1d_percent: numberOrNull(row.uptime_last_1d),
+    },
+  }
+}
+
+export function groupZdrEndpointsByModel(endpoints) {
+  const grouped = new Map()
+
+  for (const endpoint of endpoints) {
+    if (!endpoint?.model_id) continue
+    const list = grouped.get(endpoint.model_id) ?? []
+    list.push(endpoint)
+    grouped.set(endpoint.model_id, list)
+  }
+
+  return [...grouped.entries()].map(([modelId, rows]) => {
+    const endpointOptions = rows.map(compactZdrEndpoint)
+    const providers = [...new Set(rows.map((row) => row.provider_name).filter(Boolean))]
+    const toolOptions = endpointOptions.filter((row) => row.supports_tools)
+    const toolProviders = [...new Set(toolOptions.map((row) => row.provider).filter(Boolean))]
+    const parameterSets = rows.map(
+      (row) => new Set((row.supported_parameters ?? []).map(String)),
+    )
+    const union = [...new Set(rows.flatMap((row) => row.supported_parameters ?? []))].sort()
+    const intersection = parameterSets.length
+      ? [...parameterSets[0]].filter((value) =>
+          parameterSets.every((set) => set.has(value)),
+        ).sort()
+      : []
+
+    return {
+      model_id: modelId,
+      model_name: rows.find((row) => row.model_name)?.model_name ?? modelId.split('/').pop(),
+      author: modelId.includes('/') ? modelId.split('/')[0] : null,
+      zdr: true,
+      zdr_endpoint_count: rows.length,
+      zdr_providers: providers.sort(),
+      context: {
+        min_endpoint_context_length: minOrNull(endpointOptions.map((row) => row.context_length)),
+        max_endpoint_context_length: maxOrNull(endpointOptions.map((row) => row.context_length)),
+        max_tool_capable_context_length:
+          maxOrNull(toolOptions.map((row) => row.context_length)),
+        max_prompt_tokens: maxOrNull(endpointOptions.map((row) => row.max_prompt_tokens)),
+        max_completion_tokens:
+          maxOrNull(endpointOptions.map((row) => row.max_completion_tokens)),
+      },
+      capabilities: {
+        supports_tools_on_any_zdr_endpoint: toolProviders.length > 0,
+        tool_capable_zdr_providers: toolProviders.sort(),
+        supported_parameters_union: union,
+        supported_parameters_all_zdr_endpoints: intersection,
+      },
+      openrouter_zdr_pricing_usd_per_1m_tokens: {
+        lowest_input:
+          minOrNull(endpointOptions.map((row) => row.pricing_usd_per_1m_tokens.input)),
+        median_input:
+          medianOrNull(endpointOptions.map((row) => row.pricing_usd_per_1m_tokens.input)),
+        lowest_output:
+          minOrNull(endpointOptions.map((row) => row.pricing_usd_per_1m_tokens.output)),
+        median_output:
+          medianOrNull(endpointOptions.map((row) => row.pricing_usd_per_1m_tokens.output)),
+      },
+      openrouter_zdr_performance: {
+        best_latency_p50_seconds:
+          minOrNull(endpointOptions.map((row) => row.performance.latency_p50_seconds)),
+        median_endpoint_latency_p50_seconds:
+          medianOrNull(endpointOptions.map((row) => row.performance.latency_p50_seconds)),
+        best_throughput_p50_tokens_per_second:
+          maxOrNull(endpointOptions.map((row) => row.performance.throughput_p50_tokens_per_second)),
+        median_endpoint_throughput_p50_tokens_per_second:
+          medianOrNull(endpointOptions.map((row) => row.performance.throughput_p50_tokens_per_second)),
+        best_uptime_last_1d_percent:
+          maxOrNull(endpointOptions.map((row) => row.performance.uptime_last_1d_percent)),
+        worst_uptime_last_1d_percent:
+          minOrNull(endpointOptions.map((row) => row.performance.uptime_last_1d_percent)),
+      },
+      zdr_endpoint_options: endpointOptions,
+    }
+  })
+}
+
+function compactCatalogModel(row) {
+  const parameters = (row.supported_parameters ?? []).map(String).sort()
+  const contextLength = numberOrNull(row.top_provider?.context_length ?? row.context_length)
+
+  return {
+    model_id: row.id,
+    model_name: row.name ?? row.id?.split('/').pop() ?? row.id,
+    author: row.id?.includes('/') ? row.id.split('/')[0] : null,
+    openrouter_catalog: {
+      context_length: contextLength,
+      max_completion_tokens: numberOrNull(row.top_provider?.max_completion_tokens),
+      supports_tools: supportsToolUse(parameters),
+      supported_parameters: parameters,
+      pricing_usd_per_1m_tokens: {
+        input: pricePerMillion(row.pricing?.prompt),
+        output: pricePerMillion(row.pricing?.completion),
+      },
+      created: numberOrNull(row.created),
+      canonical_slug: row.canonical_slug ?? row.id ?? null,
+    },
+  }
+}
+
+export function buildOpenRouterCatalog(modelRows, zdrEndpointRows = []) {
+  const zdrByModel = new Map(
+    groupZdrEndpointsByModel(zdrEndpointRows).map((model) => [model.model_id, model]),
+  )
+
+  return modelRows
+    .filter((row) => row?.id)
+    .map((row) => {
+      const model = compactCatalogModel(row)
+      const zdr = zdrByModel.get(model.model_id)
+      return {
+        ...model,
+        zdr: Boolean(zdr),
+        zdr_endpoint_count: zdr?.zdr_endpoint_count ?? 0,
+        zdr_providers: zdr?.zdr_providers ?? [],
+        zdr_context: zdr?.context ?? null,
+        zdr_capabilities: zdr?.capabilities ?? null,
+        openrouter_zdr_pricing_usd_per_1m_tokens:
+          zdr?.openrouter_zdr_pricing_usd_per_1m_tokens ?? null,
+        openrouter_zdr_performance: zdr?.openrouter_zdr_performance ?? null,
+        zdr_endpoint_options: zdr?.zdr_endpoint_options ?? [],
+      }
+    })
+}
+
+export function modelCatalogSatisfies(model, constraints = {}) {
+  const catalog = model.openrouter_catalog ?? {}
+  if (constraints.tools === true && !catalog.supports_tools) return false
+  if (
+    constraints.minContext != null &&
+    (catalog.context_length == null || catalog.context_length < constraints.minContext)
+  ) {
+    return false
+  }
+  if (
+    constraints.maxInputPrice != null &&
+    (catalog.pricing_usd_per_1m_tokens?.input == null ||
+      catalog.pricing_usd_per_1m_tokens.input > constraints.maxInputPrice)
+  ) {
+    return false
+  }
+  if (
+    constraints.maxOutputPrice != null &&
+    (catalog.pricing_usd_per_1m_tokens?.output == null ||
+      catalog.pricing_usd_per_1m_tokens.output > constraints.maxOutputPrice)
+  ) {
+    return false
+  }
+  return true
+}
+
+export function endpointSatisfies(endpoint, constraints = {}) {
+  if (constraints.tools === true && !endpoint.supports_tools) return false
+  if (
+    constraints.minContext != null &&
+    (endpoint.context_length == null || endpoint.context_length < constraints.minContext)
+  ) {
+    return false
+  }
+  if (
+    constraints.maxInputPrice != null &&
+    (endpoint.pricing_usd_per_1m_tokens?.input == null ||
+      endpoint.pricing_usd_per_1m_tokens.input > constraints.maxInputPrice)
+  ) {
+    return false
+  }
+  if (
+    constraints.maxOutputPrice != null &&
+    (endpoint.pricing_usd_per_1m_tokens?.output == null ||
+      endpoint.pricing_usd_per_1m_tokens.output > constraints.maxOutputPrice)
+  ) {
+    return false
+  }
+  return true
+}

package/mcp/server.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { McpServer } from '@modelcontextprotocol/server'
+import { serveStdio } from '@modelcontextprotocol/server/stdio'
+import * as z from 'zod/v4'
+import { getMergedCatalog } from '../lib/catalog.js'
+import { endpointSatisfies, modelCatalogSatisfies } from '../lib/openrouter.js'
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+loadLocalEnv(path.join(ROOT, '.env.local'))
+
+function loadLocalEnv(filePath) {
+  if (!fs.existsSync(filePath)) return
+  const text = fs.readFileSync(filePath, 'utf8')
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+    const equals = line.indexOf('=')
+    if (equals <= 0) continue
+    const key = line.slice(0, equals).trim()
+    let value = line.slice(equals + 1).trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    if (process.env[key] == null) process.env[key] = value
+  }
+}
+
+function requireLocalSecrets() {
+  const missing = [
+    'ARTIFICIAL_ANALYSIS_API_KEY',
+    'OPENROUTER_API_KEY',
+  ].filter((key) => !process.env[key])
+
+  if (missing.length) {
+    throw new Error(
+      `Missing ${missing.join(', ')}. Create ${path.join(ROOT, '.env.local')} from .env.local.example.`,
+    )
+  }
+}
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function min(values) {
+  const nums = values.map(num).filter((value) => value != null)
+  return nums.length ? Math.min(...nums) : null
+}
+
+function max(values) {
+  const nums = values.map(num).filter((value) => value != null)
+  return nums.length ? Math.max(...nums) : null
+}
+
+function compactCandidate(model, { requiresZdr = false, eligibleZdrEndpoints = [] } = {}) {
+  const aa = model.artificial_analysis
+  const zdrEndpoints = requiresZdr ? eligibleZdrEndpoints : model.zdr_endpoint_options ?? []
+
+  return {
+    model_id: model.model_id,
+    model_name: model.model_name,
+    creator: aa?.creator ?? model.author ?? null,
+    release_date: aa?.release_date ?? null,
+    artificial_analysis: aa
+      ? {
+          intelligence_index: aa.evaluations?.intelligence_index ?? null,
+          coding_index: aa.evaluations?.coding_index ?? null,
+          agentic_index: aa.evaluations?.agentic_index ?? null,
+          price_usd_per_1m_tokens: aa.pricing_usd_per_1m_tokens ?? null,
+          median_performance: aa.performance ?? null,
+        }
+      : null,
+    openrouter: {
+      catalog: model.openrouter_catalog,
+      zdr: {
+        available: model.zdr === true,
+        requirement_applied: requiresZdr,
+        requirement_met: requiresZdr ? zdrEndpoints.length > 0 : null,
+        endpoint_count: model.zdr_endpoint_count ?? 0,
+        providers: model.zdr_providers ?? [],
+        eligible_endpoint_count: requiresZdr ? zdrEndpoints.length : null,
+        eligible_providers: requiresZdr
+          ? [...new Set(zdrEndpoints.map((e) => e.provider).filter(Boolean))].sort()
+          : null,
+        eligible_max_context_length: requiresZdr
+          ? max(zdrEndpoints.map((e) => e.context_length))
+          : null,
+        eligible_max_completion_tokens: requiresZdr
+          ? max(zdrEndpoints.map((e) => e.max_completion_tokens))
+          : null,
+        eligible_lowest_input_price_usd_per_1m_tokens: requiresZdr
+          ? min(zdrEndpoints.map((e) => e.pricing_usd_per_1m_tokens?.input))
+          : null,
+        eligible_lowest_output_price_usd_per_1m_tokens: requiresZdr
+          ? min(zdrEndpoints.map((e) => e.pricing_usd_per_1m_tokens?.output))
+          : null,
+        eligible_best_latency_p50_seconds: requiresZdr
+          ? min(zdrEndpoints.map((e) => e.performance?.latency_p50_seconds))
+          : null,
+        eligible_best_throughput_p50_tokens_per_second: requiresZdr
+          ? max(zdrEndpoints.map((e) => e.performance?.throughput_p50_tokens_per_second))
+          : null,
+        eligible_worst_uptime_last_1d_percent: requiresZdr
+          ? min(zdrEndpoints.map((e) => e.performance?.uptime_last_1d_percent))
+          : null,
+      },
+    },
+    reconciliation: model.reconciliation,
+  }
+}
+
+function filterCandidates(models, args) {
+  const query = args.query?.trim().toLowerCase() || null
+  const creator = args.creator?.trim().toLowerCase() || null
+  const requiresZdr = args.requires_zdr === true
+  const constraints = {
+    tools: args.requires_tools === true,
+    minContext: args.min_context ?? null,
+    maxInputPrice: args.max_input_price ?? null,
+    maxOutputPrice: args.max_output_price ?? null,
+  }
+
+  const results = []
+  for (const model of models) {
+    if (query) {
+      const haystack = [
+        model.model_id,
+        model.model_name,
+        model.artificial_analysis?.name,
+        model.artificial_analysis?.slug,
+      ].filter(Boolean).join(' ').toLowerCase()
+      if (!haystack.includes(query)) continue
+    }
+
+    if (creator) {
+      const creatorText = `${model.author ?? ''} ${model.artificial_analysis?.creator ?? ''}`.toLowerCase()
+      if (!creatorText.includes(creator)) continue
+    }
+
+    if (requiresZdr) {
+      const eligibleZdrEndpoints = (model.zdr_endpoint_options ?? []).filter((endpoint) =>
+        endpointSatisfies(endpoint, constraints),
+      )
+      if (eligibleZdrEndpoints.length === 0) continue
+      results.push(compactCandidate(model, { requiresZdr: true, eligibleZdrEndpoints }))
+      continue
+    }
+
+    if (!modelCatalogSatisfies(model, constraints)) continue
+    results.push(compactCandidate(model, { requiresZdr: false }))
+  }
+
+  return results.sort((a, b) => a.model_id.localeCompare(b.model_id))
+}
+
+const recommendationSchema = z.object({
+  use_case: z.string().min(3).describe(
+    'What the user needs the model to do. Preserve their actual workload and priorities in detail.',
+  ),
+  requires_zdr: z.boolean().default(false).describe(
+    'Set true only when the user explicitly requires Zero Data Retention (ZDR). Otherwise leave false so all OpenRouter models remain eligible.',
+  ),
+  requires_tools: z.boolean().default(false).describe(
+    'True when the workload requires tool/function calling.',
+  ),
+  min_context: z.number().int().positive().optional().describe(
+    'Minimum context window required.',
+  ),
+  max_input_price: z.number().nonnegative().optional().describe(
+    'Maximum acceptable OpenRouter input price in USD per 1M tokens.',
+  ),
+  max_output_price: z.number().nonnegative().optional().describe(
+    'Maximum acceptable OpenRouter output price in USD per 1M tokens.',
+  ),
+  creator: z.string().optional().describe('Optional model creator/provider family filter.'),
+  query: z.string().optional().describe('Optional model-name substring filter.'),
+  limit: z.number().int().min(1).max(100).default(50),
+  force_refresh: z.boolean().default(false).describe(
+    'Force fresh upstream API requests. Use sparingly because AA Free has a quota.',
+  ),
+})
+
+function createServer() {
+  const server = new McpServer({
+    name: 'modelshortlist',
+    version: '0.2.1',
+  })
+
+  server.registerTool(
+    'recommend_models',
+    {
+      title: 'Recommend AI models',
+      description:
+        'Use this whenever the user asks which AI model to use for a workload. It considers the full current OpenRouter model catalog and adds Artificial Analysis benchmark data when confidently matched. Zero Data Retention is optional and must only be enforced when the user explicitly requires ZDR. After calling this tool, YOU must make the recommendation based on the user use case; do not simply pick the first model or a single benchmark winner. Clearly attribute Artificial Analysis benchmark metrics and OpenRouter catalog/endpoint data.',
+      inputSchema: recommendationSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      try {
+        requireLocalSecrets()
+        const catalog = await getMergedCatalog({ forceRefresh: args.force_refresh })
+        const candidates = filterCandidates(catalog.models, args).slice(0, args.limit)
+        const requiresZdr = args.requires_zdr === true
+
+        const selectionInstructions = [
+          requiresZdr
+            ? 'ZDR is an explicit hard requirement. Only recommend candidates with a current ZDR endpoint that satisfies all hard constraints on that same endpoint.'
+            : 'ZDR is not a requirement for this request. Do not exclude a model because it lacks a ZDR endpoint; treat ZDR availability as optional metadata only.',
+          requiresZdr
+            ? 'If the selected model is called through OpenRouter, enforce provider.zdr=true in the actual inference request.'
+            : 'Do not add provider.zdr=true merely because ModelShortlist reports ZDR availability; only enforce it when the user requests ZDR.',
+          'Choose weights based on the stated use case rather than using a universal scoring formula.',
+          'For coding work, Artificial Analysis coding_index and agentic_index are usually more relevant than intelligence_index alone when those metrics are available.',
+          'For high-volume workloads, weigh OpenRouter pricing and relevant performance evidence heavily.',
+          'For interactive workloads, weigh latency when endpoint-level latency data is available.',
+          'Models without a confident Artificial Analysis match remain eligible; do not invent missing benchmark scores.',
+          'Distinguish Artificial Analysis benchmark/performance data from OpenRouter model catalog and endpoint data.',
+          'Recommend one primary model and normally two alternatives with explicit tradeoffs.',
+        ]
+
+        const payload = {
+          use_case: args.use_case,
+          zdr_required: requiresZdr,
+          constraint_basis: requiresZdr
+            ? 'current OpenRouter ZDR endpoints; hard constraints must be satisfied by the same endpoint'
+            : 'current OpenRouter model catalog; ZDR is not used as an eligibility filter',
+          selection_instructions: selectionInstructions,
+          generated_at: catalog.generated_at,
+          candidate_count: candidates.length,
+          candidates,
+          diagnostics: {
+            openrouter_model_count: catalog.diagnostics.openrouter_model_count,
+            openrouter_zdr_model_count: catalog.diagnostics.openrouter_zdr_model_count,
+            matched_model_count: catalog.diagnostics.matched_model_count,
+            unmatched_model_count: catalog.diagnostics.unmatched_model_count,
+            ambiguous_model_count: catalog.diagnostics.ambiguous_model_count,
+            aa_rate_limit: catalog.diagnostics.aa?.rateLimit ?? null,
+          },
+          attribution: {
+            artificial_analysis: 'https://artificialanalysis.ai/',
+            openrouter: 'https://openrouter.ai/',
+          },
+        }
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify(payload) }],
+        }
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `ModelShortlist error: ${error.message}` }],
+        }
+      }
+    },
+  )
+
+  server.registerTool(
+    'compare_models',
+    {
+      title: 'Compare specific AI models',
+      description:
+        'Use this after model discovery for a focused comparison of specific OpenRouter model IDs. It returns general OpenRouter catalog data, current ZDR availability, and Artificial Analysis metrics when confidently matched. ZDR is not assumed to be required.',
+      inputSchema: z.object({
+        model_ids: z.array(z.string()).min(2).max(12),
+        requires_zdr: z.boolean().default(false).describe(
+          'Set true only when the user explicitly requires Zero Data Retention.',
+        ),
+        force_refresh: z.boolean().default(false),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+      },
+    },
+    async ({ model_ids, requires_zdr, force_refresh }) => {
+      try {
+        requireLocalSecrets()
+        const catalog = await getMergedCatalog({ forceRefresh: force_refresh })
+        const wanted = new Set(model_ids)
+        const models = catalog.models
+          .filter((model) => wanted.has(model.model_id))
+          .map((model) => compactCandidate(model, {
+            requiresZdr: requires_zdr === true,
+            eligibleZdrEndpoints: model.zdr_endpoint_options ?? [],
+          }))
+        const found = new Set(models.map((model) => model.model_id))
+        const missing = model_ids.filter((id) => !found.has(id))
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              generated_at: catalog.generated_at,
+              zdr_required: requires_zdr === true,
+              models,
+              missing_model_ids: missing,
+              response_instruction:
+                'Attribute Artificial Analysis benchmark/performance metrics to Artificial Analysis and OpenRouter catalog/endpoint data to OpenRouter. Do not treat ZDR as required unless zdr_required is true.',
+              attribution: {
+                artificial_analysis: 'https://artificialanalysis.ai/',
+                openrouter: 'https://openrouter.ai/',
+              },
+            }),
+          }],
+        }
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `ModelShortlist error: ${error.message}` }],
+        }
+      }
+    },
+  )
+
+  server.registerTool(
+    'modelshortlist_status',
+    {
+      title: 'Check ModelShortlist status',
+      description:
+        'Use this to diagnose OpenRouter catalog coverage, model matching coverage, ZDR availability, or Artificial Analysis quota state.',
+      inputSchema: z.object({
+        include_unmatched: z.boolean().default(false),
+        force_refresh: z.boolean().default(false),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+      },
+    },
+    async ({ include_unmatched, force_refresh }) => {
+      try {
+        requireLocalSecrets()
+        const catalog = await getMergedCatalog({ forceRefresh: force_refresh })
+        const payload = {
+          generated_at: catalog.generated_at,
+          diagnostics: catalog.diagnostics,
+          unmatched: include_unmatched ? catalog.unmatched : undefined,
+          ambiguous: include_unmatched ? catalog.ambiguous : undefined,
+          cache: catalog.cache,
+        }
+        return {
+          content: [{ type: 'text', text: JSON.stringify(payload) }],
+        }
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `ModelShortlist error: ${error.message}` }],
+        }
+      }
+    },
+  )
+
+  return server
+}
+
+void serveStdio(createServer)
+console.error('ModelShortlist MCP server running on stdio')

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@agentic.artists/modelshortlist",
+  "version": "0.2.1",
+  "description": "A local BYOK MCP server that helps AI assistants shortlist models using OpenRouter catalog data and Artificial Analysis benchmarks, with optional ZDR filtering.",
+  "type": "module",
+  "license": "MIT",
+  "mcpName": "io.github.AgenticArtists/modelshortlist",
+  "bin": {
+    "modelshortlist": "bin/modelshortlist.js"
+  },
+  "files": [
+    "bin/",
+    "mcp/",
+    "lib/",
+    "config/",
+    "scripts/setup.js",
+    ".env.local.example",
+    "ATTRIBUTION.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgenticArtists/ModelShortlist.git"
+  },
+  "homepage": "https://modelshortlist.com",
+  "bugs": {
+    "url": "https://github.com/AgenticArtists/ModelShortlist/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openrouter",
+    "artificial-analysis",
+    "llm",
+    "model-selection",
+    "model-recommendation",
+    "zdr",
+    "ai"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "setup": "node scripts/setup.js",
+    "test": "node --test",
+    "check": "node --check bin/modelshortlist.js && node --check lib/artificial-analysis.js && node --check lib/openrouter.js && node --check lib/match.js && node --check lib/catalog.js && node --check lib/http.js && node --check mcp/server.js && node --check scripts/setup.js",
+    "pack:check": "npm pack --dry-run",
+    "mcp": "node mcp/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.5.4"
+  }
+}