@idemcore/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Don Wick
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# Idemcore MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give any MCP-capable assistant or agent (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Codex and others) two abilities:
+
+1. **Chat with a receipt.** Call an open model running on Idemcore and get back the answer together with a signed receipt that records which model, weights, inputs and settings produced it.
+2. **Verify a receipt.** Check any Idemcore receipt locally, with no network access and no account.
+
+Status: 0.1.0. Published as `@idemcore/mcp`. Verifies receipt formats r1 and r2.
+
+## Tools
+
+| Tool | Network | What it does |
+|---|---|---|
+| `idemcore_chat` | API key | Sends an OpenAI-compatible chat request, returns the answer, the receipt and a local signature check. Options: `privacy` (`hash_only` / `full`), `token_log` (`none` / `per_token`), `seed`, `model`, `max_tokens`, `temperature`. |
+| `idemcore_verify_receipt` | none | **L1**: format and Ed25519 signature against trusted Idemcore keys. **L2**: recomputes the chain digests from a public token log (`log_text` or `log_path`; one `pi j h hc` line per position plus `ALL <fnv>`). **Disclosure**: checks a prompt, output token ids or the displayed answer text against the receipt's hashes (salt needed for `hash_only`). |
+| `idemcore_get_receipt` | API key | Fetches a stored receipt (optionally with its per-token log) and verifies it. |
+| `idemcore_export_audit` | API key | Exports receipts and audit events for a time range, saves the bundle locally and checks the event hash chain and the signed daily Merkle roots. |
+| `idemcore_verify_audit` | none | Checks a saved audit bundle offline. |
+| `idemcore_trusted_keys` | optional | Lists the public keys used for signature checks and where each came from. |
+
+Verdicts: `VERIFIED` (all requested checks passed), `FAILED` (a signature, hash or chain does not match: the receipt or data was altered), `UNVERIFIED` (the signing key is not trusted or no key set could be loaded).
+
+## Configuration (environment)
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `IDEMCORE_API_KEY` | (none) | Your Idemcore API key. Needed only for chat, get and export. Sent only in the `Authorization` header, never echoed in tool output. |
+| `IDEMCORE_BASE_URL` | `https://api.idemcore.net` | API base URL (use your self-hosted gateway if you run Idemcore on-prem). |
+| `IDEMCORE_MODEL` | (server default) | Default model id for `idemcore_chat`. |
+| `IDEMCORE_TRUSTED_KEYS` | (none) | Path to a JWK / JWKS file of trusted signing keys. Use this for fully offline verification or for a self-hosted signer. |
+| `IDEMCORE_DEFAULT_KEYS` | `on` | The Idemcore production public key (`ed25519:2fab59995ac55e4f`, public half only) is bundled in `src/default-keys.ts` and trusted by default. Set `off` to trust only your file / `IDEMCORE_KEYS_URL`. |
+| `IDEMCORE_KEYS_URL` | `<base>/v1/keys` | Where to fetch the issuer's published keys. Set to `off` to disable. |
+| `IDEMCORE_EXPORT_DIR` | `./idemcore-exports` | Where audit exports are saved. |
+| `IDEMCORE_TIMEOUT_MS` | `120000` | Request timeout. |
+
+## Install
+
+Requires Node.js 20 or newer. Fastest path:
+
+```bash
+npx -y @idemcore/mcp
+```
+
+Or clone and build locally: `npm install && npm run build` (produces `dist/index.js`).
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "idemcore": {
+      "command": "npx",
+      "args": ["-y", "@idemcore/mcp"],
+      "env": { "IDEMCORE_API_KEY": "ick_..." }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add idemcore -e IDEMCORE_API_KEY=ick_... -- npx -y @idemcore/mcp
+```
+
+### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "idemcore": {
+      "command": "npx",
+      "args": ["-y", "@idemcore/mcp"],
+      "env": { "IDEMCORE_API_KEY": "ick_..." }
+    }
+  }
+}
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+```json
+{
+  "inputs": [{ "type": "promptString", "id": "idemcore-key", "description": "Idemcore API key", "password": true }],
+  "servers": {
+    "idemcore": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@idemcore/mcp"],
+      "env": { "IDEMCORE_API_KEY": "${input:idemcore-key}" }
+    }
+  }
+}
+```
+
+### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+Same shape as Cursor (`mcpServers` → `idemcore`).
+
+### Codex CLI (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.idemcore]
+command = "node"
+args = ["/path/to/idemcore-mcp/dist/index.js"]
+env = { IDEMCORE_API_KEY = "ick_..." }
+```
+
+### Verify-only (no account)
+
+Leave out `IDEMCORE_API_KEY`. `idemcore_verify_receipt` and `idemcore_verify_audit` still work; set `IDEMCORE_KEYS_URL=off` to run with no network at all (the bundled production key is still trusted; add `IDEMCORE_TRUSTED_KEYS=/path/to/idemcore-keys.json` for other signers).
+
+## Example prompts
+
+- "Ask Idemcore: summarise this contract clause, and keep the receipt."
+- "Verify this receipt and tell me whether the answer text matches it."
+- "Export last week's audit bundle and check it."
+
+## Receipt API assumptions
+
+The server reads the receipt from the response body field `idemcore_receipt`, or from the `Idemcore-Receipt` header (JSON or base64url JSON). For `hash_only` receipts it uses `idemcore_salt` (base64url) from the response, when present, to check the answer locally. Request options go in the `idemcore` object of the chat request.
+
+Displayed-text checks use the optional receipt field `output_text_hash` (proposed for r1): a tagged SHA-256 of the answer text after normalisation (Unicode NFC, every run of whitespace replaced by one space, leading and trailing space removed). The same rule is used by the Idemcore browser extension, so layout differences on a web page do not cause false alarms while any change of wording does.
+
+## Development
+
+```bash
+npm test     # vitest: reference vectors + MCP tools against a local mock API + stdio smoke test
+```
+
+`vectors/receipts-r1.json` is generated by `scripts/gen_vectors.py` from the reference receipts library with an ephemeral signing key that is discarded after generation; only the public key is stored.
+
+A remote (Streamable HTTP) variant for Cloudflare Workers can reuse `createServer()` from `src/server.ts`; it is not deployed yet.
+
+## License
+
+Apache-2.0. Copyright 2026 Don Wick. Contact: don.wick@idemcore.net

package/dist/api.js

@@ -0,0 +1,63 @@
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class IdemcoreApi {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    headers(json = true) {
+        if (!this.cfg.apiKey)
+            throw new ApiError(0, "IDEMCORE_API_KEY is not set; add it to the MCP server env");
+        const h = { authorization: `Bearer ${this.cfg.apiKey}`, "user-agent": "idemcore-mcp/0.1.0" };
+        if (json)
+            h["content-type"] = "application/json";
+        return h;
+    }
+    async call(method, path, body) {
+        const r = await this.cfg.fetchImpl(this.cfg.baseUrl + path, {
+            method, headers: this.headers(body !== undefined), body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(this.cfg.timeoutMs),
+        });
+        const text = await r.text();
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = { raw: text.slice(0, 2000) };
+        }
+        if (!r.ok) {
+            const msg = data?.error?.message ?? data?.error ?? data?.message ?? text.slice(0, 300);
+            throw new ApiError(r.status, `Idemcore API ${method} ${path} failed: HTTP ${r.status} ${typeof msg === "string" ? msg : JSON.stringify(msg)}`);
+        }
+        return { data, headers: r.headers };
+    }
+    chat(body) { return this.call("POST", "/v1/chat/completions", body); }
+    getReceipt(id, includeLog) {
+        return this.call("GET", `/v1/receipts/${encodeURIComponent(id)}${includeLog ? "?include_log=1" : ""}`);
+    }
+    exportAudit(body) { return this.call("POST", "/v1/audit/export", body); }
+}
+/** Receipt from the body field `idemcore_receipt` or the `Idemcore-Receipt` header (JSON or base64url JSON). */
+export function extractReceipt(data, headers) {
+    if (data && typeof data.idemcore_receipt === "object" && data.idemcore_receipt)
+        return data.idemcore_receipt;
+    const h = headers.get("idemcore-receipt");
+    if (!h)
+        return null;
+    try {
+        return JSON.parse(h);
+    }
+    catch { /* fall through */ }
+    try {
+        return JSON.parse(Buffer.from(h, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/audit.js

@@ -0,0 +1,61 @@
+// Offline checks for audit exports: hash-chained events and signed daily Merkle roots.
+import { canonicalBytes } from "./canonical.js";
+import { b64uDec, concat, hex, sha256, unhex, utf8 } from "./bytes.js";
+const GENESIS = "0".repeat(64);
+const EVENT_FIELDS = ["tenant_id", "seq", "ts", "event_type", "receipt_id", "actor", "payload", "prev_hash"];
+const ROOT_DOMAIN = utf8("idemcore-audit-root/r1\n");
+export async function eventHash(ev) {
+    const body = {};
+    for (const k of EVENT_FIELDS)
+        body[k] = ev[k] === undefined ? null : ev[k];
+    return hex(await sha256(concat(utf8("idemcore/audit/r1\0"), canonicalBytes(body))));
+}
+export async function verifyEventChain(events) {
+    const errs = [];
+    let prev = GENESIS, seq = null;
+    for (const ev of events) {
+        if (seq !== null && ev.seq !== seq + 1)
+            errs.push(`seq gap at ${ev.seq}`);
+        if (ev.prev_hash !== prev)
+            errs.push(`prev_hash mismatch at seq ${ev.seq}`);
+        if ((await eventHash(ev)) !== ev.event_hash)
+            errs.push(`event_hash mismatch at seq ${ev.seq}`);
+        prev = ev.event_hash;
+        seq = ev.seq;
+    }
+    return errs;
+}
+async function mth(items) {
+    if (items.length === 1)
+        return sha256(concat(new Uint8Array([0]), items[0]));
+    let k = 1;
+    while (k * 2 < items.length)
+        k *= 2;
+    return sha256(concat(new Uint8Array([1]), await mth(items.slice(0, k)), await mth(items.slice(k))));
+}
+export async function merkleRoot(hashesHex) {
+    if (!hashesHex.length)
+        return hex(await sha256(new Uint8Array(0)));
+    return hex(await mth(hashesHex.map(unhex)));
+}
+export async function verifyRoot(root, events, keys) {
+    const errs = [];
+    const pk = keys.find((k) => k.keyId === root.key_id);
+    const { signature, ...body } = root;
+    if (!pk)
+        errs.push(`unknown root key_id ${String(root.key_id)}`);
+    else {
+        let ok = false;
+        try {
+            ok = await pk.verify(b64uDec(String(signature)), concat(ROOT_DOMAIN, canonicalBytes(body)));
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            errs.push("root signature does not verify");
+    }
+    if ((await merkleRoot(events.map((e) => e.event_hash))) !== root.merkle_root)
+        errs.push("merkle_root mismatch");
+    return errs;
+}

package/dist/bytes.js

@@ -0,0 +1,42 @@
+const te = new TextEncoder();
+export const utf8 = (s) => te.encode(s);
+export function hex(b) {
+    const u = b instanceof Uint8Array ? b : new Uint8Array(b);
+    let s = "";
+    for (const x of u)
+        s += x.toString(16).padStart(2, "0");
+    return s;
+}
+export function unhex(s) {
+    if (s.length % 2)
+        throw new Error("odd hex length");
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(s.slice(2 * i, 2 * i + 2), 16);
+    return out;
+}
+export function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+export function b64u(b) {
+    return Buffer.from(b).toString("base64url");
+}
+export function b64uDec(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        throw new Error("not base64url");
+    return new Uint8Array(Buffer.from(s, "base64url"));
+}
+export async function sha256(data) {
+    return new Uint8Array(await crypto.subtle.digest("SHA-256", data));
+}
+export function le64(n) {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, BigInt.asUintN(64, n), true);
+    return b;
+}

package/dist/canonical.js

@@ -0,0 +1,34 @@
+// Canonical JSON for receipts r1: keys sorted by code point, no whitespace,
+// UTF-8, non-ASCII literal, integers only (no floats).
+function cmp(a, b) {
+    const A = Array.from(a), B = Array.from(b);
+    for (let i = 0; i < Math.min(A.length, B.length); i++) {
+        const d = A[i].codePointAt(0) - B[i].codePointAt(0);
+        if (d)
+            return d;
+    }
+    return A.length - B.length;
+}
+function enc(v, path) {
+    if (v === null)
+        return "null";
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    if (typeof v === "number") {
+        if (!Number.isSafeInteger(v))
+            throw new Error(`${path}: only integers are allowed`);
+        return String(v);
+    }
+    if (Array.isArray(v))
+        return "[" + v.map((x, i) => enc(x, `${path}[${i}]`)).join(",") + "]";
+    if (typeof v === "object") {
+        const o = v;
+        const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort(cmp);
+        return "{" + keys.map((k) => JSON.stringify(k) + ":" + enc(o[k], `${path}.${k}`)).join(",") + "}";
+    }
+    throw new Error(`${path}: unsupported type`);
+}
+export const canonicalString = (v) => enc(v, "$");
+export const canonicalBytes = (v) => new TextEncoder().encode(canonicalString(v));

package/dist/config.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { importKeySet } from "./keys.js";
+import { DEFAULT_TRUSTED_KEYS } from "./default-keys.js";
+export function configFromEnv(env = process.env) {
+    const baseUrl = (env.IDEMCORE_BASE_URL || "https://api.idemcore.net").replace(/\/+$/, "");
+    return {
+        baseUrl,
+        apiKey: env.IDEMCORE_API_KEY || undefined,
+        keysUrl: env.IDEMCORE_KEYS_URL === "off" ? undefined : (env.IDEMCORE_KEYS_URL || `${baseUrl}/v1/keys`),
+        trustedKeysFile: env.IDEMCORE_TRUSTED_KEYS || undefined,
+        defaultKeys: env.IDEMCORE_DEFAULT_KEYS !== "off",
+        exportDir: env.IDEMCORE_EXPORT_DIR || "./idemcore-exports",
+        timeoutMs: Number(env.IDEMCORE_TIMEOUT_MS || 120000),
+        fetchImpl: fetch,
+    };
+}
+/** Trusted key store: bundled production keys, a local file, then the issuer's published key set (cached). */
+export class KeyStore {
+    cfg;
+    cache = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async get() {
+        if (this.cache)
+            return { keys: this.cache, warnings: [] };
+        const keys = [], warnings = [];
+        if (this.cfg.defaultKeys !== false)
+            keys.push(...await importKeySet(DEFAULT_TRUSTED_KEYS, "bundled:idemcore-production"));
+        if (this.cfg.trustedKeysFile) {
+            try {
+                for (const k of await importKeySet(JSON.parse(readFileSync(this.cfg.trustedKeysFile, "utf8")), `file:${this.cfg.trustedKeysFile}`))
+                    if (!keys.some((x) => x.keyId === k.keyId))
+                        keys.push(k);
+            }
+            catch (e) {
+                warnings.push(`could not load trusted keys file: ${e.message}`);
+            }
+        }
+        if (this.cfg.keysUrl) {
+            try {
+                const r = await this.cfg.fetchImpl(this.cfg.keysUrl, { signal: AbortSignal.timeout(this.cfg.timeoutMs) });
+                if (!r.ok)
+                    throw new Error(`HTTP ${r.status}`);
+                for (const k of await importKeySet(await r.json(), this.cfg.keysUrl))
+                    if (!keys.some((x) => x.keyId === k.keyId))
+                        keys.push(k);
+            }
+            catch (e) {
+                warnings.push(`could not fetch issuer keys from ${this.cfg.keysUrl}: ${e.message}`);
+            }
+        }
+        if (keys.length)
+            this.cache = keys;
+        return { keys, warnings };
+    }
+}

package/dist/default-keys.js

@@ -0,0 +1,9 @@
+/**
+ * Idemcore production receipt-signing public keys (public halves only), bundled so that
+ * receipts verify offline without trusting the network. Rotations add entries here; the
+ * live set is also published at GET https://api.idemcore.net/v1/keys.
+ * Disable with IDEMCORE_DEFAULT_KEYS=off.
+ */
+export const DEFAULT_TRUSTED_KEYS = [
+    { kty: "OKP", crv: "Ed25519", x: "AdQX-eipjpmqi4GDvqYHIep2Vb7l5Vas4xncNN453OY", kid: "ed25519:2fab59995ac55e4f" },
+];

package/dist/hash.js

@@ -0,0 +1,78 @@
+// Domain-separated hashes and token-log chain digests (receipts r1).
+import { canonicalBytes } from "./canonical.js";
+import { concat, hex, le64, sha256, utf8 } from "./bytes.js";
+export async function taggedHash(tag, ...parts) {
+    const chunks = [utf8(`idemcore/${tag}/r1`), new Uint8Array([0])];
+    for (const p of parts)
+        chunks.push(le64(BigInt(p.length)), p);
+    return hex(await sha256(concat(...chunks)));
+}
+export function tokenBytes(ids) {
+    const b = new Uint8Array(ids.length * 4);
+    const dv = new DataView(b.buffer);
+    ids.forEach((id, i) => {
+        if (!Number.isInteger(id) || id < 0 || id > 0xffffffff)
+            throw new Error(`token id out of range at ${i}`);
+        dv.setUint32(i * 4, id, true);
+    });
+    return b;
+}
+export const promptHash = (messages, salt) => taggedHash("prompt", salt, canonicalBytes(messages));
+export const tokenHash = (ids, salt) => taggedHash("tokens", salt, tokenBytes(ids));
+// Display-text normalisation: NFC, every whitespace run becomes one U+0020, trimmed.
+const WS = /[\t\n\v\f\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+/g;
+export const normalizeText = (s) => s.normalize("NFC").replace(WS, " ").replace(/^ | $/g, "");
+/** Proposed optional field `output_text_hash`: binds the displayed answer text. */
+export const textHash = (text, salt) => taggedHash("text", salt, utf8(normalizeText(text)));
+export function parseLog(text) {
+    const lines = [];
+    let all = null;
+    text.split(/\r?\n/).forEach((raw, n) => {
+        const s = raw.trim();
+        if (!s || s.startsWith("#"))
+            return;
+        const f = s.split(/\s+/);
+        if (f[0] === "ALL") {
+            if (f.length !== 2 || !/^[0-9a-fA-F]{1,16}$/.test(f[1]))
+                throw new Error(`log line ${n + 1}: malformed ALL line`);
+            all = f[1].toLowerCase();
+            return;
+        }
+        if (!/^\d+$/.test(f[0]))
+            return; // reserved keyword lines
+        if (f.length !== 4)
+            throw new Error(`log line ${n + 1}: not a public log line (expected 4 fields: pi j h hc)`);
+        if (!/^\d+$/.test(f[1]) || !/^[0-9a-fA-F]{1,16}$/.test(f[2]) || !/^[0-9a-fA-F]{1,16}$/.test(f[3]))
+            throw new Error(`log line ${n + 1}: malformed field`);
+        const ln = { pi: BigInt(f[0]), j: BigInt(f[1]), h: BigInt("0x" + f[2]), hc: BigInt("0x" + f[3]) };
+        if (ln.pi >= 2n ** 64n || ln.j >= 2n ** 64n)
+            throw new Error(`log line ${n + 1}: index out of range`);
+        lines.push(ln);
+    });
+    return { lines, all };
+}
+const FNV_OFFSET = 0xcbf29ce484222325n, FNV_PRIME = 0x100000001b3n, MASK = (1n << 64n) - 1n;
+function fnv(data, start) {
+    let h = start;
+    for (const b of data)
+        h = ((h ^ BigInt(b)) * FNV_PRIME) & MASK;
+    return h;
+}
+export function chainFnv(lines) {
+    let a = FNV_OFFSET;
+    for (const l of lines) {
+        a = fnv(le64(l.h), a);
+        a = fnv(le64(l.hc), a);
+    }
+    return a.toString(16).padStart(16, "0");
+}
+export async function chainDigest(lines) {
+    let c = await sha256(utf8("idemcore/chain/r1\0"));
+    for (const l of lines)
+        c = await sha256(concat(c, le64(l.pi), le64(l.j), le64(l.h), le64(l.hc)));
+    return hex(c);
+}
+export async function logDigests(text) {
+    const p = parseLog(text);
+    return { positions: p.lines.length, chain_digest: await chainDigest(p.lines), chain_fnv: chainFnv(p.lines), all_line: p.all };
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { configFromEnv } from "./config.js";
+import { createServer, VERSION } from "./server.js";
+if (process.argv.includes("--version")) {
+    console.log(VERSION);
+    process.exit(0);
+}
+const server = createServer(configFromEnv());
+await server.connect(new StdioServerTransport());
+console.error(`idemcore-mcp ${VERSION} ready on stdio`);

package/dist/keys.js

@@ -0,0 +1,31 @@
+// Trusted Ed25519 public keys (JWK) for receipt signatures.
+import { b64uDec, hex, sha256 } from "./bytes.js";
+export async function keyIdFor(raw) {
+    return "ed25519:" + hex((await sha256(raw)).slice(0, 8));
+}
+export async function importJwk(jwk, source) {
+    if (jwk?.kty !== "OKP" || jwk?.crv !== "Ed25519" || typeof jwk.x !== "string")
+        throw new Error("not an Ed25519 public JWK");
+    const raw = b64uDec(jwk.x);
+    if (raw.length !== 32)
+        throw new Error("Ed25519 public key must be 32 bytes");
+    const keyId = await keyIdFor(raw);
+    if (jwk.kid && jwk.kid !== keyId)
+        throw new Error(`kid ${jwk.kid} does not match key bytes (${keyId})`);
+    const pk = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
+    return {
+        keyId, jwk: { kty: "OKP", crv: "Ed25519", x: jwk.x, kid: keyId }, source,
+        verify: async (sig, msg) => { try {
+            return await crypto.subtle.verify({ name: "Ed25519" }, pk, sig, msg);
+        }
+        catch {
+            return false;
+        } },
+    };
+}
+/** Accepts a JWK, an array of JWKs, or a JWKS ({ keys: [...] }). */
+export async function importKeySet(data, source) {
+    const list = Array.isArray(data) ? data : (data && typeof data === "object" && Array.isArray(data.keys))
+        ? data.keys : [data];
+    return Promise.all(list.map((j) => importJwk(j, source)));
+}

package/dist/receipt.js

@@ -0,0 +1,136 @@
+// Offline verification of Idemcore receipts r1 and r2 (L1 signature, L2 chain, disclosure).
+// r2 only renames seed→variant, chain_fnv→chain_check, kernel_version→engine_version; signing is identical.
+import { canonicalBytes, canonicalString } from "./canonical.js";
+import { b64uDec, concat, utf8 } from "./bytes.js";
+import { logDigests, promptHash, textHash, tokenHash } from "./hash.js";
+export const RECEIPT_VERSION = "r2";
+export const RECEIPT_VERSIONS = ["r1", "r2"];
+const R2_RENAMES = { seed: "variant", chain_fnv: "chain_check", kernel_version: "engine_version" };
+const SIG_DOMAIN = utf8("idemcore-receipt/r1\n");
+const HEX64 = /^[0-9a-f]{64}$/, HEX16 = /^[0-9a-f]{16}$/;
+const REQUIRED_R1 = {
+    receipt_version: "str", receipt_id: "str", issued_at: "str", tenant_id: "str", model_id: "str",
+    weights_hash: "str", kernel_version: "str", engine_build: "str", privacy: "str", prompt_hash: "str",
+    params_hash: "str", seed: "int", decoding: "str", prompt_tokens: "int", output_tokens: "int",
+    output_token_hash: "str", chain_digest: "str", chain_fnv: "str", log_ref: "str", key_id: "str", signature: "str",
+};
+const REQUIRED_R2 = Object.fromEntries(Object.entries(REQUIRED_R1).map(([k, t]) => [R2_RENAMES[k] ?? k, t]));
+/** Name of the 16-hex chain check field for this receipt's version. */
+export const chainCheckField = (r) => (r.receipt_version === "r2" ? "chain_check" : "chain_fnv");
+// output_text_hash is a proposed optional field (see EMBED_SPEC in the extension repo).
+const OPTIONAL = { finish_reason: "str", request_id: "str", output_text_hash: "str" };
+const HASH_FIELDS = ["weights_hash", "prompt_hash", "params_hash", "output_token_hash", "chain_digest"];
+const result = (level, errors, extra = {}) => ({ level, ok: errors.length === 0, errors, ...extra });
+export function signingPayload(r) {
+    const { signature: _s, ...body } = r;
+    return concat(SIG_DOMAIN, canonicalBytes(body));
+}
+export function checkFormat(r) {
+    if (typeof r !== "object" || r === null || Array.isArray(r))
+        return ["receipt is not an object"];
+    const o = r, errs = [];
+    if (!RECEIPT_VERSIONS.includes(o.receipt_version))
+        return [`unsupported receipt_version ${String(o.receipt_version)}`];
+    const REQUIRED = o.receipt_version === "r2" ? REQUIRED_R2 : REQUIRED_R1, CHK = chainCheckField(o);
+    for (const [k, t] of Object.entries(REQUIRED)) {
+        if (!(k in o))
+            errs.push(`missing field ${k}`);
+        else if (t === "int" ? !Number.isSafeInteger(o[k]) : typeof o[k] !== "string")
+            errs.push(`field ${k} must be ${t}`);
+    }
+    for (const k of Object.keys(o))
+        if (!(k in REQUIRED) && !(k in OPTIONAL))
+            errs.push(`unknown field ${k}`);
+    for (const k of Object.keys(OPTIONAL))
+        if (k in o && typeof o[k] !== "string")
+            errs.push(`field ${k} must be str`);
+    if (errs.length)
+        return errs;
+    for (const k of HASH_FIELDS)
+        if (!HEX64.test(o[k]))
+            errs.push(`${k} must be 64 lowercase hex`);
+    if ("output_text_hash" in o && !HEX64.test(o.output_text_hash))
+        errs.push("output_text_hash must be 64 lowercase hex");
+    if (!HEX16.test(o[CHK]))
+        errs.push(`${CHK} must be 16 lowercase hex`);
+    if (o.privacy !== "hash_only" && o.privacy !== "full")
+        errs.push("privacy must be hash_only or full");
+    if (o.prompt_tokens < 1 || o.output_tokens < 0)
+        errs.push("token counts out of range");
+    if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d{1,6})?Z$/.test(o.issued_at))
+        errs.push("issued_at must be RFC 3339 UTC (Z)");
+    try {
+        canonicalString(o);
+    }
+    catch (e) {
+        errs.push(e.message);
+    }
+    return errs;
+}
+export async function verifyL1(r, keys) {
+    const errs = checkFormat(r);
+    if (errs.length)
+        return result("L1", errs);
+    const rc = r;
+    const pk = keys.find((k) => k.keyId === rc.key_id);
+    if (!pk)
+        return result("L1", [`unknown key_id ${String(rc.key_id)} (not in the trusted key set)`]);
+    let sig;
+    try {
+        sig = b64uDec(rc.signature);
+    }
+    catch {
+        return result("L1", ["signature is not base64url"]);
+    }
+    if (sig.length !== 64 || !(await pk.verify(sig, signingPayload(rc))))
+        return result("L1", ["signature does not verify"]);
+    return result("L1", [], { key_id: pk.keyId, key_source: pk.source });
+}
+export async function verifyL2(r, logText) {
+    let d;
+    try {
+        d = await logDigests(logText);
+    }
+    catch (e) {
+        return result("L2", [`log parse error: ${e.message}`]);
+    }
+    const errs = [];
+    if (d.chain_digest !== r.chain_digest)
+        errs.push("chain_digest mismatch");
+    const CHK = chainCheckField(r);
+    if (d.chain_fnv !== r[CHK])
+        errs.push(`${CHK} mismatch`);
+    if (d.all_line !== null && d.all_line !== d.chain_fnv)
+        errs.push("log ALL line inconsistent with its own lines");
+    const want = Number(r.prompt_tokens ?? 0) + Number(r.output_tokens ?? 0);
+    if (d.positions !== want)
+        errs.push(`log covers ${d.positions} positions, receipt says ${want}`);
+    return result("L2", errs, { positions: d.positions });
+}
+export async function verifyDisclosure(r, d) {
+    const salt = r.privacy === "full" ? new Uint8Array(0) : d.salt;
+    if (salt == null)
+        return result("disclosure", ["salt required for hash_only receipts"]);
+    const errs = [], checked = [];
+    if (d.messages !== undefined) {
+        checked.push("prompt_hash");
+        if ((await promptHash(d.messages, salt)) !== r.prompt_hash)
+            errs.push("prompt_hash mismatch");
+    }
+    if (d.outputIds !== undefined) {
+        checked.push("output_token_hash");
+        if ((await tokenHash(d.outputIds, salt)) !== r.output_token_hash)
+            errs.push("output_token_hash mismatch");
+    }
+    if (d.outputText !== undefined) {
+        if (typeof r.output_text_hash !== "string") {
+            errs.push("receipt has no output_text_hash; displayed text cannot be bound (use output token ids instead)");
+        }
+        else {
+            checked.push("output_text_hash");
+            if ((await textHash(d.outputText, salt)) !== r.output_text_hash)
+                errs.push("output_text_hash mismatch");
+        }
+    }
+    return result("disclosure", errs, { checked });
+}

package/dist/server.js

@@ -0,0 +1,252 @@
+import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ApiError, extractReceipt, IdemcoreApi } from "./api.js";
+import { KeyStore } from "./config.js";
+import { importKeySet } from "./keys.js";
+import { b64uDec } from "./bytes.js";
+import { verifyDisclosure, verifyL1, verifyL2 } from "./receipt.js";
+import { verifyEventChain, verifyRoot } from "./audit.js";
+export const VERSION = "0.1.0";
+const out = (summary, data, isError = false) => ({ content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(data, null, 2)}` }], ...(isError ? { isError } : {}) });
+const fail = (e) => out(`Error: ${e.message}`, { error: e.message, status: e instanceof ApiError ? e.status : undefined }, true);
+function parseReceipt(x) {
+    if (typeof x === "string") {
+        const s = x.trim();
+        try {
+            return JSON.parse(s);
+        }
+        catch { /* maybe base64url */ }
+        return JSON.parse(Buffer.from(s, "base64url").toString("utf8"));
+    }
+    if (x && typeof x === "object" && !Array.isArray(x)) {
+        const o = x;
+        if (o.receipt && typeof o.receipt === "object")
+            return o.receipt; // embed envelope
+        return o;
+    }
+    throw new Error("receipt must be a JSON object or string");
+}
+function verdict(parts) {
+    if (parts.some((p) => !p.ok && !String(p.errors[0] ?? "").startsWith("unknown key_id")))
+        return "FAILED";
+    if (parts.some((p) => !p.ok))
+        return "UNVERIFIED";
+    return "VERIFIED";
+}
+export async function verifyAll(input, keyStore) {
+    const receipt = parseReceipt(input.receipt);
+    const { keys, warnings } = await keyStore.get();
+    let all = keys;
+    if (input.extra_keys !== undefined)
+        all = [...keys, ...await importKeySet(input.extra_keys, "caller-supplied")];
+    const checks = [await verifyL1(receipt, all)];
+    const logText = input.log_text ?? (input.log_path ? readFileSync(input.log_path, "utf8") : undefined);
+    if (logText !== undefined)
+        checks.push(await verifyL2(receipt, logText));
+    if (input.messages !== undefined || input.output_ids !== undefined || input.output_text !== undefined) {
+        checks.push(await verifyDisclosure(receipt, {
+            messages: input.messages, outputIds: input.output_ids, outputText: input.output_text,
+            salt: input.salt_b64u !== undefined ? b64uDec(input.salt_b64u) : null,
+        }));
+    }
+    const v = verdict(checks);
+    if (checks[0].ok && checks[0].key_source === "caller-supplied")
+        warnings.push("signature checked against a caller-supplied key, not an Idemcore-published key");
+    return {
+        verdict: v,
+        receipt_id: receipt.receipt_id, model_id: receipt.model_id, issued_at: receipt.issued_at, privacy: receipt.privacy,
+        checks, warnings,
+        note: logText === undefined ? "L2 not run: pass log_text or log_path to recompute the token-log chain" : undefined,
+    };
+}
+const message = z.object({ role: z.enum(["system", "user", "assistant"]), content: z.string() });
+export function createServer(cfg) {
+    const api = new IdemcoreApi(cfg);
+    const keyStore = new KeyStore(cfg);
+    const server = new McpServer({ name: "idemcore", version: VERSION });
+    server.registerTool("idemcore_chat", {
+        title: "Chat with a signed receipt",
+        description: "Send a chat request to an open model running on Idemcore (OpenAI-compatible API). Returns the answer plus a signed receipt that proves which model, inputs and settings produced it, and checks the receipt signature locally.",
+        inputSchema: {
+            prompt: z.string().optional().describe("User message. Use this or `messages`."),
+            messages: z.array(message).optional().describe("Full chat history in OpenAI format."),
+            system: z.string().optional().describe("Optional system message, prepended when using `prompt`."),
+            model: z.string().optional().describe("Model id; defaults to IDEMCORE_MODEL or the server default."),
+            max_tokens: z.number().int().positive().max(32768).optional(),
+            temperature: z.number().min(0).max(2).optional(),
+            seed: z.number().int().optional().describe("Sampling seed recorded in the receipt."),
+            privacy: z.enum(["hash_only", "full"]).optional().describe("hash_only (default on the API) keeps only salted hashes."),
+            token_log: z.enum(["none", "per_token"]).optional().describe("per_token keeps a per-token log so L2 can be checked later."),
+            verify: z.boolean().default(true).describe("Check the receipt signature locally (offline)."),
+        },
+    }, async (a) => {
+        try {
+            const messages = a.messages ?? [...(a.system ? [{ role: "system", content: a.system }] : []), ...(a.prompt !== undefined ? [{ role: "user", content: a.prompt }] : [])];
+            if (!messages.length)
+                throw new Error("pass `prompt` or `messages`");
+            const model = a.model ?? process.env.IDEMCORE_MODEL;
+            const idem = {};
+            if (a.privacy)
+                idem.privacy = a.privacy;
+            if (a.token_log)
+                idem.token_log = a.token_log;
+            if (a.seed !== undefined)
+                idem.seed = a.seed;
+            const body = { messages, ...(model ? { model } : {}), stream: false };
+            if (a.max_tokens !== undefined)
+                body.max_tokens = a.max_tokens;
+            if (a.temperature !== undefined)
+                body.temperature = a.temperature;
+            if (a.seed !== undefined)
+                body.seed = a.seed;
+            if (Object.keys(idem).length)
+                body.idemcore = idem;
+            const { data, headers } = await api.chat(body);
+            const answer = data?.choices?.[0]?.message?.content ?? "";
+            const receipt = extractReceipt(data, headers);
+            let verification = receipt ? undefined : { verdict: "UNVERIFIED", checks: [], warnings: ["the API response carried no receipt"] };
+            if (receipt && a.verify) {
+                const salt = typeof data?.idemcore_salt === "string" ? data.idemcore_salt : undefined;
+                verification = await verifyAll({
+                    receipt, messages,
+                    ...(typeof receipt.output_text_hash === "string" && (receipt.privacy === "full" || salt) ? { output_text: answer, salt_b64u: salt } : {}),
+                }, keyStore);
+            }
+            const v = verification?.verdict ?? "NOT_CHECKED";
+            return out(`${answer}\n\n— Idemcore receipt ${String(receipt?.receipt_id ?? "missing")}: ${v}`, {
+                answer, model: data?.model, finish_reason: data?.choices?.[0]?.finish_reason, usage: data?.usage,
+                receipt, verification,
+            });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("idemcore_verify_receipt", {
+        title: "Verify a receipt offline",
+        description: "Verify an Idemcore receipt without calling the API: L1 checks format and the Ed25519 signature against trusted Idemcore keys; L2 recomputes the token-log chain digests from a log; optional disclosure checks that a prompt, token ids or displayed text match the receipt's hashes.",
+        inputSchema: {
+            receipt: z.union([z.string(), z.record(z.string(), z.any())]).describe("Receipt JSON (object, JSON string, base64url JSON, or an embed envelope {receipt, ...})."),
+            log_text: z.string().optional().describe("Per-token log text for L2."),
+            log_path: z.string().optional().describe("Path to a per-token log file for L2."),
+            messages: z.array(message).optional().describe("Disclosed prompt messages to check against prompt_hash."),
+            output_ids: z.array(z.number().int().nonnegative()).optional().describe("Disclosed output token ids to check against output_token_hash."),
+            output_text: z.string().optional().describe("Displayed answer text to check against output_text_hash (if the receipt carries it)."),
+            salt_b64u: z.string().optional().describe("Salt (base64url) for hash_only receipts; not needed for privacy=full."),
+            extra_keys: z.any().optional().describe("Extra public JWK / JWKS to trust for this call (e.g. a self-hosted signer)."),
+        },
+    }, async (a) => {
+        try {
+            const r = await verifyAll(a, keyStore);
+            return out(`Receipt ${String(r.receipt_id)}: ${r.verdict}`, r, r.verdict === "FAILED");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("idemcore_get_receipt", {
+        title: "Fetch a stored receipt",
+        description: "Fetch a receipt (and optionally its per-token log) from the tenant's Idemcore receipt store, then verify it locally.",
+        inputSchema: {
+            receipt_id: z.string().regex(/^[A-Za-z0-9_.:-]{1,128}$/),
+            include_log: z.boolean().default(false),
+            verify: z.boolean().default(true),
+        },
+    }, async (a) => {
+        try {
+            const { data, headers } = await api.getReceipt(a.receipt_id, a.include_log);
+            const receipt = (data?.receipt && typeof data.receipt === "object") ? data.receipt : (extractReceipt(data, headers) ?? data);
+            const logText = typeof data?.log_text === "string" ? data.log_text : undefined;
+            const verification = a.verify ? await verifyAll({ receipt, log_text: logText }, keyStore) : undefined;
+            return out(`Receipt ${a.receipt_id}: ${verification?.verdict ?? "NOT_CHECKED"}`, { receipt, has_log: logText !== undefined, verification });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("idemcore_export_audit", {
+        title: "Export an audit bundle",
+        description: "Export the tenant's receipts and audit events for a time range, save them to a local file, and check the event hash chain and signed daily Merkle roots offline.",
+        inputSchema: {
+            from: z.string().describe("Start (RFC 3339 or YYYY-MM-DD, UTC)."),
+            to: z.string().describe("End (RFC 3339 or YYYY-MM-DD, UTC)."),
+            include_logs: z.boolean().default(false),
+            save: z.boolean().default(true).describe("Write the bundle under IDEMCORE_EXPORT_DIR."),
+        },
+    }, async (a) => {
+        try {
+            const { data } = await api.exportAudit({ from: a.from, to: a.to, include_logs: a.include_logs, format: "json" });
+            const check = await checkBundle(data, keyStore);
+            let saved;
+            if (a.save) {
+                const dir = resolve(cfg.exportDir);
+                mkdirSync(dir, { recursive: true });
+                saved = join(dir, `idemcore-audit-${a.from}_${a.to}.json`.replace(/[^A-Za-z0-9_.-]/g, "_").replace(/^_+/, ""));
+                saved = join(dir, saved.split("/").pop());
+                writeFileSync(saved, JSON.stringify(data, null, 1));
+            }
+            return out(`Audit export ${a.from} → ${a.to}: ${check.verdict}`, { saved_to: saved, ...check });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("idemcore_verify_audit", {
+        title: "Verify an audit bundle offline",
+        description: "Check an exported audit bundle (JSON file with `events`, `roots` and optional `receipts`) offline: event hash chain, signed Merkle roots and every receipt signature.",
+        inputSchema: { path: z.string().describe("Path to the exported bundle JSON.") },
+    }, async (a) => {
+        try {
+            const check = await checkBundle(JSON.parse(readFileSync(a.path, "utf8")), keyStore);
+            return out(`Audit bundle ${a.path}: ${check.verdict}`, check, check.verdict === "FAILED");
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("idemcore_trusted_keys", {
+        title: "List trusted signing keys",
+        description: "Show which Idemcore public keys this server trusts for receipt signatures and where each came from.",
+        inputSchema: {},
+    }, async () => {
+        const { keys, warnings } = await keyStore.get();
+        return out(`${keys.length} trusted key(s)`, { keys: keys.map((k) => ({ key_id: k.keyId, source: k.source, jwk: k.jwk })), warnings, base_url: cfg.baseUrl });
+    });
+    return server;
+}
+export async function checkBundle(data, keyStore) {
+    const { keys, warnings } = await keyStore.get();
+    const events = Array.isArray(data?.events) ? data.events : [];
+    const roots = Array.isArray(data?.roots) ? data.roots : [];
+    const receipts = Array.isArray(data?.receipts) ? data.receipts : [];
+    const errors = [];
+    const byTenant = new Map();
+    for (const e of events) {
+        const t = String(e.tenant_id);
+        if (!byTenant.has(t))
+            byTenant.set(t, []);
+        byTenant.get(t).push(e);
+    }
+    for (const [t, evs] of byTenant)
+        for (const er of await verifyEventChain(evs.sort((x, y) => x.seq - y.seq)))
+            errors.push(`tenant ${t}: ${er}`);
+    for (const root of roots) {
+        const evs = events.filter((e) => e.tenant_id === root.tenant_id && e.seq >= Number(root.first_seq) && e.seq <= Number(root.last_seq));
+        for (const er of await verifyRoot(root, evs, keys))
+            errors.push(`root ${String(root.day)}: ${er}`);
+    }
+    let receiptsOk = 0;
+    for (const r of receipts) {
+        const res = await verifyL1(r, keys);
+        if (res.ok)
+            receiptsOk++;
+        else
+            errors.push(`receipt ${String(r.receipt_id)}: ${res.errors.join("; ")}`);
+    }
+    return {
+        verdict: (errors.length ? "FAILED" : "VERIFIED"),
+        events: events.length, roots: roots.length, receipts: receipts.length, receipts_ok: receiptsOk, errors, warnings,
+    };
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@idemcore/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for Idemcore: chat with signed receipts and verify them offline.",
+  "author": "Don Wick <don.wick@idemcore.net>",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "idemcore-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/idemcore/idemcore-mcp.git"
+  },
+  "homepage": "https://github.com/idemcore/idemcore-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/idemcore/idemcore-mcp/issues"
+  },
+  "keywords": [
+    "idemcore",
+    "mcp",
+    "model-context-protocol",
+    "receipts",
+    "verification"
+  ]
+}