toolroll 0.9.104 → 0.9.105

package/dist/mcp-connect.js

@@ -1,18 +1,3 @@
-/**
- * One-click connections: services whose MCP servers let an app register
- * itself (OAuth dynamic client registration, with PKCE), so connecting one is
- * a sign-in and nothing else: no developer app to create, no key to paste.
- *
- * Connect finds the server's sign-in (its protected-resource metadata, or the
- * authorization server at its origin), registers Toolroll as a client
- * with this console's callback, and sends the person to the service to sign
- * in. The callback trades the code for tokens, which live in the tool's own
- * secrets (the OS keychain, or its file where there is none; never the
- * database, never a log), and the tool joins the project like any other:
- * tested, listed, and given to subagents under rules. The worker refreshes
- * tokens before they expire, and each run gets an access token of its own
- * (oauth-run-token.ts).
- */
 import { createHash, randomBytes } from "node:crypto";
 import { basename } from "node:path";
 import { LOCAL_APPS, addToolTo, catalogTool, localAppOf, projectToolsOf, readToolSecrets, renewingSignIn, setToolSecrets, testToolOf } from "./project-tools.js";
@@ -20,17 +5,6 @@ import { envValue } from "./names.js";
 import { readAuthorizationServer, readProtectedResource, readRegistration, readTokenResponse } from "./contracts/integration-metadata.js";
 import { ACCESS, CLIENT, CLIENT_SECRET, EXPIRES, GRANTED, REFRESH, RESOURCE, REVOKE_URL, TOKEN_URL, readScope, scopeList } from "./oauth-run-token.js";
 export { readScope, scopeList };
-/**
- * Services that connect this way: their servers speak streamable HTTP and
- * advertise registering clients on the spot. Advertising isn't accepting:
- * Figma's server advertises it, but its registration answers 403 to any app
- * Figma hasn't approved, so Figma connects through its desktop app instead
- * (LOCAL_APPS). A service is listed only when its registration accepts
- * Toolroll; mcp-connect.test.ts replays each one's answer (no live calls).
- *
- * Signed in end to end, live: Mobbin. The rest register in replayed checks
- * only, until someone signs in to each for real.
- */
 export const ONE_CLICK = [
     { id: "stripe", label: "Stripe", url: "https://mcp.stripe.com/", about: "Payments, customers, refunds and invoices." },
     { id: "notion", label: "Notion", url: "https://mcp.notion.com/mcp", about: "Pages and databases: search, read and write." },
@@ -53,7 +27,6 @@ export const ONE_CLICK = [
         reads: ["team", "project", "deployment", "build", "runtime", "log", "logs", "vercel", "documentation"] },
     { id: "cloudflare", label: "Cloudflare", url: "https://mcp.cloudflare.com/mcp", about: "Workers, DNS and your Cloudflare account.",
         reads: ["account", "worker", "workers", "observability", "analytics", "log", "logs", "page", "pages", "project", "deployment"] },
-    // Mobbin's sign-in is its Supabase auth server, on another origin: its protected-resource metadata names it.
     { id: "mobbin", label: "Mobbin", url: "https://api.mobbin.com/mcp", about: "Real app screens and flows to learn from.",
         reads: ["screen", "flow", "app", "site", "element", "pattern", "ui", "ios", "android", "web"] },
     { id: "posthog", label: "PostHog", url: "https://mcp.posthog.com/mcp", about: "Product analytics, funnels and events.", serverScopes: true, readActions: ["exec"],
@@ -68,12 +41,6 @@ const loopback = (value) => { try {
 catch {
     return false;
 } };
-/**
- * The list, with one service standing in on this computer when the person
- * running Toolroll says so ("stripe|Stripe|http://127.0.0.1:5123/mcp"
- * in TOOLROLL_TEST_CONNECT): how the end-to-end check signs in for
- * real without a real account. Only a loopback address is taken.
- */
 export function oneClickServices(environment = process.env) {
     const [id = "", label = "", url = ""] = (envValue(environment, "TEST_CONNECT") ?? "").split("|");
     if (!/^[a-z0-9-]{1,40}$/.test(id) || label === "" || !loopback(url))
@@ -83,18 +50,11 @@ export function oneClickServices(environment = process.env) {
     return ONE_CLICK.some(one => one.id === id) ? ONE_CLICK.map(one => one.id === id ? standIn : one) : [...ONE_CLICK, standIn];
 }
 export const oneClickOf = (id) => oneClickServices().find(one => one.id === id) ?? null;
-/** What to use when a service won't let Toolroll sign in by itself. */
 const INSTEAD = { figma: "Connect Figma (desktop app) instead." };
-/** An app on this computer that Connect adds without a sign-in (LOCAL_APPS): its tool, name and one line of how. */
 export const localConnectOf = (id) => {
     const app = LOCAL_APPS.find(one => one.tool === id), tool = catalogTool(id);
     return app === undefined || tool === null ? null : { id, label: tool.label, about: app.connect };
 };
-/**
- * Where each service stands in a project: connected, open to connect, or its name taken by a tool set up another way.
- * `local` connects with no sign-in. `research` says, for a connected service research can't use because of the access
- * it was granted, why (shown on its Tools entry beside Reconnect read-only).
- */
 export function connectionsOf(store, repo, home) {
     const tools = projectToolsOf(store, repo);
     const signIn = oneClickServices().map(service => {
@@ -112,15 +72,8 @@ export function connectionsOf(store, repo, home) {
     });
     return [...signIn, ...local];
 }
-/** The verbs that only read. An action named by anything else is withheld from research. */
 const READING = new Set(["list", "get", "search", "find", "read", "query", "describe", "fetch", "view", "export-image"]);
-/** Words that only qualify what is read ("insights-get-all", "get_by_id"). */
 const QUALIFIERS = new Set(["all", "by", "id", "ids"]);
-/**
- * Whether an action only reads: its name has a reading verb, and every other
- * word is a reading verb, a qualifier or something this service lets
- * research read. An allow-list: a word nobody listed withholds the action.
- */
 export function readsOnly(action, subjects) {
     if (!/^[A-Za-z0-9_.-]{1,64}$/.test(action))
         return false;
@@ -129,12 +82,8 @@ export function readsOnly(action, subjects) {
     const subject = (word) => subjects.includes(word) || subjects.includes(word.replace(/s$/, ""));
     return words.some(word => READING.has(word)) && words.every(word => READING.has(word) || QUALIFIERS.has(word) || subject(word));
 }
-/** Whether a saved grant only reads: it names at least one scope and every one is a read or identity scope. Unknown (null) never is. */
-// A scope a server adds to every token without being asked, that grants no access to data. PostHog adds
-// `introspection` (its ALWAYS_ALLOWED_SCOPES): it lets the token be checked, and has no write form. Never requested.
 const GRANTED_ANYWAY = new Set(["introspection"]);
 export const readOnlyGrant = (grant) => grant !== null && grant.some(readScope) && grant.every(scope => readScope(scope) || GRANTED_ANYWAY.has(scope));
-/** The scope a connected service's sign-in was granted, as saved beside its token; null when it was never proved. */
 export function grantOf(repo, tool, home) {
     try {
         return scopeList(readToolSecrets(repo, tool, home)[GRANTED]);
@@ -143,11 +92,6 @@ export function grantOf(repo, tool, home) {
         return null;
     }
 }
-/**
- * What research may use of one connected service: its exact `readActions` while the saved grant only reads, and
- * otherwise (as for every service) the actions whose names only read. A service with `readActions` that gives
- * research nothing says why, plainly, for the run and its Tools entry.
- */
 function researchAccess(service, tool, grant) {
     const listed = tool.lastTest?.ok ? tool.lastTest.tools : [];
     const exact = service.readActions !== undefined && readOnlyGrant(grant) ? service.readActions : [];
@@ -160,7 +104,6 @@ function researchAccess(service, tool, grant) {
 }
 export function researchToolsOf(tools, launched = null, granted = () => null) {
     const research = { services: [], allowed: [], reads: {}, local: [] };
-    // Signed-in services, then apps on this computer (each exactly as listed: its own address, no key).
     const readable = [
         ...oneClickServices().map(service => ({ id: service.id, label: service.label, reads: service.reads, readActions: service.readActions, is: (spec) => spec.url === service.url && spec.bearer === ACCESS })),
         ...LOCAL_APPS.map(app => ({ id: app.tool, label: catalogTool(app.tool)?.label ?? app.tool, reads: app.reads, readActions: undefined, is: (spec) => localAppOf(spec) === app })),
@@ -182,11 +125,9 @@ export function researchToolsOf(tools, launched = null, granted = () => null) {
     }
     return research;
 }
-/** Where a service sends the person back after they sign in. */
 export const CONNECT_CALLBACK = "/settings/tools/connected";
 const VISIT_MS = 15 * 60_000, RENEW_RETRY_MS = 5 * 60_000;
 const renewTried = new Map();
-/** The most scope text a sign-in address carries (addresses stay well under 8 KB). */
 const SCOPE_PARAM_LIMIT = 6_000;
 const json = async (fetcher, url) => {
     try {
@@ -206,10 +147,8 @@ const secure = (value) => { try {
 catch {
     return false;
 } };
-/** A server's sign-in: the resource metadata its 401 names (or the well-known one), then its authorization server's metadata. */
 export async function discoverSignIn(mcpUrl, fetcher = fetch) {
     const mcp = new URL(mcpUrl);
-    // Sign-in addresses are https, except a stand-in on this computer whose own sign-in is here too (OAuth's loopback exception).
     const https = (value) => typeof value === "string" && (secure(value) || (loopback(mcpUrl) && loopback(value)));
     let pointer = null;
     try {
@@ -240,9 +179,6 @@ export async function discoverSignIn(mcpUrl, fetcher = fetch) {
         return null;
     if (!(meta.code_challenge_methods_supported ?? ["S256"]).includes("S256"))
         return null;
-    // Ask for every scope the server lists for this resource: a token missing one the server itself requires is
-    // refused after a successful sign-in (PostHog lists 155 and needs user:read, the 140th). Only well-formed scope
-    // tokens, and at most what fits a sign-in address.
     const listed = resource.scopes_supported ?? [];
     const scopes = [];
     for (const one of listed) {
@@ -250,15 +186,9 @@ export async function discoverSignIn(mcpUrl, fetcher = fetch) {
             break;
         scopes.push(one);
     }
-    // A token is for the resource the server names (Stripe's has no trailing slash), when it names one.
     const named = resource.resource;
     return { authorize, token, register, scopes, resource: https(named) ? named : null, revoke: https(meta.revocation_endpoint) ? meta.revocation_endpoint : null };
 }
-/**
- * Start connecting a service: find its sign-in, register this console as a
- * client, and hand back the address to send the person to (and the visit the
- * callback finishes). The person's password was checked before this.
- */
 export async function startConnect(input, fetcher = fetch, now = Date.now()) {
     const service = oneClickOf(input.service);
     if (service === null)
@@ -271,11 +201,9 @@ export async function startConnect(input, fetcher = fetch, now = Date.now()) {
     try {
         const registered = await fetcher(server.register, { method: "POST", headers: { "content-type": "application/json", accept: "application/json" }, signal: AbortSignal.timeout(10_000),
             body: JSON.stringify({ client_name: "Toolroll", redirect_uris: [redirect], grant_types: ["authorization_code", "refresh_token"], response_types: ["code"], token_endpoint_auth_method: "none" }) });
-        // Figma's answer (Oct 2026): it registers only apps it has approved. Said before reading a body that may not be JSON.
         if (registered.status === 401 || registered.status === 403)
             return { ok: false, said: `${service.label} doesn't let other apps sign in this way yet.${INSTEAD[service.id] === undefined ? "" : ` ${INSTEAD[service.id]}`}` };
         const body = readRegistration(await registered.json());
-        // A `null` answer that says it registered is no answer, as it always read.
         if (registered.ok && body === null)
             return { ok: false, said: `${service.label} couldn't be reached.` };
         if (!registered.ok || body?.client_id === undefined)
@@ -297,8 +225,6 @@ export async function startConnect(input, fetcher = fetch, now = Date.now()) {
     go.searchParams.set("code_challenge_method", "S256");
     go.searchParams.set("state", state);
     go.searchParams.set("resource", resource);
-    // Reconnect read-only (a service that names its research actions): only the read and identity scopes the server
-    // lists. Otherwise every listed scope, or none where the server applies its own preset.
     const scopes = input.readOnly === true && service.readActions !== undefined ? server.scopes.filter(readScope)
         : service.serverScopes === true ? [] : server.scopes;
     if (input.readOnly === true && service.readActions !== undefined && scopes.length === 0)
@@ -308,7 +234,6 @@ export async function startConnect(input, fetcher = fetch, now = Date.now()) {
         go.searchParams.set("scope", scope);
     return { ok: true, go: go.toString(), state, visit: { service: service.id, repo: input.repo, by: input.by, kit: input.kit ?? null, template: input.template ?? null, verifier, clientId, clientSecret, token: server.token, resource, redirect, expires: now + VISIT_MS, scope, revoke: server.revoke } };
 }
-/** The spec a connected service joins the project with: its MCP address, signed in with the token its sign-in gave. */
 export function connectedSpec(serviceId) {
     const service = oneClickOf(serviceId);
     if (service === null)
@@ -321,11 +246,6 @@ const tokensFrom = (body, now) => ({
     refresh: body.refresh_token ?? null,
     expires: body.expires_in === undefined ? null : new Date(now + body.expires_in * 1000).toISOString(),
 });
-/**
- * Finish connecting: trade the code for tokens, add the tool to the project
- * (or refresh its sign-in, when it's there already), keep the tokens in its
- * secrets, and test it.
- */
 export async function finishConnect(store, visit, code, now, options = {}) {
     const service = oneClickOf(visit.service);
     const fetcher = options.fetcher ?? fetch, home = options.home;
@@ -338,7 +258,6 @@ export async function finishConnect(store, visit, code, now, options = {}) {
         const answer = await fetcher(visit.token, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
             body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: visit.redirect, client_id: visit.clientId, code_verifier: visit.verifier, resource: visit.resource, ...(visit.clientSecret === null ? {} : { client_secret: visit.clientSecret }) }) });
         const read = readTokenResponse(await answer.json());
-        // An answer of `null` reads as none, like one that isn't JSON.
         if (read === null)
             return { ok: false, said: `${service.label} couldn't be reached to finish the sign-in.` };
         body = read;
@@ -358,11 +277,9 @@ export async function finishConnect(store, visit, code, now, options = {}) {
         if (!added.ok)
             return { ok: false, said: added.message };
     }
-    // The grant: what the answer says, or what was asked for when it says nothing; never one from an earlier sign-in.
     const granted = body.scopeSaid ? scopeList(body.scope) : scopeList(visit.scope ?? null);
     setToolSecrets(visit.repo, spec.name, { [ACCESS]: tokens.access, [CLIENT]: visit.clientId, [TOKEN_URL]: visit.token, [RESOURCE]: visit.resource, [GRANTED]: granted?.join(" ") ?? "", [REVOKE_URL]: visit.revoke ?? "", [REFRESH]: "",
         ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }), ...(visit.clientSecret === null ? {} : { [CLIENT_SECRET]: visit.clientSecret }) }, home);
-    // The success line names the project it went to: the page and chat may be looking at another.
     const to = basename(visit.repo);
     if (options.test === false)
         return { ok: true, said: `${service.label} is connected to ${to}.` };
@@ -370,7 +287,6 @@ export async function finishConnect(store, visit, code, now, options = {}) {
     return tested?.ok ? { ok: true, said: `${service.label} is connected to ${to}: ${tested.tools.length} action${tested.tools.length === 1 ? "" : "s"}. Let a subagent use it from its page.` }
         : { ok: true, said: `${service.label} is signed in for ${to}, but its test didn't pass yet: ${tested?.problem ?? "no answer"}.` };
 }
-/** Keep connected services signed in: any token expiring within ten minutes is refreshed (the worker's pass, and before a subagent's call). */
 export async function refreshConnections(store, repos, now, options = {}) {
     const fetcher = options.fetcher ?? fetch, home = options.home;
     const report = { refreshed: 0, problems: [] };
@@ -382,12 +298,10 @@ export async function refreshConnections(store, repos, now, options = {}) {
             const expires = values[EXPIRES] === undefined ? null : Date.parse(values[EXPIRES]);
             if (expires === null || Number.isNaN(expires) || expires - now.getTime() > 10 * 60_000 || values[REFRESH] === undefined || values[TOKEN_URL] === undefined || values[CLIENT] === undefined)
                 continue;
-            // One try every five minutes at most: a sign-in the service has revoked is said once in a while, not every pass.
             const key = `${repo}\0${tool.name}`;
             if (now.getTime() - (renewTried.get(key) ?? 0) < RENEW_RETRY_MS)
                 continue;
             renewTried.set(key, now.getTime());
-            // Renewed one at a time with a run's own sign-in, across Toolroll's processes: a rotated refresh token is never used twice.
             const problem = await renewingSignIn(repo, tool.name, home, async () => {
                 const latest = readToolSecrets(repo, tool.name, home);
                 if (!latest[REFRESH] || !latest[TOKEN_URL] || !latest[CLIENT])
@@ -401,8 +315,6 @@ export async function refreshConnections(store, repos, now, options = {}) {
                     const tokens = tokensFrom(body, now.getTime());
                     if (!answer.ok || tokens.access === null)
                         return `${tool.name}: its sign-in ran out; connect it again on the Tools page`;
-                    // A refresh carries the same grant or a narrower one, and says so when it changes; said badly, it is unknown.
-                    // Not saved (a locked keychain): the saved sign-in stays as it was, and this says so.
                     try {
                         setToolSecrets(repo, tool.name, { [ACCESS]: tokens.access, ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }),
                             ...(body.scopeSaid ? { [GRANTED]: scopeList(body.scope)?.join(" ") ?? "" } : {}) }, home);

package/dist/mcp-core.js

@@ -1,13 +1,3 @@
-/**
- * The MCP gateway's transport-free core (MCP gateway spec v6): protocol
- * constants and limits, message reading, the coordinator tool registry and
- * its per-call authorization. The stdio adapter (mcp.ts) and the HTTP adapter
- * (mcp-http.ts) each own their transport and lifecycle; neither re-implements
- * what a call means.
- *
- * Protocol errors are JSON-RPC errors; tool-level refusals are successful
- * `tools/call` results with `isError: true`.
- */
 import { answerMap } from "./code-map-read.js";
 import { dirname, join } from 'node:path';
 import { repositoryContextRead } from './repository-context.js';
@@ -20,17 +10,13 @@ import { ISO_STAMP_RULE, decisionOver, decisionsOver, labelRepos, queueOver, rec
 import { proposeAsCoordinator } from "./coordinator-proposals.js";
 export const MODERN = "2026-07-28";
 export const LEGACY = "2025-11-25";
-/** The modern revision namespaces its per-request metadata. */
 export const META_VERSION = "io.modelcontextprotocol/protocolVersion";
 export const META_SERVER = "io.modelcontextprotocol/serverInfo";
 export const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
-/** The revision's own error code for an unsupported protocol version. */
 export const UNSUPPORTED_VERSION = -32022;
 export const MAX_REQUEST = 256 * 1024;
 export const MAX_DEPTH = 32;
 export function depthOf(value) {
-    // The byte cap bounds the work list. Neither nesting nor array width
-    // becomes a JavaScript call stack or a spread argument list.
     const pending = [{ value, depth: 0 }];
     let maximum = 0;
     while (pending.length > 0) {
@@ -57,7 +43,6 @@ const CONTRACT_GUIDE = [
     "Approve, steer, answer, pick, mint, configure, merge: those verbs do not exist on this surface, by construction.",
     "Claim one assignment, then receive its changes with get_assignment_inbox and acknowledge each handled batch with acknowledge_assignment_delivery; inspect get_assignment when a current result or decision needs attention. list_assignment_updates is only the history of handoffs sent to people. claim_assignment records its lead; acknowledge_assignment records that lead's check of an exact ready receipt. Neither operation grants authority, accepts proof, answers decisions, approves work, publishes, or deploys.",
 ].join("\n");
-/** An assignment tool: the adapter reads its call with the same schema `toolroll assignment` does. */
 const assignmentHandler = (operation) => (ctx, args) => {
     const result = assignmentForCoordinator(ctx.store, ctx.token, operation, args, ctx.now, ctx.evidenceRoot);
     return result.ok ? { ok: true, body: result.body } : { ok: false, message: `${result.reason}: ${result.message}` };
@@ -66,7 +51,6 @@ const assignmentTool = (name) => {
     const spec = ASSIGNMENT_TOOLS.find(one => one.name === name);
     return { description: spec.description, handle: assignmentHandler(spec.operation) };
 };
-/** A propose_* tool: it writes one proposal row through the coordinator door. */
 const proposeTool = (kind, description) => ({
     description,
     handle: (ctx, args) => {
@@ -134,9 +118,6 @@ const HANDLERS = {
     list_repos: {
         description: "The repositories your credential may see and file into, with their operating-mode standing.",
         handle: ctx => {
-            // FAIL CLOSED when the project registry cannot be read (round-2
-            // finding 4): answering the full allowlist would claim enrollment
-            // nobody proved.
             if (ctx.enrolled === null) {
                 return { ok: false, message: "the project registry could not be read — the enrolled set is unknown, so nothing lists" };
             }
@@ -173,9 +154,6 @@ const HANDLERS = {
             const repo = args.repo;
             if (!ctx.who.repos.includes(repo))
                 return { ok: false, message: "not-found: that repository is not in your allowlist" };
-            // The installation-wide revision stays home (slice-2 review, finding
-            // 12): a coordinator cannot move queues, and the counter would tell it
-            // about repos it may not see.
             const { queueRevision: _revision, ...columns } = queueOver(ctx.store, repo, ctx.now);
             return { ok: true, body: { repo, ...columns } };
         },
@@ -204,8 +182,6 @@ const HANDLERS = {
     file_proposal: {
         description: "File a task proposal into one of your repositories. It stays quarantined until the operator signs its scope.",
         handle: (ctx, args) => {
-            // The token, not the pre-verified identity: filing re-authenticates
-            // INSIDE its own transaction (the session's `who` is a courtesy).
             const outcome = fileCoordinatorProposal(ctx.store, ctx.token, { repo: args.repo, title: args.title, ...(args.intent === undefined ? {} : { intent: args.intent }), ...(args.deliverable === undefined ? {} : { deliverable: args.deliverable }), idempotencyKey: args.idempotency_key }, ctx.now);
             if (!outcome.ok)
                 return { ok: false, message: outcome.message };
@@ -220,23 +196,16 @@ const HANDLERS = {
         },
     },
 };
-/** The gateway's tools in tools/list order, each inputSchema derived from its contract. */
 export const TOOLS = Object.keys(GATEWAY_TOOL_INPUTS).map((name) => {
     const handler = HANDLERS[name];
     return { name, description: handler.description, inputSchema: toModelSchema(GATEWAY_TOOL_INPUTS[name]), handle: (ctx, args) => handler.handle(ctx, args) };
 });
-/** The tools/list payload for a registry. No outputSchema: MCP output schemas describe structuredContent, and these
- * tools return text content only (round-2 finding 1). */
 export const toolsPayload = (tools) => ({
     tools: tools.map(tool => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })),
 });
-/** A modern result is schema-complete; a cacheable one (tools/list, discover) carries `ttlMs: 0` and the narrowest scope. */
 export function shapeResult(era, result, cacheable) {
     return era === "modern" ? { ...result, resultType: "complete", ...(cacheable ? { ttlMs: 0, cacheScope: "private" } : {}) } : result;
 }
-/** Read one message's text: size, JSON, no batching, depth, `jsonrpc`, and the id rules. A notification is the message
- * that carries NO id — the method name never decides (round-3 finding 3). MCP RequestId is a string or an INTEGER
- * (round-2 finding 2): floats, null, and object shapes refuse wherever an id appears. */
 export function readMessage(text) {
     if (Buffer.byteLength(text, "utf8") > MAX_REQUEST)
         return { ok: false, id: null, code: -32600, message: "request over 256 KiB" };
@@ -247,7 +216,6 @@ export function readMessage(text) {
     catch {
         return { ok: false, id: null, code: -32700, message: "parse error" };
     }
-    // Batching left MCP in 2025-06-18 — neither pinned era accepts it.
     if (Array.isArray(message))
         return { ok: false, id: null, code: -32600, message: "JSON-RPC batching is not part of MCP — send one request per line" };
     if (message === null || typeof message !== "object" || depthOf(message) > MAX_DEPTH)
@@ -272,24 +240,14 @@ export function readMessage(text) {
     const meta = (params["_meta"] ?? {});
     return { ok: true, hasId, id: (rawId ?? null), method, params, meta };
 }
-/** ClientCapabilities is an OBJECT shape (round-3 finding 5): an array is not a capabilities declaration. */
 export const capabilitiesShape = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** The `arguments` of a call: only an ABSENT value defaults to empty (round-3 finding 2), and the root is an object
- * BEFORE any schema applies (round-2 finding 2): 42 or false never passes an empty schema. */
 export function callArguments(params) {
     const raw = params["arguments"] === undefined ? {} : params["arguments"];
     return typeof raw !== "object" || raw === null || Array.isArray(raw) ? null : raw;
 }
-/** A handler's answer as a tools/call result: a refusal is `isError`, never a protocol error. */
 export function answerResult(answered) {
     return answered.ok ? { content: [{ type: "text", text: JSON.stringify(answered.body) }] } : { content: [{ type: "text", text: answered.message }], isError: true };
 }
-/**
- * One coordinator tools/call. ONE snapshot per call (review finding 3): the version check, the credential re-read, and
- * every data read share a transaction, so a concurrent migration cannot slip between them; filing's own BEGIN IMMEDIATE
- * reenters this one. tools/list visibility is presentation — authorization happens HERE, on every call, against the
- * live credential row.
- */
 export function callCoordinatorTool(call, params) {
     const { store, token, clock, ...rest } = call;
     return store.transact(() => {
@@ -305,13 +263,10 @@ export function callCoordinatorTool(call, params) {
         const rawArgs = callArguments(params);
         if (rawArgs === null)
             return { kind: "error", code: -32602, message: "arguments must be an object", fatal: false };
-        // The call is read by the schema tools/list advertised (review finding 2): unknown fields, bad types, bad enums,
-        // and bound violations are protocol errors (InvalidParams) naming each path, never tool refusals.
         const read = parseContract(GATEWAY_TOOL_INPUTS[tool.name], rawArgs);
         if (!read.ok)
             return { kind: "error", code: -32602, message: read.issues.map(one => one.line).join("; "), fatal: false };
         const answered = tool.handle({ store, token, who: session.who, now: clock(), ...rest }, read.value);
-        // Checked against its output schema before delivery; a disagreement is reported, never refused.
         if (answered.ok)
             reportToolOutput("gateway", tool.name, GATEWAY_TOOL_OUTPUTS[tool.name], answered.body);
         return { kind: "result", result: answerResult(answered) };

package/dist/mcp-http.js

@@ -6,19 +6,16 @@ import { authenticateCoordinator } from "./coordinator.js";
 import { LEGACY, MAX_REQUEST, META_CAPABILITIES, META_SERVER, META_VERSION, MODERN, TOOLS, UNSUPPORTED_VERSION, callCoordinatorTool, capabilitiesShape, readMessage, shapeResult, toolsPayload, } from "./mcp-core.js";
 import { callPersonTool, personTools } from "./mcp-person.js";
 import { limitWords, SOURCE_BUDGET_DEFAULTS, SourceAdmission } from "./request-budget.js";
-/** The most decisions a coordinator credential is remembered to have read (propose_answer needs one). */
 const READ_DECISIONS_KEPT = 200;
 export function createMcpHttp(options) {
     const { store } = options;
     const coordinatorBudget = new SourceAdmission({ perMinute: SOURCE_BUDGET_DEFAULTS.coordinator, ...(options.requestBudgetClock === undefined ? {} : { clock: options.requestBudgetClock }) });
-    /** Stdio remembers per connection which decisions a coordinator read; stateless HTTP remembers it per credential. */
     const readDecisions = new Map();
     const send = (response, status, body, headers = {}) => {
         response.writeHead(status, { "cache-control": "no-store", "x-content-type-options": "nosniff", ...(body === null ? {} : { "content-type": "application/json" }), ...headers });
         response.end(body === null ? undefined : JSON.stringify(body));
     };
     const refuse = (response, status, message, headers = {}) => send(response, status, { jsonrpc: "2.0", id: null, error: { code: -32000, message } }, headers);
-    /** Who signed this request, from the live rows — nothing is cached, so revocation and grant changes apply at once. */
     const callerOf = (request) => {
         const presented = /^Bearer (\S+)$/.exec(request.headers.authorization ?? "")?.[1];
         if (presented === undefined || presented.includes(":"))
@@ -26,7 +23,6 @@ export function createMcpHttp(options) {
         if (presented.startsWith("so_")) {
             if (!options.signedIn(request))
                 return null;
-            // The secret is checked here too (the one credential check), so this door never rests on how signedIn reads the request.
             const found = store.presentedCredential(presented);
             const kept = found?.kind === "person" ? store.apiTokenSecret(found.id) : null;
             if (kept === null)
@@ -36,7 +32,6 @@ export function createMcpHttp(options) {
             const account = store.accountOf(kept.row.account);
             if (account === null || account.revokedAt !== null)
                 return null;
-            // An MCP sign-in's token: only while its access is fresh, and only in the projects the person chose (mcp-oauth.ts).
             if (!oauthTokenAllowed(store, kept.row.id, RESOURCE_PATH, options.clock()))
                 return null;
             const granted = oauthProjects(store, kept.row.id);
@@ -53,9 +48,7 @@ export function createMcpHttp(options) {
         const auth = authenticateCoordinator(store, presented);
         return auth.ok ? { kind: "coordinator", token: presented, cid: auth.who.cid } : null;
     };
-    /** Loaded on first use: operate.ts imports serve.ts, which serves this gateway. */
     const runAs = async () => options.runAs ?? (await import("./operate.js")).runOperateAs;
-    /** The body, or null the moment it passes MAX_REQUEST: reading stops there and nothing more is buffered. */
     const readBody = (request) => new Promise((resolve, reject) => {
         const chunks = [];
         let size = 0;
@@ -72,7 +65,6 @@ export function createMcpHttp(options) {
         request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
         request.on("error", reject);
     });
-    /** 413, then the connection goes: the rest of an oversized body is never read. */
     const tooLarge = (request, response) => {
         response.once("finish", () => request.destroy());
         refuse(response, 413, "request over 256 KiB", { connection: "close" });
@@ -93,7 +85,6 @@ export function createMcpHttp(options) {
     return async (request, response) => {
         if (request.method !== "POST")
             return refuse(response, 405, "the MCP gateway takes POST only — one JSON-RPC message per request", { allow: "POST" });
-        // A browser page must never drive the gateway with whatever it can reach: agents send no Origin.
         if (request.headers.origin !== undefined)
             return refuse(response, 403, "browser requests are refused — connect an MCP client with your API token");
         const caller = callerOf(request);
@@ -101,8 +92,6 @@ export function createMcpHttp(options) {
             const metadata = options.resourceMetadata?.(request) ?? null;
             return refuse(response, 401, "sign in with your API token (Authorization: Bearer so_…) or a coordinator credential — passwords and cookies are not accepted here", { "www-authenticate": `Bearer realm="toolroll-mcp"${metadata === null ? "" : `, resource_metadata="${metadata}"`}` });
         }
-        // Count every authenticated request once, including notifications. Coordinator proposal limits still apply
-        // separately inside tool transactions; this admission also bounds their reads and malformed requests.
         {
             const admitted = caller.kind === "person" ? options.admit?.(caller.person) ?? { ok: true } : coordinatorBudget.admit(caller.cid);
             if (!admitted.ok && admitted.status === 503)
@@ -132,7 +121,6 @@ export function createMcpHttp(options) {
         const answer = (era, result, cacheable) => send(response, 200, { jsonrpc: "2.0", id, result: shapeResult(era, result, cacheable) });
         if (!store.schemaCurrent())
             return error(-32000, "the database schema moved underneath this server — try again after it restarts");
-        // Notifications (initialized, cancelled) need nothing from a stateless server: accepted, never answered.
         if (method.startsWith("notifications/"))
             return send(response, 202, null);
         const header = request.headers["mcp-protocol-version"];
@@ -142,7 +130,6 @@ export function createMcpHttp(options) {
         }
         const tools = () => caller.kind === "person" ? personTools(caller.person) : TOOLS;
         if (method === "initialize") {
-            // The handshake era negotiates only itself; nothing is kept, so no session id is issued.
             return answer("legacy", { protocolVersion: LEGACY, capabilities: { tools: {} }, serverInfo: { name: "toolroll", version: PACKAGE_VERSION } }, false);
         }
         const era = declared === MODERN ? "modern" : "legacy";