@brightbeamai/chap-coordinator-mcp 0.3.3 → 0.3.5

package/README.md

@@ -9,33 +9,54 @@ Spec target: **MCP 2026-07-28**, serving MCP 2025-11-25 clients as well · CHAP
 
 ## Run it as a server
 
-The package ships a stdio server, so an MCP client can use CHAP without any
-code. Point the client at it:
+The package ships a stdio server, `chap-mcp-server`, so an MCP client can use
+CHAP without any code. It makes every call as one participant, by default the
+agent `agent:assistant`, as a create-chap-app mcp-gate project names its
+agent, and offers the tools an agent's own work needs.
+A person decides in a desk, never through the assistant, so the server
+refuses to act as a `human:` participant and refuses a call that names
+anyone else.
+
+The usual setup has a CHAP server with a desk, such as a project made with
+`npx create-chap-app my-gate --template mcp-gate`, and points the stdio server
+at that server's JSON-RPC endpoint. The assistant's work then waits for the
+person in the desk:
 
 ```json
 {
   "mcpServers": {
     "chap": {
       "command": "npx",
-      "args": ["-y", "@brightbeamai/chap-coordinator-mcp"],
-      "env": { "CHAP_DB_PATH": "~/chap.db" }
+      "args": ["-y", "@brightbeamai/chap-coordinator-mcp",
+               "--url", "http://127.0.0.1:8792/chap", "--as", "agent:assistant"]
     }
   }
 }
 ```
 
-All 39 methods arrive as tools named `chap.<method>`. Two environment
-variables configure it:
+| Option | Environment | Effect |
+|--------|-------------|--------|
+| `--as <uri>` | `CHAP_PARTICIPANT` | The participant every call is made as. Default `agent:assistant`. `from` is filled in, a call naming anyone else is refused, and a `human:` URI is refused at start. |
+| `--tools agent\|all` | | `agent`, the default, offers `AGENT_MCP_TOOLS` (below). `all` offers every method, still as the one participant. |
+| `--url <endpoint>` | | Forward every call to a running CHAP server's JSON-RPC endpoint, such as a desk server's `http://127.0.0.1:8792/chap`. That server keeps the workspaces, its store and its profiles. A call waits 30 seconds for its answer. |
+| `--db <path>` | `CHAP_DB_PATH` | Keep the workspaces in this SQLite file. A leading `~` is the home directory. |
+| `--profiles <list>` | `CHAP_PROFILES` | Comma-separated profiles for new workspaces. Defaults to Core plus review, whisper, deliberation, handoff, control, routing, modes and audit-scitt, so the audit chain is on from the first entry. |
+| `--help` | | Print the options and exit. |
+
+An option takes its value as `--as agent:x` or `--as=agent:x`, and wins over
+its environment variable; an empty variable counts as unset.
 
-| Variable | Effect |
-|----------|--------|
-| `CHAP_DB_PATH` | Path to a SQLite file. Without it the coordinator runs in memory and every workspace is lost when the client restarts. |
-| `CHAP_PROFILES` | Comma-separated profiles for new workspaces. Defaults to Core plus review, whisper, deliberation, handoff, control, routing, modes and audit-scitt, so the audit chain is on from the first entry. |
+Without `--url` the server runs its own coordinator. With neither `--url` nor
+`--db` it keeps everything in memory, says so on stderr, and every workspace
+is lost when the client restarts. The agent tools create no workspace and
+join no one, so a coordinator of its own suits a store that already holds the
+workspace, or `--tools all`, where the assistant creates a workspace and
+joins it as itself.
 
 Persistence needs `better-sqlite3`, an optional native dependency of the
-coordinator. If `CHAP_DB_PATH` is set and it cannot be loaded the server says
-so and exits rather than starting in memory and discarding the decisions it
-was asked to keep.
+coordinator. If `--db` or `CHAP_DB_PATH` is set and it cannot be loaded the
+server says so and exits, so it never starts in memory and discards the
+decisions it was asked to keep.
 
 The server is also listed in the [MCP registry](https://registry.modelcontextprotocol.io)
 as `io.github.BrightbeamAI/chap`.
@@ -46,21 +67,25 @@ as `io.github.BrightbeamAI/chap`.
 npm install @brightbeamai/chap-coordinator-mcp
 ```
 
-Node 20+ required. Runtime dependencies: `@brightbeamai/chap-coordinator`,
+Node 22+ required. Runtime dependencies: `@brightbeamai/chap-coordinator`,
 `@modelcontextprotocol/sdk` and `zod`. The binary is `chap-mcp-server`.
 
 ## Quick start
 
 ```typescript
 import { Coordinator } from "@brightbeamai/chap-coordinator";
-import { makeChapMcpServer } from "@brightbeamai/chap-coordinator-mcp";
+import { AGENT_MCP_TOOLS, makeChapMcpServer } from "@brightbeamai/chap-coordinator-mcp";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 const coord = new Coordinator({
   defaultProfiles: ["core/1.0", "review/1.0", "audit-scitt/1.0"],
 });
 
-const server = makeChapMcpServer(coord, { name: "chap", version: "0.3.3" });
+// The assistant's own connection: every call as the agent, with its tools.
+const server = makeChapMcpServer(coord, {
+  participant: "agent:assistant",
+  toolFilter: (name) => AGENT_MCP_TOOLS.has(name),
+});
 await server.connect(new StdioServerTransport());
 ```
 
@@ -68,14 +93,130 @@ The returned `Server` is the official MCP SDK's `Server` class with
 `tools/list` and `tools/call` handlers pre-registered. Attach any MCP
 transport (stdio, Streamable HTTP, etc.).
 
+`makeChapMcpServer(coord, options)` takes:
+
+| Option | Effect |
+|--------|--------|
+| `participant` | Make every call as this participant: `from` is filled in, and a call that names another `from` is refused. The tools list `from` as optional, with this URI in its description. A `human:` URI is refused, as the commands refuse it. |
+| `toolFilter` | `(toolName) => boolean`. A tool the filter excludes is left out of the list and refused when called by name. |
+| `name`, `version` | What the server reports to its client. |
+| `envelopeIdFactory` | The id of each envelope a tool call sends. |
+
+Without `participant` or `toolFilter`,
+`makeChapMcpServer(coord, { name: "chap", version: "0.3.5" })` serves every
+tool and each call names its own `from`. That suits a connection that stands
+for no one member, such as a service of your own that authenticates its
+callers and checks the `from` they send.
+
+`coord` is a `Coordinator`, or any object with the same
+`dispatch(envelope)`, returning the response or a promise of it.
+
+`AGENT_MCP_TOOLS` is the agent's set: `chap.task.create`, `chap.task.update`,
+`chap.task.complete`, `chap.whisper.ask`, `chap.decide.approve`,
+`chap.decide.reject`, `chap.decide.override`, `chap.review.acknowledge`,
+`chap.workspace.describe`, `chap.audit.read` and `chap.audit.verify_chain`.
+The decision tools and `chap.review.acknowledge` stay for work the agent is
+asked to review; on its own work the coordinator refuses them with `-32011`
+and records the attempt. It leaves out the tools that choose who reviews the
+agent's work or pass its review on: `chap.review.request`, whose `to` can
+name the agent itself, `chap.escalate.raise`, which passes the open review
+on to a successor task, and every workspace, membership and control method.
+`chap.task.update` stays, so the agent can take a task under review back to
+`in_progress`, which withdraws its draft; its next completion opens the
+review again, so a task that holds a review completes only through a
+decision. A task with no review open completes when the agent completes it,
+so set `review_required` on any task the agent must not finish alone.
+
 A runnable reference server is at
 [`reference/mcp-server-ts/`](../../reference/mcp-server-ts/).
 
+## Serve it over HTTP
+
+`chapMcpHttpHandler` answers MCP on an HTTP endpoint such as `/mcp`, for a
+Node `http` request and response, in both protocol eras:
+
+```typescript
+function chapMcpHttpHandler(
+  coord: ChapDispatcher,
+  options?: ChapMcpHttpOptions,
+): (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void>;
+
+interface ChapMcpHttpOptions extends ChapMcpOptions {
+  maxBodyBytes?: number;      // default 1,114,112: 1 MiB, and 64 KiB of MCP around it
+  allowedHosts?: string[];    // Host values served besides the loopback names, such as "mcp.internal:8792"
+  allowedOrigins?: string[];  // origins a browser page may call from, such as "http://localhost:6274"
+  timeoutMs?: number;         // default 45,000
+}
+```
+
+`options` are those of `makeChapMcpServer`, so `participant` and
+`toolFilter` hold over HTTP as on stdio. Pass `parsedBody` when your server
+has read and parsed the body already; otherwise the handler reads it, up to
+`maxBodyBytes`.
+
+```typescript
+import { createServer } from "node:http";
+import { AGENT_MCP_TOOLS, chapMcpHttpHandler } from "@brightbeamai/chap-coordinator-mcp";
+
+const mcp = chapMcpHttpHandler(coord, {
+  participant: "agent:assistant",
+  toolFilter: (name) => AGENT_MCP_TOOLS.has(name),
+});
+createServer((req, res) => {
+  if (new URL(req.url ?? "/", "http://localhost").pathname === "/mcp") return mcp(req, res);
+  res.writeHead(404).end();
+}).listen(8792, "127.0.0.1");
+```
+
+The handler answers under the server's own names only, as the MCP
+specification requires against DNS rebinding: a `Host` other than
+127.0.0.1, localhost or [::1] on the port the request came in on is refused
+with 421, and a browser's request from another origin with 403. Name the
+host a proxy passes in `allowedHosts`, and the origin of a page that calls
+the server, such as the MCP Inspector's, in `allowedOrigins`; such a page
+also needs the CORS headers, which the server the handler is mounted in
+sends. Anything but POST is refused with 405, in both eras.
+
+A request with no `MCP-Protocol-Version` header, or a handshake-era version
+(2025-11-25 and earlier), goes to the SDK's Streamable HTTP transport, with
+a server and a transport for each request and no session. A batch is
+refused with 400, as every revision since 2025-06-18 refuses one, and so is
+a body whose envelope declares a protocol version the header does not name
+(`-32020`). Any other version takes the 2026-07-28 binding: one POST
+carrying one JSON-RPC request, answered with one JSON object. Its headers
+are checked against its body, and an error carries that binding's status:
+400 for a malformed request, a mismatched header (`-32020`) or an
+unsupported version (`-32022`), 404 for a method it does not serve. The
+SDK's transport alone refuses every 2026-07-28 request with 400.
+
+A request with no answer within `timeoutMs` is answered with an internal
+error, `-32603`, and one whose client has gone stops waiting at once.
+
+## What an unsigned local server trusts
+
+MCP calls carry no signature. `participant` keeps a connection to one name,
+and that is all it does: the stdio server trusts the process that started it,
+so whatever the client sends is made as the participant. The log records
+that the call came through this connection; it does not show that the
+participant signed it. Anything that can start the command, or reach a
+server's MCP endpoint, acts as that participant.
+
+With `--url`, the server at the other end applies its own rules to each call.
+One that requires a signature on every call refuses these with `-32070`; one
+that requires signatures from people only accepts the agent's unsigned calls.
+The pin covers this connection only. A CHAP server without signatures
+accepts a call in any member's name from any local process, so the record of
+a person's decision holds only where the server requires the desk's
+signature on it.
+
 ## What gets exposed
 
-All 39 CHAP methods become MCP tools named `chap.<method>`. Each
+Every CHAP method becomes an MCP tool named `chap.<method>`. Each
 tool's `inputSchema` is the JSON Schema for the corresponding method's
-params. Tool descriptions are tuned for LLM consumption.
+params. Tool descriptions are tuned for LLM consumption. A call naming no
+CHAP tool is a protocol error, `-32602` "Unknown tool: <name>", as the MCP
+tools specification has it; a CHAP tool the server leaves out is refused
+as a tool result, as the coordinator's refusals are.
 
 The `chap.` prefix avoids collisions with other MCP servers a client
 might have loaded simultaneously.
@@ -103,7 +244,9 @@ npm test
 
 The integration tests use the SDK's `InMemoryTransport.createLinkedPair()`
 to drive a wrapped Coordinator end-to-end, exercising every major
-profile.
+profile. `cli.test.ts` starts `chap-mcp-server` the way an MCP client does,
+with and without `--url`, and `http.test.ts` serves both protocol eras over
+HTTP.
 
 ## See also