@opennodes/registry 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @opennodes/registry
+
+The OpenNodes Protocol (ONP) reference registry — an open, federatable discovery service for AI inference nodes.
+
+```bash
+npx @opennodes/registry                 # web app + API on http://127.0.0.1:4300
+ONP_DB=./registry.db npx @opennodes/registry          # persistent SQLite + persistent signing key
+ONP_DB=postgres://user:pass@host/db npx @opennodes/registry
+```
+
+What it does:
+
+- **Registration with proof of resource** — namespace challenge (HTTP or DNS TXT), Stage A conformance probes, Stage B identity fingerprinting / context verification / capacity ramp, Stage C continuous liveness and blind probes. Trust tiers: `unverified → community → verified` (+ `disputed`, `suspended`). Claimed ≠ measured ≠ attested — always labeled, never blended.
+- **Search and transparent ranking** (`/v0/offerings`, `sort=rank|price|ttft|tps`) with per-result `rank_explanation`; **enforceable estimates** (`POST /v0/estimate`) pinned to card revisions; the **advisor** (`POST /v0/recommend`).
+- **Catalog importers** — OpenRouter, Hugging Face Inference Providers, models.dev, the Ollama library — so search is useful on day one, with imported listings labeled and claimable by their operators.
+- **MCP surface** at `/mcp` and a signed **export feed** for federation.
+- **Web app** at `/`: OpenRouter-style catalog with model and node pages, hardware and measured performance, playground, multi-model chat (compare / jury / pipeline / iterative), the advisor, and the Node Builder.
+
+Environment: `PORT`, `ONP_DB`, `ONP_REGISTRY_KEY`, `ONP_ADMIN_TOKEN`, `ONP_ALLOW_PRIVATE=1` (dev only: permit localhost nodes), `ONP_STAGE_C=0`, `ONP_REIMPORT=1`.
+
+Part of [OpenNodes](https://opennodes.io) · [specification](https://github.com/opennodes-io/opennodes/tree/main/spec) · Apache-2.0.

package/bin.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { startRegistry } from './src/server.js';
+
+const dbPath = process.env.ONP_DB ?? ':memory:'; // sqlite path/:memory: or postgres:// URL
+const persistent = dbPath !== ':memory:' && !dbPath.startsWith('postgres');
+const registry = await startRegistry({
+  port: Number(process.env.PORT ?? 4300),
+  dbPath,
+  // Persistent signing identity: explicit path, or derived from a file db; pg deployments set ONP_REGISTRY_KEY.
+  keyPath: process.env.ONP_REGISTRY_KEY ?? (persistent ? `${dbPath}.key.pem` : (dbPath.startsWith('postgres') ? 'onp-registry-key.pem' : null)),
+  allowPrivateTargets: process.env.ONP_ALLOW_PRIVATE === '1', // dev only: permit localhost nodes
+  adminToken: process.env.ONP_ADMIN_TOKEN ?? null,
+  stageC: process.env.ONP_STAGE_C === '0' ? null : {
+    livenessIntervalMs: Number(process.env.ONP_LIVENESS_MS ?? 300_000),
+    blindIntervalMs: Number(process.env.ONP_BLIND_MS ?? 3_600_000),
+  },
+  reimport: process.env.ONP_REIMPORT === '1' ? {
+    intervalMs: Number(process.env.ONP_REIMPORT_MS ?? 6 * 3600 * 1000),
+    sources: (process.env.ONP_REIMPORT_SOURCES ?? 'openrouter,huggingface').split(','),
+  } : null,
+});
+if (process.env.ONP_ALLOW_PRIVATE === '1') console.log('WARNING: SSRF guard disabled (ONP_ALLOW_PRIVATE=1) — dev only');
+console.log(`opennodes registry listening at ${registry.origin}`);
+console.log(`health: ${registry.origin}/v0/health`);

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@opennodes/registry",
+  "version": "0.1.0",
+  "description": "OpenNodes (ONP) reference registry: node registration with proof-of-resource qualification (Stage A/B/C), transparent ranking, enforceable estimates, catalog importers (OpenRouter, Hugging Face, models.dev, Ollama), MCP surface, and the web app (catalog, chat, advisor, Node Builder)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "src/server.js",
+  "exports": { ".": "./src/server.js", "./src/*": "./src/*" },
+  "bin": { "onp-registry": "bin.js" },
+  "files": ["bin.js", "src", "README.md"],
+  "keywords": ["opennodes", "onp", "registry", "ai", "inference", "discovery", "mcp", "catalog"],
+  "homepage": "https://opennodes.io",
+  "repository": { "type": "git", "url": "git+https://github.com/opennodes-io/opennodes.git", "directory": "impl/packages/registry" },
+  "bugs": { "url": "https://github.com/opennodes-io/opennodes/issues" },
+  "engines": { "node": ">=22.5" },
+  "publishConfig": { "access": "public" },
+  "dependencies": { "@opennodes/core": "0.1.0", "pg": "^8.13.1" }
+}

package/src/export.js

@@ -0,0 +1,26 @@
+// DS-EXP-01: signed NDJSON mirror feed so downstream registries/aggregators can
+// replicate without re-crawling. Each line = { payload, jws } signed by this registry,
+// so provenance survives mirroring.
+import { signJson } from '@opennodes/core';
+
+export function exportRoutes(store, registryKeys) {
+  return [
+    ['GET', '/v0/export', async (req, res, { query }) => {
+      const since = query.get('since') ?? '';
+      res.writeHead(200, { 'content-type': 'application/x-ndjson' });
+      for (const node of await store.allNodes()) {
+        if (since && node.updated_at <= since) continue;
+        const card = await store.latestCard(node.id);
+        const payload = {
+          type: 'node',
+          node: { id: node.id, origin: node.origin, state: node.state, source: node.source, updated_at: node.updated_at },
+          card,
+          observations: await store.observationsForNode(node.id),
+        };
+        const jws = signJson(payload, registryKeys.privateKey, 'registry-1');
+        res.write(JSON.stringify({ payload, jws }) + '\n');
+      }
+      res.end();
+    }],
+  ];
+}

package/src/importers.js

@@ -0,0 +1,346 @@
+// DS-IMP-01: seed importers so search is useful before any real registration.
+// Imported records enter as unverified, unsigned, source='import', and are
+// excluded from verified tiers until claimed by their operator.
+import { validateCard } from '@opennodes/core';
+
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[^a-z0-9]+/, '').slice(0, 100);
+const vendorSlug = (s) => slug(s).replace(/[._]/g, '-');
+
+/** Map input/output modality arrays (the shape both HF and OpenRouter use) to the ONP enum. */
+export function mapModalities(inputs = ['text'], outputs = ['text']) {
+  const out = new Set(outputs);
+  if (out.has('image')) return 'image';
+  if (out.has('video')) return 'video';
+  if (out.has('audio')) return 'audio';
+  if (out.has('embedding') || out.has('embeddings')) return 'embedding';
+  return inputs.some((i) => i !== 'text') ? 'multimodal' : 'text';
+}
+
+const PIPELINE_TAG_MODALITY = {
+  'text-generation': 'text', 'text2text-generation': 'text', 'conversational': 'text',
+  'image-text-to-text': 'multimodal', 'visual-question-answering': 'multimodal',
+  'text-to-image': 'image', 'image-to-image': 'image',
+  'text-to-video': 'video', 'image-to-video': 'video', 'image-text-to-video': 'video',
+  'text-to-speech': 'audio', 'automatic-speech-recognition': 'audio', 'audio-to-audio': 'audio',
+  'feature-extraction': 'embedding', 'sentence-similarity': 'embedding',
+};
+
+/** Per-token price strings/values -> USD per MTok. Values >= 0.01 are assumed per-MTok already. */
+const perMtok = (v) => {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return Math.round((n < 0.01 ? n * 1_000_000 : n) * 1e6) / 1e6;
+};
+
+async function saveImportedCard(store, nodeId, origin, sourceRef, card) {
+  const errors = validateCard(card);
+  if (errors.length) return errors[0];
+  await store.upsertNode(nodeId, origin, sourceRef, 'indexed', 'import');
+  await store.saveRevision(nodeId, card.revision, card, false);
+  return null;
+}
+
+/**
+ * Import a models.dev-shaped catalog: { providerId: { id, name, api?, doc?, models: { key: model } } }.
+ * Each provider becomes a synthetic node `import.modelsdev.{provider}`; each model an offering.
+ * Returns { providers, offerings, skipped }.
+ */
+export async function importModelsDev(store, catalog) {
+  let providers = 0, offerings = 0;
+  const skipped = [];
+  for (const [providerId, provider] of Object.entries(catalog ?? {})) {
+    const models = provider?.models ?? {};
+    const offeringList = [];
+    for (const [modelKey, model] of Object.entries(models)) {
+      const outputs = model?.modalities?.output ?? ['text'];
+      const modality = outputs.includes('text') ? 'text' : outputs.includes('image') ? 'image' : 'text';
+      offeringList.push({
+        offering_id: slug(modelKey) || 'model',
+        modality,
+        model: {
+          name: model?.name ?? modelKey,
+          family: slug(providerId),
+          artifact: `urn:proprietary:${slug(providerId).replace(/[._]/g, '-')}:${slug(model?.id ?? modelKey).replace(/\//g, '-')}`,
+        },
+        serving: {
+          ...(model?.limit?.context ? { context_window: Math.floor(model.limit.context) } : {}),
+          ...(model?.limit?.output ? { max_output_tokens: Math.floor(model.limit.output) } : {}),
+          ...(model?.tool_call ? { supports: ['tool_calls'] } : {}),
+        },
+        binding: { profile: 'onp.openai.chat/v1', model_id: model?.id ?? modelKey },
+        pricing: {
+          currency: 'USD',
+          input_per_mtok: Number(model?.cost?.input ?? 0),
+          output_per_mtok: Number(model?.cost?.output ?? 0),
+          schemes: ['prepaid'],
+        },
+      });
+    }
+    if (!offeringList.length) { skipped.push(providerId); continue; }
+
+    const nodeId = `import.modelsdev.${slug(providerId).replace(/[._]/g, '-')}`;
+    const base = provider?.api ?? provider?.doc ?? 'https://models.dev';
+    const card = {
+      onp: '0.1',
+      revision: new Date().toISOString(),
+      node: {
+        id: nodeId,
+        name: provider?.name ?? providerId,
+        description: `Imported from models.dev; metadata only, unclaimed by the operator.`,
+        operator: { name: provider?.name ?? providerId },
+      },
+      endpoints: { openai: base, health: `${base.replace(/\/$/, '')}/health` },
+      offerings: offeringList,
+      payment: { schemes: [{ scheme: 'prepaid' }] },
+    };
+    const errors = validateCard(card);
+    if (errors.length) { skipped.push(`${providerId}: ${errors[0]}`); continue; }
+
+    await store.upsertNode(nodeId, new URL(base).origin, `import:modelsdev:${providerId}`, 'indexed', 'import');
+    await store.saveRevision(nodeId, card.revision, card, false);
+    providers++;
+    offerings += offeringList.length;
+  }
+  return { providers, offerings, skipped };
+}
+
+export const HF_ROUTER_URL = 'https://router.huggingface.co/v1/models';
+export const HF_HUB_URL = 'https://huggingface.co/api/models?inference_provider=all&limit=1000&expand[]=inferenceProviderMapping&expand[]=pipeline_tag&expand[]=safetensors';
+
+/**
+ * Import Hugging Face Inference Providers: `router` is the /v1/models response
+ * (live serving: per-provider status/capabilities/perf), `hub` the Hub API list
+ * (params_b from safetensors, pipeline_tag). One synthetic node per provider
+ * (`import.hf.{provider}`); artifact `hf:{repo}` is authoritative.
+ */
+export async function importHuggingFace(store, router, hub = []) {
+  const hubById = new Map((hub ?? []).map((m) => [m.id, m]));
+  const byProvider = new Map(); // provider -> offerings[]
+
+  for (const model of router?.data ?? []) {
+    const hubEntry = hubById.get(model.id);
+    const paramsB = hubEntry?.safetensors?.total
+      ? Math.round(hubEntry.safetensors.total / 1e7) / 100 : undefined;
+    const inputs = model.architecture?.input_modalities ?? ['text'];
+    const outputs = model.architecture?.output_modalities ?? ['text'];
+    const modality = hubEntry?.pipeline_tag && PIPELINE_TAG_MODALITY[hubEntry.pipeline_tag]
+      ? PIPELINE_TAG_MODALITY[hubEntry.pipeline_tag]
+      : mapModalities(inputs, outputs);
+
+    for (const p of model.providers ?? []) {
+      if (p.status !== 'live') continue;
+      const supports = ['streaming'];
+      if (p.supports_tools) supports.push('tool_calls');
+      if (p.supports_structured_output) supports.push('json_mode');
+      if (inputs.includes('image') && outputs.includes('text')) supports.push('vision');
+      const offering = {
+        offering_id: slug(model.id),
+        modality,
+        modalities: { input: inputs, output: outputs }, // Draft 0.2 field, additive
+        model: {
+          name: model.id,
+          family: vendorSlug(model.owned_by ?? model.id.split('/')[0]),
+          artifact: `hf:${model.id}`,
+          ...(paramsB ? { params_b: paramsB } : {}),
+        },
+        serving: {
+          supports,
+          ...(p.context_length ? { context_window: Math.floor(p.context_length) } : {}),
+          ...(Number.isFinite(p.first_token_latency_ms)
+            ? { expected_ttft_ms: { p50: Math.round(p.first_token_latency_ms), basis: 'claimed' } } : {}),
+          ...(Number.isFinite(p.throughput)
+            ? { expected_tps: { p50: Math.round(p.throughput), basis: 'claimed' } } : {}),
+        },
+        binding: { profile: 'onp.openai.chat/v1', model_id: `${model.id}:${p.provider}` },
+        pricing: {
+          currency: 'USD',
+          input_per_mtok: perMtok(p.pricing?.input),
+          output_per_mtok: perMtok(p.pricing?.output),
+          schemes: p.is_free ? ['free'] : ['prepaid'],
+        },
+      };
+      if (!byProvider.has(p.provider)) byProvider.set(p.provider, []);
+      byProvider.get(p.provider).push(offering);
+    }
+  }
+
+  let providers = 0, offerings = 0;
+  const skipped = [];
+  for (const [provider, offeringList] of byProvider) {
+    const nodeId = `import.hf.${vendorSlug(provider)}`;
+    const card = {
+      onp: '0.1',
+      revision: new Date().toISOString(),
+      node: {
+        id: nodeId,
+        name: `${provider} (via Hugging Face Inference Providers)`,
+        description: 'Imported from the Hugging Face Inference Providers router; metadata only, unclaimed by the operator.',
+        operator: { name: provider },
+      },
+      endpoints: { openai: 'https://router.huggingface.co/v1', health: 'https://router.huggingface.co/health' },
+      offerings: offeringList,
+      payment: { schemes: [{ scheme: 'prepaid', signup: 'https://huggingface.co/settings/billing' }] },
+    };
+    const err = await saveImportedCard(store, nodeId, 'https://router.huggingface.co', `import:hf:${provider}`, card);
+    if (err) { skipped.push(`${provider}: ${err}`); continue; }
+    providers++;
+    offerings += offeringList.length;
+  }
+  return { providers, offerings, skipped };
+}
+
+export const OLLAMA_LIBRARY_URL = 'https://ollama.com/library';
+
+/** Parse ollama.com/library HTML into entries. Resilient to styling churn:
+ *  anchors on /library/{name}, spans classified by content (sizes look like "27b"/"270m"). */
+export function parseOllamaLibrary(html) {
+  const entries = [];
+  const blocks = String(html).split('href="/library/').slice(1);
+  for (const block of blocks) {
+    const name = block.match(/^([a-z0-9._-]+)"/)?.[1];
+    if (!name) continue;
+    const chunk = block.slice(0, 6000);
+    const description = chunk.match(/<p[^>]*class="[^"]*max-w-lg[^"]*"[^>]*>\s*([^<]{1,400}?)\s*<\/p>/)?.[1]?.trim() ?? null;
+    const spans = [...chunk.matchAll(/<span[^>]*class="[^"]*inline-flex[^"]*"[^>]*>\s*([^<]{1,40}?)\s*<\/span>/g)].map((m) => m[1].trim());
+    const sizes = spans.filter((s) => /^\d+(\.\d+)?[mb]$/i.test(s));
+    const capabilities = spans.filter((s) => !/^\d+(\.\d+)?[mb]$/i.test(s));
+    const pulls = chunk.match(/<span[^>]*>\s*([\d.]+[KMB]?)\s*<\/span>\s*<span[^>]*>&nbsp;Pulls/)?.[1] ?? null;
+    entries.push({ name, description, capabilities, sizes, pulls });
+  }
+  return entries;
+}
+
+const sizeToParamsB = (s) => {
+  const m = String(s).match(/^(\d+(?:\.\d+)?)([mb])$/i);
+  if (!m) return null;
+  return m[2].toLowerCase() === 'b' ? Number(m[1]) : Math.round(Number(m[1]) / 10) / 100;
+};
+
+/**
+ * Import the Ollama library as locally-runnable offerings on a synthetic node whose
+ * endpoint is the user's OWN machine (http://127.0.0.1:11434/v1) — free, local, and
+ * directly usable from the model-page playground once `ollama run <name>` has pulled it.
+ */
+export async function importOllamaLibrary(store, entries) {
+  const offeringList = [];
+  for (const e of entries ?? []) {
+    if (!e?.name) continue;
+    const caps = (e.capabilities ?? []).map((c) => String(c).toLowerCase());
+    const modality = caps.includes('embedding') ? 'embedding' : (caps.includes('vision') ? 'multimodal' : 'text');
+    const paramsCandidates = (e.sizes ?? []).map(sizeToParamsB).filter((n) => n != null);
+    const supports = ['streaming'];
+    if (caps.includes('tools')) supports.push('tool_calls');
+    if (caps.includes('vision')) supports.push('vision');
+    offeringList.push({
+      offering_id: slug(e.name),
+      modality,
+      model: {
+        name: e.name,
+        family: vendorSlug(e.name.split(/[.:0-9]/)[0] || e.name),
+        artifact: `urn:proprietary:ollama:${vendorSlug(e.name)}`,
+        ...(paramsCandidates.length ? { params_b: Math.max(...paramsCandidates) } : {}),
+        ...(e.description ? { description: String(e.description).slice(0, 500) } : {}),
+      },
+      serving: { supports },
+      binding: {
+        profile: modality === 'embedding' ? 'onp.openai.embeddings/v1' : 'onp.openai.chat/v1',
+        model_id: e.name,
+      },
+      pricing: { currency: 'USD', input_per_mtok: 0, output_per_mtok: 0, schemes: ['free'] },
+      local: {
+        runtime: 'ollama',
+        run: `ollama run ${e.name}`,
+        ...(e.pulls ? { pulls: e.pulls } : {}),
+        ...(e.sizes?.length ? { sizes: e.sizes } : {}),
+      },
+    });
+  }
+  if (!offeringList.length) return { providers: 0, offerings: 0, skipped: ['no entries'] };
+  const nodeId = 'import.ollama.library';
+  const card = {
+    onp: '0.1',
+    revision: new Date().toISOString(),
+    node: {
+      id: nodeId,
+      name: 'Ollama library (runs on your machine)',
+      description: 'Locally-runnable models from the Ollama library. The endpoint is your own machine: install Ollama, `ollama run <model>`, and these offerings serve at localhost — free, private, no network.',
+      operator: { name: 'Ollama (community library)' },
+    },
+    endpoints: { openai: 'http://127.0.0.1:11434/v1', health: 'http://127.0.0.1:11434' },
+    offerings: offeringList,
+    payment: { schemes: [{ scheme: 'free' }] },
+  };
+  const err = await saveImportedCard(store, nodeId, 'https://ollama.com', 'import:ollama-library', card);
+  if (err) return { providers: 0, offerings: 0, skipped: [err] };
+  return { providers: 1, offerings: offeringList.length, skipped: [] };
+}
+
+export const OPENROUTER_URL = 'https://openrouter.ai/api/v1/models';
+
+/**
+ * Import the OpenRouter catalog as one synthetic node (`import.openrouter.catalog`):
+ * per-token price strings -> per-MTok; `hugging_face_id` gives the artifact join
+ * where present, else a proprietary URN under the model author's namespace.
+ */
+export async function importOpenRouter(store, catalog) {
+  const offeringList = [];
+  for (const model of catalog?.data ?? []) {
+    const inputs = model.architecture?.input_modalities ?? ['text'];
+    const outputs = model.architecture?.output_modalities ?? ['text'];
+    const supports = ['streaming'];
+    const params = model.supported_parameters ?? [];
+    if (params.includes('tools')) supports.push('tool_calls');
+    if (params.includes('response_format') || params.includes('structured_outputs')) supports.push('json_mode');
+    if (inputs.includes('image') && outputs.includes('text')) supports.push('vision');
+    const author = vendorSlug(model.id.split('/')[0] || 'unknown');
+    offeringList.push({
+      offering_id: slug(model.id),
+      modality: mapModalities(inputs, outputs),
+      modalities: { input: inputs, output: outputs },
+      model: {
+        name: model.name ?? model.id,
+        family: author,
+        artifact: model.hugging_face_id
+          ? `hf:${model.hugging_face_id}`
+          : `urn:proprietary:${author}:${slug(model.id.split('/').slice(1).join('-') || model.id)}`,
+        ...(model.description ? { description: String(model.description).slice(0, 500) } : {}),
+        ...(Number.isFinite(model.created)
+          ? { released: new Date(model.created * 1000).toISOString().slice(0, 10) } : {}),
+      },
+      serving: {
+        supports,
+        ...(model.context_length ? { context_window: Math.floor(model.context_length) } : {}),
+        ...(model.top_provider?.max_completion_tokens
+          ? { max_output_tokens: Math.floor(model.top_provider.max_completion_tokens) } : {}),
+      },
+      binding: { profile: 'onp.openai.chat/v1', model_id: model.id },
+      pricing: {
+        currency: 'USD',
+        input_per_mtok: perMtok(model.pricing?.prompt),
+        output_per_mtok: perMtok(model.pricing?.completion),
+        ...(model.pricing?.input_cache_read
+          ? { cached_input_per_mtok: perMtok(model.pricing.input_cache_read) } : {}),
+        schemes: Number(model.pricing?.prompt) === 0 ? ['free'] : ['prepaid'],
+      },
+    });
+  }
+  if (!offeringList.length) return { providers: 0, offerings: 0, skipped: ['empty catalog'] };
+
+  const nodeId = 'import.openrouter.catalog';
+  const card = {
+    onp: '0.1',
+    revision: new Date().toISOString(),
+    node: {
+      id: nodeId,
+      name: 'OpenRouter catalog',
+      description: 'Imported from the public OpenRouter models API; metadata only, unclaimed by the operator.',
+      operator: { name: 'OpenRouter' },
+    },
+    endpoints: { openai: 'https://openrouter.ai/api/v1', health: 'https://openrouter.ai/api/v1/models' },
+    offerings: offeringList,
+    payment: { schemes: [{ scheme: 'prepaid', signup: 'https://openrouter.ai/keys' }] },
+  };
+  const err = await saveImportedCard(store, nodeId, 'https://openrouter.ai', 'import:openrouter', card);
+  if (err) return { providers: 0, offerings: 0, skipped: [err] };
+  return { providers: 1, offerings: offeringList.length, skipped: [] };
+}

package/src/mcp.js

@@ -0,0 +1,182 @@
+// DS-MCP-01: the registry as an MCP server (streamable HTTP, stateless).
+// Minimal JSON-RPC handler covering initialize / tools/list / tools/call so any
+// MCP host gets ONP discovery (search_offerings, get_offering, estimate) for free.
+import { readJson, sendJson, problem, estimateBounds, round6, extractFeatures, recommend } from '@opennodes/core';
+import { searchOfferings, collectOfferings } from './search.js';
+
+const PROTOCOL_VERSION = '2025-06-18';
+
+const TOOLS = [
+  {
+    name: 'search_offerings',
+    description: 'Search AI inference offerings in the OpenNodes registry. Filters: modality (text|image|audio|video|embedding|multimodal|agent), family, min_context, supports (comma list: tool_calls,json_mode,vision,streaming), max_input_price (USD per MTok), scheme (free|prepaid|x402), tier (community|verified|attested), lang ("en:strong"), q (free text), sort (rank|price). Returns offerings with pricing, trust tier, and rank explanation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        modality: { type: 'string' }, family: { type: 'string' },
+        min_context: { type: 'number' }, supports: { type: 'string' },
+        max_input_price: { type: 'number' }, scheme: { type: 'string' },
+        tier: { type: 'string' }, lang: { type: 'string' },
+        q: { type: 'string' }, sort: { type: 'string' }, limit: { type: 'number' },
+      },
+    },
+  },
+  {
+    name: 'get_offering',
+    description: 'Get full detail for one offering by node_id and offering_id, including endpoints, pricing, serving capabilities, and observed probe results.',
+    inputSchema: {
+      type: 'object',
+      required: ['node_id', 'offering_id'],
+      properties: { node_id: { type: 'string' }, offering_id: { type: 'string' } },
+    },
+  },
+  {
+    name: 'estimate',
+    description: 'Estimate cost bounds for a planned invocation chain BEFORE spending money. Each step names a concrete offering ("node_id/offering_id") or a select query (same filters as search_offerings), plus est_input_tokens and est_output_tokens. Returns per-step cost, pinned card_revision (making the estimate enforceable at invocation), and totals.',
+    inputSchema: {
+      type: 'object',
+      required: ['steps'],
+      properties: {
+        steps: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              offering: { type: 'string' },
+              select: { type: 'object' },
+              est_input_tokens: { type: 'number' },
+              est_output_tokens: { type: 'number' },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: 'recommend',
+    description: 'Recommend the best AI node + model for a task. Give the task (a description or the prompt itself) and an optional policy; returns the top offerings with score components, human-readable reasons, an enforceable cost estimate with pinned card_revision, an optional two-step scenario (cheap triage/draft → strong expert/refine) when it would save money, and MCP tool categories the task likely needs. Prefer passing `features` (from a local extractFeatures) instead of `task` when the prompt is private.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: { type: 'string', description: 'task description or prompt' },
+        features: { type: 'object', description: 'pre-extracted features (privacy-preserving alternative to task)' },
+        est_output_tokens: { type: 'number' },
+        policy: {
+          type: 'object',
+          properties: {
+            min_tier: { type: 'string' }, max_input_per_mtok: { type: 'number' }, max_total_usd: { type: 'number' },
+            region: { type: 'string' }, prefer_local: { type: 'boolean' },
+            preset: { type: 'string', description: 'cheap | fast | quality | private' }, limit: { type: 'number' },
+          },
+        },
+      },
+    },
+  },
+];
+
+async function runTool(store, name, args = {}) {
+  switch (name) {
+    case 'recommend': {
+      const features = args.features ?? (args.task != null
+        ? extractFeatures(String(args.task), { est_output_tokens: args.est_output_tokens ?? null }) : null);
+      if (!features) throw new Error('recommend needs "task" or "features"');
+      return recommend(await collectOfferings(store), features, args.policy ?? {});
+    }
+    case 'search_offerings': {
+      const query = new URLSearchParams();
+      for (const [k, v] of Object.entries(args)) if (v !== undefined && v !== null) query.set(k, String(v));
+      return { offerings: await searchOfferings(store, query) };
+    }
+    case 'get_offering': {
+      const found = (await collectOfferings(store)).find(
+        (o) => o.node_id === args.node_id && o.offering_id === args.offering_id);
+      if (!found) throw new Error(`unknown offering: ${args.node_id}/${args.offering_id}`);
+      return found;
+    }
+    case 'estimate': {
+      const all = await collectOfferings(store);
+      const steps = [];
+      let min = 0, max = 0, currency = 'USD';
+      for (const step of args.steps ?? []) {
+        let offering;
+        if (step.offering) {
+          const [nodeId, offeringId] = step.offering.split('/');
+          offering = all.find((o) => o.node_id === nodeId && o.offering_id === offeringId);
+          if (!offering) throw new Error(`unknown offering: ${step.offering}`);
+        } else if (step.select) {
+          const query = new URLSearchParams();
+          for (const [k, v] of Object.entries(step.select)) query.set(k, String(v));
+          offering = (await searchOfferings(store, query))[0];
+          if (!offering) throw new Error(`no offering matches select: ${JSON.stringify(step.select)}`);
+        } else {
+          throw new Error('each step needs "offering" or "select"');
+        }
+        const bounds = estimateBounds(offering.pricing, step.est_input_tokens ?? 0, step.est_output_tokens ?? 0);
+        currency = offering.pricing.currency;
+        min += bounds.min; max += bounds.max;
+        steps.push({
+          offering: `${offering.node_id}/${offering.offering_id}`,
+          card_revision: offering.card_revision,
+          cost: { currency, ...bounds },
+        });
+      }
+      return { total: { currency, min: round6(min), max: round6(max) }, steps };
+    }
+    default:
+      throw new Error(`unknown tool: ${name}`);
+  }
+}
+
+async function handleRpc(store, msg) {
+  const { id, method, params } = msg;
+  const reply = (result) => ({ jsonrpc: '2.0', id, result });
+  const rpcError = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+  switch (method) {
+    case 'initialize':
+      return reply({
+        protocolVersion: params?.protocolVersion ?? PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'opennodes-registry', version: '0.1.0' },
+        instructions: 'OpenNodes registry: search AI inference offerings, inspect them, and pre-price invocation chains. Typical flow: search_offerings -> estimate -> invoke via the offering endpoints (invocation itself is not exposed here).',
+      });
+    case 'ping':
+      return reply({});
+    case 'tools/list':
+      return reply({ tools: TOOLS });
+    case 'tools/call':
+      try {
+        const result = await runTool(store, params?.name, params?.arguments);
+        return reply({
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+          structuredContent: result,
+          isError: false,
+        });
+      } catch (err) {
+        return reply({ content: [{ type: 'text', text: String(err.message) }], isError: true });
+      }
+    case 'resources/list':
+      return reply({ resources: [] });
+    case 'prompts/list':
+      return reply({ prompts: [] });
+    default:
+      if (method?.startsWith('notifications/')) return null; // notifications get no response
+      return rpcError(-32601, `method not found: ${method}`);
+  }
+}
+
+/** Routes to mount into the registry app. */
+export function mcpRoutes(store) {
+  return [
+    ['POST', '/mcp', async (req, res) => {
+      const body = await readJson(req, 5_000_000);
+      const messages = Array.isArray(body) ? body : [body];
+      const replies = (await Promise.all(messages.map((m) => handleRpc(store, m)))).filter(Boolean);
+      if (replies.length === 0) { res.writeHead(202); res.end(); return; }
+      sendJson(res, 200, Array.isArray(body) ? replies : replies[0]);
+    }],
+    ['GET', '/mcp', (req, res) => {
+      problem(res, 405, 'method-not-allowed', 'stateless MCP server: POST JSON-RPC messages to this endpoint');
+    }],
+  ];
+}