@codai/axiom-mcp 2.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @codai/axiom-mcp
 
-MCP server (stdio) and CLI for AXIOM v2 — the transactional write gate for coding agents:
+MCP server (stdio or Streamable HTTP) and CLI for AXIOM v2 — the transactional write gate for coding agents:
 `Plan` → canonical `ManifestBundle` → set-level checks → hash-gated two-phase `apply` → journal.
 `dist/cli.js` (thin entry) + `dist/cli-main.js` (lazy-loaded engines, SDK and zod bundled in); no runtime dependencies.
 
@@ -8,6 +8,7 @@ MCP server (stdio) and CLI for AXIOM v2 — the transactional write gate for cod
 
 ```sh
 npx @codai/axiom-mcp mcp --root /abs/path/to/repo          # stdio MCP server
+npx @codai/axiom-mcp mcp --root /abs/path/to/repo --http 127.0.0.1:3411   # Streamable HTTP at /mcp
 npx @codai/axiom-mcp --help                                # CLI verbs
 ```
 
@@ -28,6 +29,31 @@ root it is the default. There is **no** env-var or `cwd` fallback (`ERR_ROOT_REQ
 }
 ```
 
+### Streamable HTTP — `--http <host:port>`
+
+```sh
+axiom mcp --root /abs/repo --http 127.0.0.1:3411            # loopback, no token needed
+axiom mcp --root /abs/repo --http 0                          # random port; URL logged at info level
+AXIOM_HTTP_TOKEN=$(openssl rand -hex 32) axiom mcp --root /abs/repo --http 0.0.0.0:3411 --log-level info
+```
+
+- Endpoints: `POST /mcp` (an `initialize` opens a session and returns `Mcp-Session-Id`; every later
+  request must send it), `GET /mcp` (standalone SSE stream, one per session), `DELETE /mcp` (close the
+  session), `GET /health` → `{ ok, name, version }` (unauthenticated). Anything else is `404` JSON.
+- **Loopback by default.** A non-loopback host **refuses to start** unless a bearer token is present in
+  the env var named by `--http-token-env <NAME>` (default `AXIOM_HTTP_TOKEN`, ≥ 16 chars). Clients send
+  `Authorization: Bearer <token>`; the compare is constant-time. A token is optional on loopback.
+- DNS-rebinding protection is on for loopback binds (`Host` must be `<host>:<port>`, `localhost:<port>`
+  or `127.0.0.1:<port>`; otherwise `403`). Request bodies over 4 MiB are `413`.
+- Sessions idle for 30 minutes are evicted; each session has its own server instance (roots and guard
+  settings are shared). The transport lives in `dist/http-lazy.js`, loaded only with `--http`, and is
+  plain `node:http` — no express/hono at runtime.
+- VS Code: `{ "type": "http", "url": "http://127.0.0.1:3411/mcp" }`; add
+  `"headers": { "Authorization": "Bearer ${input:axiom-token}" }` when a token is set.
+
+Conformance: `packages/conformance` runs `@modelcontextprotocol/conformance server` against this transport
+in CI with an expected-failures baseline (`packages/conformance/baseline.yml`).
+
 ### Claude Desktop — `claude_desktop_config.json`
 
 ```json
@@ -44,7 +70,7 @@ root it is the default. There is **no** env-var or `cwd` fallback (`ERR_ROOT_REQ
 |---|---|---|---|
 | `axiom_plan_validate` | READ | `{ plan }` | `{ ok, planDigest?, errors[] }` |
 | `axiom_plan_compile` | ACT | `{ plan, store?: inline\|cas, root? }` | `ManifestBundle` (writes only under `<root>/.axiom/` — CAS blobs and the stored manifest — when a root is given) |
-| `axiom_manifest_verify` | READ | `{ bundle }` | `{ ok, manifestDigest, canonical, signed, missing[], errors[] }` |
+| `axiom_manifest_verify` | READ | `{ bundle, root? }` | `{ ok, manifestDigest, canonical, signed, missing[], errors[], signatures?: { trustFile, keyids[], findings[], ok } }` — `signatures` only when `root` has `.axiom/trust/keys.json` |
 | `axiom_check` | READ | `{ bundle, profile?, root? }` | `CheckReport` (`verdict: pass\|fail\|error`) |
 | `axiom_apply_dry_run` | READ | `{ bundle, root, profile? }` | `ApplyResult{mode:"dry-run", diff}` |
 | `axiom_apply` | SENSITIVE | `{ bundle, root, profile?, confirmDigest }` | `ApplyResult` |
@@ -52,6 +78,7 @@ root it is the default. There is **no** env-var or `cwd` fallback (`ERR_ROOT_REQ
 | `axiom_manifest_diff` | READ | `{ a: bundle\|"sha256:…", b }` | `{ added[], removed[], changed[] }` |
 | `axiom_axm_parse` | READ | `{ source }` (`.axm` text) | `{ plan?, diagnostics: [{ severity, code, message, range: { start: {line, column}, end } }] }` |
 | `axiom_roots_list` | READ | `{}` | `{ roots: [{ path, writable, hasGit }] }` |
+| `axiom_repo_snapshot` | READ | `{ root?, include?[], exclude?[], maxFiles? (20000, cap 50000), maxBytes? (64 MiB), respectGitignore? (true), withContentDigest? (true) }` | `RepoSnapshot { snapshotDigest, body: { files: [{ path, bytes, sha256?, mode, kind }], truncated, counts } }` — sorted, no timestamps/absolute paths; `.git/`, `.axiom/` always skipped; symlinks recorded, never followed (`docs/snapshot.md`) |
 
 Every tool carries MCP `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
 and an `outputSchema`; `structuredContent` is the full result, `content[0].text` a small summary (digest,
@@ -62,7 +89,8 @@ codai's `packages/agent-core/spec/tools-v2.json` entry shape (`{ name, risk, des
 see `docs/integration/codai.md`.
 
 Resources: `axiom://manifest/{sha}`, `axiom://report/{sha}`, `axiom://applied/{sha}`,
-`axiom://profile/{name}`, `axiom://schema/{Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal}`.
+`axiom://profile/{name}`, `axiom://schema/{Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal|RepoSnapshot}`,
+`axiom://emitters` (template emitters available to `axiom_plan_compile` — `web@2.0.0`, see `docs/emitters.md`).
 
 ## Trust model
 
@@ -79,23 +107,46 @@ Resources: `axiom://manifest/{sha}`, `axiom://report/{sha}`, `axiom://applied/{s
   absolute ones must be listed exactly via `--guard-allowlist <abs>` (repeatable). Guards are spawned
   with an args array (never a shell), a scrubbed environment, a wall-clock timeout, and must print
   `GuardOutput` JSON — see `docs/checks.md`.
+- **Signed manifests** (`docs/signing.md`): a root can pin Ed25519 public keys in
+  `.axiom/trust/keys.json`; a profile with `manifest.requireSigned` then refuses unsigned, tampered or
+  untrusted bundles, and with `antiRollback: true` refuses any `counter ≤ .axiom/trust/state.json#lastCounter`.
+  `axiom_apply` advances that state only on `status: "applied"`. Private keys never enter the server:
+  signing is `axiom sign` with `AXIOM_SIGNING_KEY` or `--key-file`.
 
 ## CLI
 
 ```
 axiom mcp     [--root <abs>]... [--allow-guards] [--guard-allowlist <abs>]... [--log-level warn]
-axiom compile <plan.json> [-o out.json] [--store cas --root .]
-axiom verify  <bundle.json>
+              [--http <host:port>] [--http-token-env AXIOM_HTTP_TOKEN]
+axiom compile <plan.json> [-o out.json] [--store cas --root .] [--allow-net [--net-allow host[,host]]] [--allow-file]
+axiom verify  <bundle.json> [--root .]          (--root: also verify signatures against .axiom/trust/keys.json)
 axiom check   <bundle.json> --root . [--profile p] [--json] [--allow-guards] [--guard-allowlist <abs>]...
 axiom apply   <bundle.json> --root . [--dry-run] [--profile p] [--confirm <digest>] [--allow-guards] [--guard-allowlist <abs>]...
 axiom rollback <digest> --root .
+axiom gc      --root . [--dry-run] [--older-than 30d] [--keep all-manifests|journal]   (CAS garbage collection; CLI only, no MCP tool)
 axiom diff    <a.json> <b.json>
-axiom schema  <Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal>
+axiom schema  <Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal|RepoSnapshot>
+axiom emitters [--json]
+axiom keygen  [--out <dir>] [--name <label>]     (ed25519; private key → <dir>/axiom-signing-<id>.key 0600, public entry → stdout)
+axiom sign    <bundle.json> [--key-file <path>] [-o out.json]   (key from --key-file or $AXIOM_SIGNING_KEY)
+axiom trust   add <pub.json> --root . | remove <keyid> --root . | list --root .
 axiom gate    --stdin [--root <dir>] [--profile <file>] [--strict] [--log-level warn]
+axiom migrate v1 <manifest.json> [-o plan.json] [--profile default] [--cas <root>] [--content <dir>] [--overwrite]
+                                               (v1 manifest → v2 Plan, lazy chunk; exit 1 = migrated with warnings — docs/migrate.md)
+axiom snapshot --root . [-o snap.json] [--include <glob>]... [--exclude <glob>]... [--max-files n] [--max-bytes n] [--no-gitignore] [--no-digest]
+axiom snapshot-diff <a.json> <b.json>          (RepoSnapshot → { added, removed, changed })
 ```
 
 Exit codes: `0` ok · `1` verdict fail / apply failed · `2` usage or error. Non-`mcp` verbs print JSON to stdout.
 
+`ref` sources (`{ type: "ref", uri, digest }`) are offline by default: a digest already in
+`<root>/.axiom/cas` resolves without network, anything else is `ERR_NET_DISABLED`. `--allow-net`
+fetches `https:` only (no redirects, 30 s timeout, 32 MiB cap), optionally restricted to
+`--net-allow` hosts (`*.example.com` wildcards), verifies the pinned digest and stores the blob in
+the CAS — a mismatch stores nothing (`ERR_DIGEST_MISMATCH`). `apply` never fetches. The MCP
+`axiom_plan_compile` tool has no network switch. See [docs/plan-format.md](../../docs/plan-format.md#ref-sources)
+and [docs/cas.md](../../docs/cas.md).
+
 ## Hook mode — `axiom gate --stdin`
 
 A PreToolUse hook for Claude Code, Copilot CLI and VS Code agent hooks. It reads **one** harness