Merge pull request #56 from ScriptKittyOS/slice/061-mcp-server

feat(s061): complete slice 061 (MCP server)

Signed-off-by: Ayla Croft <aylacroft@proton.me>

Author: HackTuah

.dockerignore

@@ -0,0 +1,10 @@
+_build
+_build_pg
+deps
+burrito_out
+src-tauri/target
+node_modules
+assets/node_modules
+*.db
+*.db-*
+.env*

README.md

@@ -40,10 +40,14 @@ that means in practice:
   2025-11-25 as the fallback. Every tool a server lists becomes a tool the assistant can call,
   namespaced so it can never borrow a built-in tool's permissions, asking you until you write a
   rule; every result is marked untrusted; and when a server needs input mid-call it asks you,
-  on the permissions page, before the call continues.
-
-Not there yet: scheduled tasks and the rest of MCP (M5a: Trinity as an MCP server with approvals,
-and the authorization roles), messaging gateways and subagents (M5b),
+  on the permissions page, before the call continues. The other direction too: Trinity is an
+  MCP server at `POST /mcp` (and over stdio), exporting the read-only tools by default and
+  any others you name; a client's call passes the same gate and leaves the same receipts as
+  the assistant's own, and one that needs your approval waits for it on the permissions page
+  while the client carries a sealed state it can retry with. A headless release runs the same
+  tree as a server, in a container or under systemd (`docs/mcp-server.md`).
+
+Not there yet: scheduled tasks and MCP's authorization roles (M5a), messaging gateways and subagents (M5b),
 the native desktop shell and signed releases (M6), executable skills in a sandbox (M7). `ROADMAP.md` carries the live status of every
 slice, and the [Milestones](#milestones) section below explains how to read it.
 
@@ -150,6 +154,7 @@ later without renumbering anything.
 | `VERSIONS.md` | The verified dependency versions, generated from `lib/trinity/versions.ex` |
 | `CLAUDE.md` | The engineering contract: slice rules, definition of done, proof standard |
 | `docs/` | Vision, architecture, tech stack, conventions, slice process, data model, risks, security model, standards; packaging, the FIPS leg, backup and restore, performance measurements |
+| `docs/mcp-server.md` | Connecting a client to Trinity's MCP server (Claude Code, VS Code, Codex, goose), stdio, approvals over the wire, the headless profile |
 | `slices/059-mcp-library-spike/FINDINGS.md` | What the MCP server core (`beam_mcp`) ships, carries, refuses or leaves open against the 2026-07-28 checklist; the reference for the MCP phase |
 | `docs/adr/` | Architecture decision records. One is added whenever a decision changes |
 | `slices/` | One folder per slice: specification, notes and proof |

ROADMAP.md

@@ -54,7 +54,7 @@ standards register names the rows that ask for them.
 | 050 | Scheduler: Oban cron agent tasks with delivery targets | 5 Automation | M | 012 | planned |
 | 059 | MCP capability gap against beam_mcp, and the server seam probe | 6 MCP | S/M | 020 | approved |
 | 060 | MCP client: Trinity's thin driver (2026-07-28 preferred, 2025-11-25 compat, MRTR, Tasks) | 6 MCP | L | 059, 021 | approved |
-| 061 | MCP server (stateless 2026-07-28 + compat, MRTR approvals, headless profile) | 6 MCP | M | 060, 024 | planned |
+| 061 | MCP server (stateless 2026-07-28 + compat, MRTR approvals, headless profile) | 6 MCP | M | 060, 024 | done |
 | 062 | MCP authorization: OAuth client role, RS, embedded AS, Enterprise Managed Authorization (ID-JAG) | 6 MCP | L | 061 | planned |
 | 070 | Gateway core: adapter behaviour, routing, PubSub fan-out | 7 Gateways | M | 012 | planned |
 | 071 | Gateway: Telegram | 7 Gateways | S | 070 | planned |

VERSIONS.md

@@ -91,7 +91,7 @@ never pin a version hex marks as retired or vulnerable.
 | `oban` | ~> 2.24 | 🔍 not yet a dependency | Uses `Oban.Engines.Lite` on SQLite. ⚠️ Oban Pro Workflows/Smart engine are Postgres-only. Added at Slice 050. |
 | `req` | ~> 0.5 | ✅ in `mix.lock` | HTTP client. |
 | `req_llm` | ~> 1.22 | ✅ in `mix.lock` | Provider layer (streaming, tools, structured output, usage). ⚠️ The pin was `~> 1.10` against a recorded latest of 1.10.0; the real latest was twelve minors ahead. Check event shapes against the current version at Slice 011, not against this file's prose. Added at Slice 011. |
-| `beam_mcp` | ~> 0.8 | ✅ in `mix.lock` | MCP server core, Apache-2.0, ADR-0007 decision 5 (owner decision 2026-09-08, recorded 2026-09-20). 0.8.0 on hex.pm, standing before 1.0.0. Server side only: the client, MRTR and OAuth are Trinity's, above it. Added at Slice 059. The earlier candidate list (anubis_mcp, fastest_mcp, gen_mcp) is history. |
+| `beam_mcp` | ~> 0.9 | ✅ in `mix.lock` | MCP server core, Apache-2.0, ADR-0007 decision 5 (owner decision 2026-09-08, recorded 2026-09-20). 0.9.0 on hex.pm (2026-09-22): the :server seam on both transports and the core server as a named behaviour, which slice 061's wrapper implements; standing before 1.0.0. Server side only: the client, MRTR and OAuth are Trinity's, above it. Added at Slice 059, bumped at 061. The earlier candidate list (anubis_mcp, fastest_mcp, gen_mcp) is history. |
 | `jido` | not used (ADR-0009, decided 2026-09-20) | 🔍 not a single package | Measured at the Slice 012 checkpoint and not adopted: the agent runtime duplicates PubSub, Oban and the gateways and adds a second tool executor; the action shape is written in-tree at Slice 020 with `jsv` for its schemas. The row stays so the decision is visible where a reader would look for the package. |
 | `jason` | ~> 1.2 | ✅ in `mix.lock` |  |
 | `boundary` | ~> 0.10 | ✅ in `mix.lock` | Compile-time module dependency enforcement. Measured at Slice 000: it compiles and enforces on Elixir 1.20.4 / OTP 28, and it reports violations as **warnings**, so it enforces only while `--warnings-as-errors` is on the compile step. ⚠️ No release since 2024-09-25. |

ci/headless/Containerfile

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+#
+# Slice 061: the headless release in a container. Two stages: the release is assembled on the
+# Elixir image whose toolchain is the tree's (.tool-versions: Erlang 28.5.0.5, Elixir 1.20.4),
+# then copied onto a slim Debian of the same generation, so the ERTS the release carries finds
+# the libc it was built against. No desktop shell, no Burrito: `mix release headless`.
+#
+#   docker build -f ci/headless/Containerfile -t trinity-headless:local .
+#   docker run --rm -p 4000:4000 -e TRINITY_MCP_SERVER_TOKEN=... trinity-headless:local
+#
+# The container binds 0.0.0.0 inside its own network namespace (TRINITY_BIND) so the published
+# port reaches it; the bearer is required on /mcp whatever the bind. The data directory is
+# /data/trinity (XDG_DATA_HOME=/data, a volume): the databases, the receipt keys, the
+# envelope key, the generated token.
+FROM hexpm/elixir:1.20.4-erlang-28.5.0.5-debian-bookworm-20260824-slim AS build
+
+RUN apt-get update -y && apt-get install -y --no-install-recommends \
+      build-essential git curl ca-certificates cmake python3 pkg-config \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+ENV MIX_ENV=prod LANG=C.UTF-8
+RUN mix local.hex --force && mix local.rebar --force
+
+COPY mix.exs mix.lock ./
+COPY config config
+RUN mix deps.get --only prod
+
+COPY lib lib
+COPY priv priv
+COPY assets assets
+RUN mix assets.deploy && mix compile && mix release headless --overwrite
+
+FROM debian:bookworm-20260824-slim AS app
+
+RUN apt-get update -y && apt-get install -y --no-install-recommends \
+      libstdc++6 openssl libncurses6 ca-certificates curl locales \
+    && apt-get clean && rm -rf /var/lib/apt/lists/* \
+    && sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
+
+ENV LANG=en_US.UTF-8 LANGUAGE=en_US:en LC_ALL=en_US.UTF-8
+ENV TRINITY_MODE=headless TRINITY_BIND=0.0.0.0 PORT=4000 XDG_DATA_HOME=/data
+WORKDIR /app
+RUN useradd --create-home --uid 10001 trinity && mkdir -p /data && chown trinity:trinity /data /app
+COPY --from=build --chown=trinity:trinity /app/_build/prod/rel/headless ./
+USER trinity
+VOLUME ["/data"]
+EXPOSE 4000
+CMD ["bin/headless", "start"]

config/runtime.exs

@@ -28,7 +28,10 @@ smoke? =
   "--smoke" in Enum.map(:init.get_plain_arguments(), &to_string/1) or
     System.get_env("TRINITY_SMOKE") == "1"
 
-if System.get_env("PHX_SERVER") || smoke? do
+# Slice 061: the headless profile is a server by definition.
+headless? = System.get_env("TRINITY_MODE") == "headless"
+
+if System.get_env("PHX_SERVER") || smoke? || headless? do
   config :trinity, TrinityWeb.Endpoint, server: true
 end
 
@@ -156,9 +159,33 @@ if config_env() == :prod do
   # LAN without asking. PORT still wins where it is set, which is how ex_tauri drives it.
   desktop_port = String.to_integer(System.get_env("PORT") || "0")
 
+  # Slice 061: the headless profile binds the address it is told (`TRINITY_BIND`, loopback by
+  # default: a server on a LAN is the operator's decision, made by setting it) on `PORT`,
+  # 4000 by default, since nobody reads an ephemeral port off a headless machine. The bearer
+  # on /mcp (`TRINITY_MCP_SERVER_TOKEN`, or the generated token file) is required whatever
+  # the bind; the web pages carry no authentication yet, which is why the default stays on
+  # the loopback (docs/mcp-server.md).
+  {bind_ip, bind_port} =
+    if System.get_env("TRINITY_MODE") == "headless" do
+      ip =
+        case System.get_env("TRINITY_BIND", "127.0.0.1")
+             |> String.to_charlist()
+             |> :inet.parse_address() do
+          {:ok, ip} ->
+            ip
+
+          {:error, _} ->
+            raise "TRINITY_BIND is not an IP address: #{System.get_env("TRINITY_BIND")}"
+        end
+
+      {ip, String.to_integer(System.get_env("PORT") || "4000")}
+    else
+      {{127, 0, 0, 1}, desktop_port}
+    end
+
   config :trinity, TrinityWeb.Endpoint,
     url: [host: host, port: 443, scheme: "https"],
-    http: [ip: {127, 0, 0, 1}, port: desktop_port],
+    http: [ip: bind_ip, port: bind_port],
     secret_key_base: secret_key_base
 
   # ## SSL Support

coverage.tsv

@@ -20,3 +20,4 @@ slice_id	percent	sha	date
 041	80.55	ae200d7	2026-09-21
 059	80.54	53c9091	2026-09-21
 060	80.32	49f40a4	2026-09-21
+061	80.05	c6b6faa	2026-09-22

docs/01-architecture.md

@@ -90,7 +90,7 @@ without anything failing.
 | `Trinity.Memory` | Always-on tiers with their budget and consolidator (030), search (031), semantic store and retrieval (032), compaction (023) | LLM (summaries/embeddings), Repo |
 | `Trinity.Skills` | SKILL.md parsing, registry, loader, manager, scanner (as built at 040: parser, sources, registry, index, the three tools; at 041: staging, promotion, manager, scanner, diff, learn, `skill_manage` and `learn`) | Repo, Permissions, **Effects**, **Receipts**, Sandbox (as built at 041: Tools, Memory, Permissions, Receipts and LLM; Effects is not a dependency: the promotion is not a tool call, it writes its own effect receipt; Tools never depends on Skills) |
 | `Trinity.Scheduler` | Oban workers for agent tasks, delivery | Sessions, Gateways, **Repo** |
-| `Trinity.MCP` | Client manager, tool bridge, server (as built at 059: the boundary alone, holding the core's version, its JSON depth and its telemetry event names; at 060: `Servers` and `ServerConfig` (the rows), `Supervisor` and `Boot` (one `Client` per enabled row), `Client` with its `Wire` (the outbound request, the headers, the core's decoder and validator) and two transports (`Transport.Stdio`, a child on a Port; `Transport.HTTP`, one POST per request), `Bridge` (the one tool module every MCP tool runs through) and `Client.Auth` (062's seam, a static token at 060)) | Tools, **Effects**, **Permissions**, Memory (as built at 059: a top-level boundary, like `Trinity.Smoke`, with `deps: [Trinity, BeamMCP.JSON]`; the boundary compiler checks every call into the `beam_mcp` application and this boundary alone lists its modules; at 060 the deps are `[Trinity, BeamMCP.JSON, BeamMCP.Schema]`, Trinity's tools, permissions and receipts reached through `Trinity`'s exports, and `Trinity.Application` and `TrinityWeb` list `Trinity.MCP`) |
+| `Trinity.MCP` | Client manager, tool bridge, server (as built at 059: the boundary alone, holding the core's version, its JSON depth and its telemetry event names; at 060: `Servers` and `ServerConfig` (the rows), `Supervisor` and `Boot` (one `Client` per enabled row), `Client` with its `Wire` (the outbound request, the headers, the core's decoder and validator) and two transports (`Transport.Stdio`, a child on a Port; `Transport.HTTP`, one POST per request), `Bridge` (the one tool module every MCP tool runs through) and `Client.Auth` (062's seam, a static token at 060); at 061: `Server` (the module above the core, `@behaviour BeamMCP.Server`, handed to both transports through `:server`; `tools/call` answered through the membrane, everything else the core's), `Server.Catalog` (the exported tools, sorted), `Server.Exports` (the configured names, `:catalog` refused), `Server.Session` (the `origin: "mcp"` session with its own persona), `Server.Envelope` and `Server.Replay` (the sealed `requestState` and the nonce table), `Server.Auth.Local` (the static bearer, 062's seam on the server side), `Server.Plug` (the `POST /mcp` endpoint, mounted in `TrinityWeb.Endpoint` ahead of the parsers) and `Server.Stdio` with `mix trinity.mcp.stdio`) | Tools, **Effects**, **Permissions**, Memory (as built at 059: a top-level boundary, like `Trinity.Smoke`, with `deps: [Trinity, BeamMCP.JSON]`; the boundary compiler checks every call into the `beam_mcp` application and this boundary alone lists its modules; at 060 the deps are `[Trinity, BeamMCP.JSON, BeamMCP.Schema]`, Trinity's tools, permissions and receipts reached through `Trinity`'s exports, and `Trinity.Application` and `TrinityWeb` list `Trinity.MCP`; at 061 the core's `Server`, `Catalog`, `ToolSpec` and both transports are listed too, and `Trinity` exports `Tools.Registry` and `Effects.Runner` to it) |
 | `Trinity.Gateways` | Adapter behaviour, router, allowlists, pairing | Sessions, **Permissions**, PubSub |
 | `Trinity.Subagents` | Delegation, result collection | Sessions, Tools |
 | `Trinity.Sandbox` | Luerl runners, resource limits | none |

docs/05-data-model.md

@@ -246,6 +246,13 @@ One row per server the client connects to; the row's `name` is the namespace seg
 | tool_overrides | map | tool name to `{"effect": …}`; `catalog` is refused by the changeset and, on a row that carries it anyway, at load with a decision receipt on the chain scope `mcp:<name>`. No override lowers a tool's tier: it is `:ask` for every namespaced name, and a rule on the permissions page is what allows one |
 | last_error | text, nullable | |
 
+### The MCP server's files (Slice 061, not rows)
+`<data dir>/mcp-server-token` (the bearer clients present, generated once, mode 0600, overridden by
+`TRINITY_MCP_SERVER_TOKEN`) and `<keys dir>/mcp-state.key` (32 bytes, the AES-256-GCM key sealing the
+`requestState` of a held call; shared by every instance of the data directory). The MCP session is a
+`sessions` row with `origin: "mcp"` and its own persona ("MCP server", no settings); its approvals and
+receipts are ordinary rows under it.
+
 ### task_runs (Slice 050)
 `task_id`, `scheduled_at`, `session_id`, `status`, `summary`, `error`. Unique on `(task_id, scheduled_at)` so a
 run is idempotent. Oban holds the job; this holds the outcome.

docs/07-security-model.md

@@ -166,6 +166,42 @@ root loads as any other and is not scanned (a follow-up in the slice's NOTES).
   argument validation are the core's public functions (`BeamMCP.JSON.decode/1`, `BeamMCP.Schema.validate/2`),
   and a census test holds the population to that (060 AC7).
 
+## MCP server (Slice 061, as built)
+
+- **A stateless Plug above beam_mcp's core**, handed to the transport through its `:server` option;
+  the core answers every method but `tools/call`, which Trinity answers through the same gate and
+  membrane as the assistant's own calls. Will-not-implement entry 12 stands on the core: the approval
+  loop lives above it.
+- **Every call is attributed** to one session with `origin: "mcp"` and a persona of its own (no
+  permission settings: an MCP client inherits none of the default persona's allowances), and every
+  decision and query receipt carries `"origin" => "mcp"`. A `traceparent` in the request's `_meta`
+  rides into the receipts' meta.
+- **Exports are a closed list** the operator configures: core entries with effect `:none` or
+  `:artifact`; `:catalog` is refused at boot and never listed; the list is sorted, so `tools/list` is
+  deterministic.
+- **A bearer before the body.** `Trinity.MCP.Server.Auth.Local`: the token from the environment or the
+  generated file, compared in constant time in the transport's `:authorize` hook; a refusal decodes
+  nothing. Loopback is the default bind; a wider bind is the operator's setting and belongs behind a
+  proxy that authenticates the web pages too (062 brings the OAuth resource server).
+- **Approvals over the wire are the owner's, never the client's.** A held call answers `input_required`
+  with a `requestState` sealed by `Trinity.MCP.Server.Envelope`: AES-256-GCM under
+  `<keys dir>/mcp-state.key`, binding the approval id, the session, the call id, the tool, a digest of
+  the arguments, a nonce and an expiry (15 minutes by default). The client's `inputResponses` decide
+  nothing: the decision is the row on the permissions page. A retry opens the envelope and is refused
+  when expired, tampered, replayed or bound to another call, with a reason that names only which; a
+  retry before the decision is held again on the same approval under a fresh state and never re-enters
+  the gate; a retry after it runs under the envelope's call id, so the decision consumed is the one
+  made and a second run is the membrane's duplicate effect.
+- **Replay defence is at-most-once per partition plus idempotent effects**, stated as such:
+  `Trinity.MCP.Server.Replay` holds every nonce this instance has seen until its expiry window passes;
+  another instance has its own table, and across instances the gate's consumed "once" and the
+  membrane's idempotency key are the backstop (a replayed state there asks the owner again rather than
+  running twice). Tests hold the four reds: a replay inside the window, a replay across partitions, an
+  expired envelope, one tampered byte.
+- **stdio has no bearer**, as the core's page says: whoever writes to the process's standard input
+  already has the host's privileges. Its standard output is the wire and the VM's log is moved to
+  standard error.
+
 ## Secrets
 
 - Env vars in dev; OS keychain via `Trinity.Secrets` from Slice 100 (Tauri stronghold/store or a keychain NIF).