csoai-gspc-mcp 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# csoai-gspc-mcp
+
+Stdio MCP server for the live GSPC board and the signed measurement cards at
+[councilof.ai](https://councilof.ai). Zero dependencies. Node >= 20.
+
+**Doctrine, enforced in the tools, not just stated here:** we measure, never
+certify. Verdicts are three-state — VALID / INVALID (with the reason) /
+UNCHECKABLE — never two-state. An unmeasured axis is a first-class answer, not
+an error and not a zero. A fetch failure is a distinct UNREACHABLE state; no
+cached number is ever presented as live. Two surfaces that count the same thing
+are reported as two labelled numbers and never reconciled.
+
+## Tools
+
+| tool | what it does |
+|---|---|
+| `board_totals` | Live totals from `GET https://councilof.ai/api/gspc`: slot count and measured count as two labelled numbers with their `kind` and `as_of` dates. UNREACHABLE state on fetch failure. |
+| `get_axis` | One axis row from the live board: `n`, `accuracy`, `interval`, MEASURED/UNMEASURED status, dates. Args: `{ "axis": "jail" }`. |
+| `verify_card` | Verify a signed `gspc.measurement-card` under the published rule — recompute the id from the canonical body, check the Ed25519 signature under the **pinned** key `did:web:csoai.org#card-attestation-1`. A card signed with its own freshly-made key is INVALID, not valid. Args: `{ "card": <object | JSON string | councilof.ai URL> }`. |
+| `list_cards` | What the published index (`/signed/card_index.json`) declares next to what the card store endpoint (`/api/cards`) reports — two labelled numbers, never reconciled. Optional `axis`, `limit`. |
+
+The same four tools, from the same definitions file
+(`functions/mcp/gspc-tools.json`), are served over HTTP at
+`https://councilof.ai/mcp` (streamable HTTP, JSON-RPC 2.0 POST). Use whichever
+transport your client speaks; the contracts are identical.
+
+## Install
+
+This package is **not yet published to npm** (checked 2026-08-27). Until it is,
+install from a checkout of the repo — the server is a single file with no
+dependencies, so "install" is just pointing your client at it:
+
+```sh
+git clone https://github.com/CSOAI-ORG/councilof-ai.git
+# the server is at councilof-ai/mcp/gspc-server/index.mjs — no npm install needed
+```
+
+Below, replace `/ABS/PATH/TO/councilof-ai` with where you cloned it.
+
+### Claude Code
+
+```sh
+claude mcp add gspc -- node /ABS/PATH/TO/councilof-ai/mcp/gspc-server/index.mjs
+```
+
+Once published to npm this becomes `claude mcp add gspc -- npx -y csoai-gspc-mcp`.
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`; Windows:
+`%APPDATA%\Claude\claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gspc": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/councilof-ai/mcp/gspc-server/index.mjs"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "gspc": {
+      "command": "node",
+      "args": ["/ABS/PATH/TO/councilof-ai/mcp/gspc-server/index.mjs"]
+    }
+  }
+}
+```
+
+### Any other stdio MCP client (Grok Bot, DSH harness, your own agent)
+
+Spawn `node /ABS/PATH/TO/councilof-ai/mcp/gspc-server/index.mjs` and speak
+newline-delimited JSON-RPC 2.0 on its stdin/stdout (stderr is logs only):
+
+1. send `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"you","version":"0"}}}`
+2. send `{"jsonrpc":"2.0","method":"notifications/initialized"}`
+3. send `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`
+4. call tools: `{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"board_totals","arguments":{}}}`
+
+Every `tools/call` result carries both a human `content[0].text` summary and a
+machine `structuredContent` object. Protocol versions accepted: 2024-11-05,
+2025-03-26, 2025-06-18.
+
+If you cannot spawn processes, POST the same JSON-RPC bodies to
+`https://councilof.ai/mcp` instead.
+
+## Configuration
+
+- `GSPC_ORIGIN` — override the live origin (default `https://councilof.ai`).
+  Card URLs are only ever fetched from councilof.ai / csoai.org.
+
+## Verify it yourself
+
+```sh
+node smoke.mjs
+```
+
+Real transport, no mocks: spawns the server, runs
+initialize → tools/list → tools/call, then proves the three verify_card
+verdicts — a genuine published card is VALID, the same card with one byte of
+body changed is INVALID (id mismatch), and a forged card signed with a
+freshly-generated key is INVALID (pubkey is not the published
+card-attestation key) even though it is perfectly self-consistent.
+
+## One source of truth
+
+- Tool definitions: `functions/mcp/gspc-tools.json` — shared byte-for-byte with
+  the HTTP endpoint (`functions/mcp/[[path]].ts`). Neither surface defines
+  these tools anywhere else.
+- Card verification: `public/signed/verify-card.mjs` — the published CLI
+  verifier, imported and run as-is.
+- In a repo checkout the canonical files are read directly; `npm run prepack`
+  (`pack.mjs`) copies them into the tarball and refuses to pack on drift.
+
+Apache-2.0. CSOAI Ltd (UK 16939677).

package/gspc-tools.json

@@ -0,0 +1,65 @@
+{
+  "schema": "csoai.gspc-mcp-tools/1",
+  "note": "ONE source of tool definitions for the GSPC MCP tools, shared by the stdio server (mcp/gspc-server/index.mjs) and the HTTP endpoint (functions/mcp/[[path]].ts) so the two surfaces cannot drift. Display text uses 'axis', never the plural — owner language ruling; code identifiers are exempt.",
+  "tools": [
+    {
+      "name": "board_totals",
+      "description": "Live GSPC board totals from https://councilof.ai/api/gspc. Returns the slot count and the measured count as two labelled numbers WITH their kind — a slot is a declared position on the board, a measurement is a real run behind it; the two are never summed and never swapped — plus as_of dates for the board and for this fetch. We measure, never certify. If the board cannot be fetched the answer is a distinct UNREACHABLE state: no cached number is ever presented as live.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "get_axis",
+      "description": "One axis row from the live GSPC board at https://councilof.ai/api/gspc: n, accuracy, interval, MEASURED or UNMEASURED status, family, and dates. An unmeasured axis is a first-class answer — a declared slot with no run behind it, published so the gap is visible — never an error and never a zero. Never a certification.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "axis": {
+            "type": "string",
+            "description": "The axis name as it appears on the board, e.g. governance, safety, jail, provenance-controls. Case-insensitive. An unknown name returns the list of names the board actually carries."
+          }
+        },
+        "required": ["axis"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "verify_card",
+      "description": "Verify a signed gspc.measurement-card under the published rule (https://councilof.ai/signed/HOW-TO-VERIFY.md): recompute the id from the canonical body bytes, then check the Ed25519 signature under the PINNED key published at did:web:csoai.org#card-attestation-1. A card that carries its own key proves only that the file is self-consistent — anyone can alter a body and sign it with a key they just generated — so a signer other than the published key is reported INVALID. Three verdicts, never two: VALID, INVALID (with the reason), or UNCHECKABLE when the check could not be completed — 'could not check' is a different claim from 'forged'. Accepts the card as a JSON object, a JSON string, or a councilof.ai / csoai.org URL. Never a certification.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "card": {
+            "description": "The signed card: an object, a JSON string, or a councilof.ai / csoai.org URL to one.",
+            "anyOf": [{ "type": "object" }, { "type": "string" }]
+          }
+        },
+        "required": ["card"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "list_cards",
+      "description": "The published signed-card index (https://councilof.ai/signed/card_index.json): what the index declares (n_cards) and how many rows it actually carries, reported next to — never reconciled with — the count the card store endpoint (https://councilof.ai/api/cards) reports for itself. Two labelled numbers from two surfaces; if they disagree, this tool shows the disagreement rather than picking one. Optional filters return recent rows: axis, limit.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "axis": {
+            "type": "string",
+            "description": "Only list rows whose axis matches this name (case-insensitive)."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 150,
+            "description": "How many rows to include in the listing (newest first). Default 10. The two counts are always reported in full regardless of this limit."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  ]
+}

package/index.mjs

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * csoai-gspc-mcp — stdio MCP server for the live GSPC board and the signed cards.
+ *
+ * Zero dependencies. Node >= 20 (WebCrypto Ed25519 and global fetch).
+ * Transport: MCP stdio — newline-delimited JSON-RPC 2.0 on stdin/stdout.
+ * Logs go to stderr only; stdout carries nothing but protocol messages.
+ *
+ * DOCTRINE (carried into every tool, not just this comment):
+ *   - We measure, never certify. No tool here issues a certification.
+ *   - Three-state verdicts: VALID / INVALID (with the reason) / UNCHECKABLE.
+ *     "I could not check" is a different claim from "this is forged".
+ *   - Unmeasured is first-class. A declared slot with no run behind it is an
+ *     honest answer, never an error, never a zero, never rounded up.
+ *   - Live means live. A fetch failure returns a distinct UNREACHABLE state;
+ *     no cached number is ever presented as a live one.
+ *   - Two surfaces that count the same thing are reported as two labelled
+ *     numbers. This server never reconciles them.
+ *
+ * ONE SOURCE OF TRUTH:
+ *   - Tool definitions come from gspc-tools.json — the same file the HTTP
+ *     endpoint at councilof.ai/mcp imports (functions/mcp/gspc-tools.json).
+ *     In a repo checkout that file is read directly; the npm package ships a
+ *     byte-identical copy made at pack time (npm run prepack).
+ *   - verify_card runs the code in public/signed/verify-card.mjs — the same
+ *     module the published CLI verifier is. Same rule: repo file first, packed
+ *     copy as fallback.
+ */
+
+import { createInterface } from "node:readline";
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const VERSION = "0.1.0";
+const ORIGIN = process.env.GSPC_ORIGIN || "https://councilof.ai";
+const FETCH_TIMEOUT_MS = 15000;
+
+/** Card URLs may be fetched only from the estate's own published origins. */
+const FETCHABLE_ORIGINS = ["https://councilof.ai/", "https://csoai.org/", "https://www.csoai.org/"];
+
+/* ------------------------------------------------- one-source module loading */
+
+function firstExisting(paths) {
+  for (const p of paths) {
+    const abs = fileURLToPath(new URL(p, import.meta.url));
+    if (existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+const TOOLS_PATH = firstExisting([
+  "../../functions/mcp/gspc-tools.json", // repo checkout: the canonical file
+  "./gspc-tools.json", // npm package: the byte-identical pack-time copy
+]);
+if (!TOOLS_PATH) {
+  process.stderr.write("csoai-gspc-mcp: gspc-tools.json not found — broken install\n");
+  process.exit(1);
+}
+const TOOLS = JSON.parse(readFileSync(TOOLS_PATH, "utf8")).tools;
+
+const VERIFIER_PATH = firstExisting([
+  "../../public/signed/verify-card.mjs", // repo checkout: the canonical file
+  "./verify-card.mjs", // npm package: the byte-identical pack-time copy
+]);
+if (!VERIFIER_PATH) {
+  process.stderr.write("csoai-gspc-mcp: verify-card.mjs not found — broken install\n");
+  process.exit(1);
+}
+const { verifyCard } = await import(`file://${VERIFIER_PATH}`);
+
+/* ------------------------------------------------------------------ fetching */
+
+async function fetchJson(path) {
+  const url = `${ORIGIN}${path}`;
+  const r = await fetch(url, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!r.ok) throw new Error(`GET ${url} returned HTTP ${r.status}`);
+  return r.json();
+}
+
+/**
+ * The distinct unreachable state. Never a cached number, never a zero that
+ * could be mistaken for a measurement.
+ */
+function unreachable(path, e) {
+  return {
+    state: "UNREACHABLE",
+    reachable: false,
+    source: `${ORIGIN}${path}`,
+    error: e instanceof Error ? e.message : String(e),
+    attempted_at: new Date().toISOString(),
+    note:
+      "The live source could not be fetched. No cached or remembered number is " +
+      "substituted — an unreachable board is a different claim from any count.",
+  };
+}
+
+/* --------------------------------------------------------------------- tools */
+
+async function boardTotals() {
+  let d;
+  try {
+    d = await fetchJson("/api/gspc");
+  } catch (e) {
+    return unreachable("/api/gspc", e);
+  }
+  const t = d.totals ?? {};
+  return {
+    state: "LIVE",
+    reachable: true,
+    kind: "live-board-totals",
+    source: `${ORIGIN}/api/gspc`,
+    as_of: { board_measured_on: d.measured_on ?? null, fetched_at: new Date().toISOString() },
+    counts: [
+      {
+        name: "axis_slots",
+        value: t.axes ?? null,
+        kind: "declared slot count — a slot is a position on the board, not evidence anything was measured",
+      },
+      {
+        name: "measured",
+        value: t.measured_axes ?? null,
+        kind: "measurement count — slots with a real run behind them",
+      },
+      {
+        name: "unmeasured",
+        value: t.unmeasured_axes ?? null,
+        kind: "declared slots with no run behind them — published so the gap is visible; first-class, not an error",
+      },
+    ],
+    count_grammar: t.count_grammar ?? null,
+    public_count: t.public_count ?? null,
+    by_family: t.by_family ?? null,
+    not_a_certification: true,
+  };
+}
+
+async function getAxis(args) {
+  const wanted = String(args.axis ?? "").trim().toLowerCase();
+  if (!wanted) return { state: "BAD_INPUT", error: "pass an axis name, e.g. governance" };
+  let d;
+  try {
+    d = await fetchJson("/api/gspc");
+  } catch (e) {
+    return unreachable("/api/gspc", e);
+  }
+  const rows = d.axes ?? [];
+  const row = rows.find((r) => String(r.axis ?? "").toLowerCase() === wanted);
+  if (!row) {
+    return {
+      state: "NOT_ON_BOARD",
+      axis: wanted,
+      note: "This name is not a row on the live board. That is a fact about the board, not a verdict about the subject.",
+      board_carries: rows.map((r) => r.axis),
+      as_of: { board_measured_on: d.measured_on ?? null, fetched_at: new Date().toISOString() },
+    };
+  }
+  const measured = String(row.status ?? "").toUpperCase() === "MEASURED";
+  return {
+    state: "LIVE",
+    axis: row.axis,
+    family: row.family ?? null,
+    status: row.status ?? null,
+    measured,
+    measured_note: measured
+      ? "a real run stands behind this row"
+      : "a declared slot with no run behind it — published so the gap is visible; first-class, not an error and not a zero",
+    n: row.n ?? null,
+    accuracy: row.accuracy ?? null,
+    interval: row.interval ?? null,
+    leader: row.leader ?? null,
+    dataset: row.dataset ?? null,
+    note: row.note ?? null,
+    as_of: { board_measured_on: d.measured_on ?? null, fetched_at: new Date().toISOString() },
+    source: `${ORIGIN}/api/gspc`,
+    not_a_certification: true,
+  };
+}
+
+/** Coerce whatever the caller passed into a card object, or say why we could not. */
+async function coerceCard(raw) {
+  if (raw && typeof raw === "object") return { card: raw };
+  if (typeof raw !== "string")
+    return { error: "pass the card as an object, a JSON string, or a councilof.ai / csoai.org URL" };
+  const s = raw.trim();
+  if (/^https?:\/\//i.test(s)) {
+    if (!FETCHABLE_ORIGINS.some((o) => s.startsWith(o)))
+      return {
+        error:
+          "only councilof.ai and csoai.org URLs are fetched by this tool; fetch other URLs yourself and pass the JSON",
+      };
+    try {
+      const r = await fetch(s, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+      if (!r.ok) return { error: `card fetch returned HTTP ${r.status}` };
+      return { card: await r.json() };
+    } catch (e) {
+      return { error: `card fetch failed: ${e.message}` };
+    }
+  }
+  try {
+    return { card: JSON.parse(s) };
+  } catch {
+    return { error: "the string is neither valid JSON nor a councilof.ai / csoai.org URL" };
+  }
+}
+
+async function verifyCardTool(args) {
+  const { card, error } = await coerceCard(args.card ?? args.record ?? args.json ?? args.url ?? args.input);
+  if (error) return { state: "UNCHECKABLE", reason: error, not_a_certification: true };
+  const v = await verifyCard(card);
+  return {
+    state: v.state, // VALID | INVALID | UNCHECKABLE — three verdicts, never two
+    id: v.id ?? card?.id ?? null,
+    axis: v.axis ?? null,
+    reason: v.reason ?? null,
+    rule: `${ORIGIN}/signed/HOW-TO-VERIFY.md`,
+    pinned_key: "did:web:csoai.org#card-attestation-1",
+    not_a_certification: true,
+    note:
+      v.state === "VALID"
+        ? "The body reproduces its own id and the signature verifies under the published card-attestation key. This is a verified measurement card — not a certification of anything."
+        : v.state === "INVALID"
+          ? "This card fails the published rule for the stated reason. INVALID is a positive finding, distinct from UNCHECKABLE."
+          : "The check could not be completed. 'Could not check' is a different claim from 'forged'.",
+  };
+}
+
+async function listCards(args) {
+  const out = {
+    doctrine:
+      "Two labelled numbers from two surfaces, reported separately and never reconciled by this tool. If they disagree, the disagreement is the finding.",
+    index: null,
+    card_store_count_endpoint: null,
+    rows: null,
+    not_a_certification: true,
+  };
+  try {
+    const idx = await fetchJson("/signed/card_index.json");
+    const rows = Array.isArray(idx.cards) ? idx.cards : [];
+    out.index = {
+      source: `${ORIGIN}/signed/card_index.json`,
+      n_cards_declared: idx.n_cards ?? null,
+      rows_carried: rows.length,
+      head: idx.head ?? null,
+      packaged_at: idx.packaged_at ?? null,
+      pubkey: idx.pubkey ?? null,
+    };
+    const wanted = args.axis ? String(args.axis).toLowerCase() : null;
+    const limit = Number.isInteger(args.limit) ? args.limit : 10;
+    out.rows = rows
+      .filter((r) => !wanted || String(r.axis ?? "").toLowerCase() === wanted)
+      .slice()
+      .sort((a, b) => String(b.ts ?? "").localeCompare(String(a.ts ?? "")))
+      .slice(0, limit)
+      .map((r) => ({ card: r.card, axis: r.axis, ts: r.ts, signed: r.signed }));
+  } catch (e) {
+    out.index = unreachable("/signed/card_index.json", e);
+  }
+  try {
+    const api = await fetchJson("/api/cards");
+    out.card_store_count_endpoint = {
+      source: `${ORIGIN}/api/cards`,
+      count: api?.cards?.count ?? null,
+      signed: api?.cards?.signed ?? null,
+    };
+  } catch (e) {
+    out.card_store_count_endpoint = unreachable("/api/cards", e);
+  }
+  return out;
+}
+
+const HANDLERS = {
+  board_totals: boardTotals,
+  get_axis: getAxis,
+  verify_card: verifyCardTool,
+  list_cards: listCards,
+};
+
+/* ----------------------------------------------------------------- transport */
+
+const SUPPORTED_PROTOCOLS = ["2024-11-05", "2025-03-26", "2025-06-18"];
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function summaryLine(name, payload) {
+  if (payload.state === "UNREACHABLE" || payload.index?.state === "UNREACHABLE")
+    return `UNREACHABLE — the live source could not be fetched; no cached number is substituted.`;
+  switch (name) {
+    case "board_totals":
+      return `LIVE board totals — ${payload.public_count ?? "see counts"} (slots and measurements are different kinds; never summed).`;
+    case "get_axis":
+      return payload.state === "NOT_ON_BOARD"
+        ? `NOT ON BOARD — "${payload.axis}" is not a row the live board carries.`
+        : `${payload.status ?? "?"} — axis "${payload.axis}" (${payload.measured ? "a real run stands behind this row" : "declared slot, no run behind it"}).`;
+    case "verify_card":
+      return `${payload.state}${payload.reason ? " — " + payload.reason : ""}${payload.state === "VALID" ? ` — ${String(payload.id).slice(0, 16)}… verifies under the published key.` : ""}`;
+    case "list_cards": {
+      const a = payload.index?.n_cards_declared ?? "?";
+      const b = payload.card_store_count_endpoint?.count ?? "?";
+      return `index declares ${a} card rows; the store's count endpoint reports ${b}. Two labelled numbers, not reconciled here.`;
+    }
+    default:
+      return name;
+  }
+}
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  const isRequest = id !== undefined && id !== null;
+
+  if (method === "initialize") {
+    const asked = params?.protocolVersion;
+    return reply(id, {
+      protocolVersion: SUPPORTED_PROTOCOLS.includes(asked) ? asked : "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "csoai-gspc-mcp", version: VERSION },
+    });
+  }
+  if (method === "notifications/initialized" || method === "initialized") return; // notification, no reply
+  if (method === "ping") return reply(id, {});
+  if (method === "tools/list") return reply(id, { tools: TOOLS });
+
+  if (method === "tools/call") {
+    const name = params?.name;
+    const fn = HANDLERS[name];
+    if (!fn) return replyError(id, -32602, `unknown tool: ${name}`);
+    try {
+      const payload = await fn(params?.arguments ?? {});
+      return reply(id, {
+        content: [{ type: "text", text: `${summaryLine(name, payload)}\n\n${JSON.stringify(payload, null, 2)}` }],
+        structuredContent: payload,
+        isError: false,
+      });
+    } catch (e) {
+      return reply(id, {
+        content: [{ type: "text", text: `tool error: ${e instanceof Error ? e.message : String(e)}` }],
+        isError: true,
+      });
+    }
+  }
+
+  if (isRequest) return replyError(id, -32601, `method not found: ${method}`);
+  // Unknown notification: ignore silently, per JSON-RPC.
+}
+
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on("line", (line) => {
+  const s = line.trim();
+  if (!s) return;
+  let msg;
+  try {
+    msg = JSON.parse(s);
+  } catch {
+    return replyError(null, -32700, "parse error");
+  }
+  handle(msg).catch((e) => {
+    process.stderr.write(`csoai-gspc-mcp: ${e?.stack ?? e}\n`);
+    if (msg?.id !== undefined && msg?.id !== null) replyError(msg.id, -32603, "internal error");
+  });
+});
+rl.on("close", () => process.exit(0));
+process.stderr.write(`csoai-gspc-mcp ${VERSION} — stdio MCP server, live source ${ORIGIN}\n`);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "csoai-gspc-mcp",
+  "version": "0.1.0",
+  "description": "Stdio MCP server for the live GSPC board and the signed measurement cards at councilof.ai. Four honest tools: board_totals, get_axis, verify_card (pinned-key, three-state), list_cards. We measure, never certify; unmeasured is first-class; verdicts are VALID / INVALID / UNCHECKABLE, never two-state. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "csoai-gspc-mcp": "index.mjs"
+  },
+  "main": "index.mjs",
+  "files": [
+    "index.mjs",
+    "gspc-tools.json",
+    "verify-card.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node pack.mjs",
+    "smoke": "node smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "csoai",
+    "gspc",
+    "measurement",
+    "ed25519",
+    "provenance",
+    "ai-governance"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://councilof.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CSOAI-ORG/councilof-ai.git",
+    "directory": "mcp/gspc-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/verify-card.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+/**
+ * verify-card.mjs — verify a Council of AI measurement card from JavaScript.
+ *
+ * WHY THIS FILE EXISTS. The preimage our cards are signed over was produced by CPython's
+ * json.dumps, which renders a float of integral value as "0.0". ECMAScript's JSON.stringify,
+ * Go's encoding/json and RFC 8785 (JCS) all render the same value as "0". A large share of
+ * our cards contain such a value, so a NAIVE JavaScript verifier computes different bytes and
+ * reports a FALSE FAILURE on roughly a third of the set.
+ *
+ * We cannot re-canonicalise: every card id is the sha256 of these exact bytes, so changing
+ * them would invalidate every id and break every citation. So the quirk is handled here,
+ * once, in a file anyone can read — rather than left for each implementer to rediscover.
+ *
+ * THE HONEST LIMIT. JavaScript cannot distinguish 0 from 0.0 at runtime; both are the same
+ * IEEE-754 double. So this verifier cannot infer which fields are floats — it is told, by
+ * FLOAT_FIELDS below, which is a property of our schema and not of the data. A future card
+ * format should use JCS so this note becomes unnecessary. These cards cannot migrate.
+ *
+ *   node verify-card.mjs <card.json> [more.json ...]
+ *   node verify-card.mjs --all            # fetch and verify every published card
+ *
+ * Requires Node 19+ (for the built-in WebCrypto Ed25519). No dependencies.
+ */
+
+const ORIGIN = "https://councilof.ai";
+
+// The pinned key. A card carries its own `pubkey`, and verifying against THAT proves only
+// that the file is self-consistent — anyone can alter a body and sign it with a key they
+// just generated. Authenticity requires pinning to the key published in our DID document:
+//   did:web:csoai.org#card-attestation-1
+const PINNED_PUBKEY_HEX =
+  "d4cb0eaa16d5f50bf7633a36aa34fe09a55e124b9316ded2abdb122bb9c37e38";
+
+// Fields whose values are floats in our schema. See "THE HONEST LIMIT" above.
+const FLOAT_FIELDS = new Set(["accuracy", "ci_low", "ci_high", "recall", "precision", "f1"]);
+
+/** Canonicalise exactly as CPython json.dumps(sort_keys=True, separators=(',',':')) does. */
+function canonical(value, key = null) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`non-finite number at ${key}`);
+    // A float of integral value renders with a trailing ".0" in CPython.
+    if (Number.isInteger(value) && FLOAT_FIELDS.has(key)) return value.toFixed(1);
+    return String(value);
+  }
+  if (typeof value === "string") return jsonString(value);
+  if (Array.isArray(value)) return "[" + value.map((v) => canonical(v, key)).join(",") + "]";
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return "{" + keys.map((k) => jsonString(k) + ":" + canonical(value[k], k)).join(",") + "}";
+  }
+  throw new Error(`unserialisable value at ${key}`);
+}
+
+/** JSON string escaping with ensure_ascii=True — non-ASCII becomes \\uXXXX, as CPython does. */
+function jsonString(s) {
+  let out = '"';
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    if (ch === '"') out += '\\"';
+    else if (ch === "\\") out += "\\\\";
+    // CPython's ESCAPE_DCT maps 0x08 and 0x0c to the SHORT forms \b and \f, not to
+    //  / . Omitting these two lines produced a wrong preimage for any body
+    // containing them. No published card does, so the bug was latent -- found 2026-08-26.
+    else if (ch === "\b") out += "\\b";
+    else if (ch === "\f") out += "\\f";
+    else if (ch === "\n") out += "\\n";
+    else if (ch === "\r") out += "\\r";
+    else if (ch === "\t") out += "\\t";
+    else if (c < 0x20) out += "\\u" + c.toString(16).padStart(4, "0");
+    else if (c < 0x7f) out += ch;
+    else if (c <= 0xffff) out += "\\u" + c.toString(16).padStart(4, "0");
+    else {
+      // Astral plane: CPython emits a surrogate pair, so we must too.
+      const v = c - 0x10000;
+      out += "\\u" + (0xd800 + (v >> 10)).toString(16).padStart(4, "0");
+      out += "\\u" + (0xdc00 + (v & 0x3ff)).toString(16).padStart(4, "0");
+    }
+  }
+  return out + '"';
+}
+
+const hex = (buf) =>
+  [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+const unhex = (s) => Uint8Array.from(s.match(/../g).map((b) => parseInt(b, 16)));
+
+/**
+ * JCS (RFC 8785) canonicaliser — the v2 preimage rule. A card carrying
+ * `preimage_rule: "jcs-rfc8785"` is hashed over THIS form, NOT the v1 CPython form.
+ * Differences from v1 (canonical above):
+ *   1. No FLOAT_FIELDS: every integral float renders as an integer ("0", not "0.0").
+ *   2. ensure_ascii=False: non-ASCII stays literal (JS JSON.stringify does this), whereas
+ *      v1 escapes to \\uXXXX (CPython ensure_ascii=True).
+ *   3. Same key-sort + compact separators + escape of quote/backslash/control chars.
+ * Matches harness/arena/jcs.py (Python) and the conformance corpus in
+ * harness/arena/jcs_conformance.py (18/18 ordinary cases agree cross-language).
+ */
+function canonicalJcs(value, key = null) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`non-finite number at ${key}`);
+    // JCS/ECMAScript: integral floats in [10^-6, 10^21) emit as integers; -0 -> "0".
+    if (Number.isInteger(value) && value !== 0) {
+      const av = Math.abs(value);
+      if (av >= 1e-6 && av < 1e21) return String(value);
+    }
+    if (value === 0) return "0"; // covers -0.0
+    return String(value);
+  }
+  if (typeof value === "string") return jcsString(value);
+  if (Array.isArray(value)) return "[" + value.map((v) => canonicalJcs(v, key)).join(",") + "]";
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return "{" + keys.map((k) => jcsString(k) + ":" + canonicalJcs(value[k], k)).join(",") + "}";
+  }
+  throw new Error(`unserialisable value at ${key}`);
+}
+
+/** JCS string escaping: quote/backslash/control-char escapes, non-ASCII stays LITERAL. */
+function jcsString(s) {
+  let out = '"';
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    if (ch === '"') out += '\\"';
+    else if (ch === "\\") out += "\\\\";
+    else if (ch === "\b") out += "\\b";
+    else if (ch === "\f") out += "\\f";
+    else if (ch === "\n") out += "\\n";
+    else if (ch === "\r") out += "\\r";
+    else if (ch === "\t") out += "\\t";
+    else if (c < 0x20) out += "\\u" + c.toString(16).padStart(4, "0");
+    else out += ch; // non-ASCII literal (ensure_ascii=False)
+  }
+  return out + '"';
+}
+
+/**
+ * Three outcomes, never two: VALID, INVALID (with the reason), or UNCHECKABLE.
+ * A verifier that cannot complete its path must say so rather than returning false —
+ * "I could not check" is not the same claim as "this is forged".
+ */
+export async function verifyCard(card) {
+  if (!card || typeof card !== "object" || !card.body)
+    return { state: "UNCHECKABLE", reason: "not a card: no body" };
+  if (!card.pubkey || !card.signature || !card.id)
+    return { state: "UNCHECKABLE", reason: "missing pubkey, signature or id" };
+
+  if (card.pubkey !== PINNED_PUBKEY_HEX)
+    return { state: "INVALID", reason: "pubkey is not the published card-attestation key" };
+
+  let preimage;
+  try {
+    // Preimage-rule dispatch (roadmap item 1): absent = legacy CPython v1; "jcs-rfc8785" = JCS v2.
+    // Never re-sign v1 cards — the verifier dispatches on the field.
+    const rule = card.preimage_rule || card.canon || "cpython-v1";
+    const fn = rule === "jcs-rfc8785" ? canonicalJcs : canonical;
+    preimage = new TextEncoder().encode(fn(card.body));
+  } catch (e) {
+    return { state: "UNCHECKABLE", reason: `cannot canonicalise: ${e.message}` };
+  }
+
+  const digest = hex(await crypto.subtle.digest("SHA-256", preimage));
+  if (digest !== card.id)
+    return { state: "INVALID", reason: `id mismatch: body hashes to ${digest.slice(0, 16)}…` };
+
+  let key;
+  try {
+    key = await crypto.subtle.importKey("raw", unhex(card.pubkey), "Ed25519", false, ["verify"]);
+  } catch {
+    return { state: "UNCHECKABLE", reason: "this runtime has no Ed25519 (needs Node 19+)" };
+  }
+  const ok = await crypto.subtle.verify("Ed25519", key, unhex(card.signature), preimage);
+  return ok
+    ? { state: "VALID", id: card.id, axis: card.body.axis }
+    : { state: "INVALID", reason: "signature does not verify under the pinned key" };
+}
+
+// ---------------------------------------------------------------- CLI
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const cards = [];
+  if (args[0] === "--all") {
+    const idx = await (await fetch(`${ORIGIN}/signed/card_index.json`)).json();
+    const rows = idx.cards || idx.entries || idx;
+    process.stderr.write(`fetching ${rows.length} cards…\n`);
+    for (const r of rows)
+      cards.push(await (await fetch(`${ORIGIN}/signed/cards/${r.card}.json`)).json());
+  } else if (args.length) {
+    const { readFileSync } = await import("node:fs");
+    for (const f of args) cards.push(JSON.parse(readFileSync(f, "utf8")));
+  } else {
+    console.error("usage: node verify-card.mjs <card.json ...> | --all");
+    process.exit(2);
+  }
+
+  const tally = { VALID: 0, INVALID: 0, UNCHECKABLE: 0 };
+  for (const c of cards) {
+    const r = await verifyCard(c);
+    tally[r.state]++;
+    if (r.state !== "VALID") console.error(`  ${r.state}  ${c?.id?.slice(0, 16) ?? "?"}  ${r.reason}`);
+  }
+  console.log(`VALID ${tally.VALID} · INVALID ${tally.INVALID} · UNCHECKABLE ${tally.UNCHECKABLE}`);
+  process.exit(tally.INVALID || tally.UNCHECKABLE ? 1 : 0);
+}