@zeroroot-ai/gibson-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeroRoot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @zeroroot-ai/gibson-mcp
+
+The Gibson MCP server. One tool surface for every coding agent host: Claude
+Code, opencode, Cursor, Codex CLI, Gemini CLI and Windsurf. The host is a thin
+adapter and holds no tools of its own.
+
+## Install
+
+Every host runs it through `npx`, so nothing has to be installed by hand.
+This is the canonical block. It is the same for every host that reads the
+`mcpServers` shape.
+
+```json
+{
+  "mcpServers": {
+    "gibson": {
+      "command": "npx",
+      "args": ["--yes", "--package", "@zeroroot-ai/gibson-mcp@latest", "gibson-mcp"]
+    }
+  }
+}
+```
+
+| Host | Where the block goes |
+|---|---|
+| Claude Code | `.mcp.json` in the project, or the `zerocool` plugin, which carries it |
+| opencode | the `zerocool` opencode plugin, which carries it |
+| Cursor | `.cursor/mcp.json` |
+| Codex CLI | `~/.codex/config.toml`, as a `[mcp_servers.gibson]` table with the same command and args |
+| Gemini CLI | `~/.gemini/settings.json`, under `mcpServers` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json`, under `mcpServers` |
+
+A host is an adapter and holds no tools of its own (ADR-0008). The per-host
+snippets and their smoke tests live in
+[`zerocool-plugins`](https://github.com/zeroroot-ai/zerocool-plugins).
+
+## The tool surface
+
+The surface is 1:1 with everything the SDK produces. One flat tier, no
+curated subset.
+
+| Where a tool comes from | Naming | How many |
+|---|---|---|
+| every RPC of every SDK service, generated from the proto descriptors | `<service>_<method>` in snake case, e.g. `harness_callback_service_world_view` | 188 |
+| every SDK helper | the helper's own name: `remember`, `recall`, `world_view`, `submit_finding`, `delegate` | 30 |
+| every checked-in platform tool and plugin, discovered at runtime | `gibson_<tool>`, `gibson_plugin_<plugin>` | whatever the tenant has |
+
+An SDK bump regenerates the first group. Discovery repeats every 60 seconds
+and emits `tools/list_changed`, so a tool a person enrols now is callable in
+the same session.
+
+A posture registers only the tools its credential can reach. With no
+platform the server still serves `submit_finding`, `componentize` and
+`validate_component`, plus `gibson_login` and `gibson_connect`.
+
+## Resources and prompts
+
+| URI | What it holds |
+|---|---|
+| `gibson://ambient` | one GraphRAG lookup per session: what the tenant already knows about this codebase |
+| `gibson://session` | the check-in source, the posture, and the mission, run and callback endpoint a session-end hook needs |
+
+A host with a hook surface injects the ambient block itself. A host without
+one calls the `gibson_ambient` prompt instead. Either way it is one lookup.
+
+## Transports
+
+| Flag | Where it runs | Why |
+|---|---|---|
+| `--transport stdio` (default) | a laptop | the host spawns the server and owns its lifetime |
+| `--transport http --listen 127.0.0.1:7788` | a sandbox | one server for the life of the sandbox, so the driver can swap the grant per turn |
+
+`--listen` accepts a loopback address only, and DNS rebinding protection is
+on. `--stream-limit` (default 500) caps how many messages a server-streaming
+RPC tool returns before it reports `truncated`.
+
+### The HTTP routes
+
+| Route | What it does |
+|---|---|
+| `POST /mcp` | starts an MCP session with `initialize`; later requests carry `mcp-session-id` |
+| `GET /mcp` | the session's notification stream |
+| `DELETE /mcp` | ends a session |
+| `GET /healthz` | liveness, plus the check-in source, the posture, the tool count and the open job |
+| `POST /turn` | puts a dispatch's grant in force |
+| `GET /turn` | reports the turn in force |
+| `DELETE /turn` | ends it |
+
+### Per-turn grants
+
+A member sandbox serves many dispatches over its life, and each input
+message carries the task grant of its own dispatch. The driver calls
+`POST /turn` before it feeds Claude a message:
+
+```
+POST /turn
+{"job_id": "job-1", "grant": "<CG-JWT>", "callback_endpoint": "daemon:50001"}
+-> 200 {"job_id": "job-1", "endpoint": "daemon:50001"}
+```
+
+Every tool call that follows runs under that grant. `DELETE /turn` ends the
+turn, and calls fall back to the **base grant** from the launch, which is
+used for the lifetime RPCs only: the inbox subscription, reading repository
+credentials, and the checkpoint writes. A single request may instead carry
+`x-gibson-turn-grant`, which applies to that request alone and wins over the
+turn in force; that is how a driver runs two turns at once.
+
+Both `job_id` and `grant` are required. A grant with no job attributes the
+work to nothing.
+
+`/turn` exists only where there is a task grant to swap. Elsewhere it is a
+404.
+
+## Check-in sources
+
+The server picks one credential source at start from what is present. It never
+mixes them, and it never mints identity.
+
+1. **Dispatched grant.** `GIBSON_CG_JWT` and `GIBSON_CALLBACK_ENDPOINT` are
+   set, so the daemon launched this process. The server joins the run it was
+   launched for. No enrollment, no state file, no mission. This source wins
+   over every other.
+2. **Pre-minted token.** `GIBSON_BOOTSTRAP_TOKEN` is set and this host has no
+   key yet. The server checks in once with the token. The host key carries
+   every later start, and the token is spent.
+3. **Enrolled host key.** The key at `GIBSON_HOST_KEY_PATH` (default
+   `~/.zerocool/host.key`) is the credential.
+4. **Nothing yet.** The server offers `gibson_login` and `gibson_connect`: a
+   person signs in through the `gibson` CLI device flow, and the server
+   enrolls the host, picks the target and starts the live mission without a
+   restart.
+
+Call `gibson_status` to see the source, the posture, the platform, the tenant,
+the target and the mission.
+
+## Postures
+
+A platform the server cannot reach never stops a session. Each posture below
+carries fewer tools than the one before it.
+
+- `task`: a dispatched run. Reads and writes use the dispatch grant.
+- `live`: checked in, and this session is a mission of its own.
+- `component`: checked in, no mission. Reads and findings only.
+- `standalone`: no platform. Findings go to a local log.
+
+## Environment
+
+| Variable | Meaning |
+|---|---|
+| `GIBSON_PLATFORM_URL` | the platform to check in to |
+| `GIBSON_TARGET_ID` | the target the live mission binds to |
+| `GIBSON_BOOTSTRAP_TOKEN` | a one-time enrollment token |
+| `GIBSON_HOST_KEY_PATH` | the host key (default `~/.zerocool/host.key`) |
+| `GIBSON_CA_CERT` | a private CA to trust |
+| `GIBSON_CALLBACK_INSECURE` | `1` dials the callback endpoint without TLS. Local daemons only. |
+| `ZEROCOOL_STATE_DIR` | the state directory (default `~/.zerocool`) |
+
+## License
+
+MIT.

package/dist/ambient.d.ts

@@ -0,0 +1,7 @@
+import { type KnowledgeSource } from "@zeroroot-ai/sdk";
+/**
+ * One GraphRAG lookup per session, read by a session-start hook or the gibson://ambient resource. A
+ * knowledge failure never breaks a start: the agent works without prior
+ * context, it just works less well.
+ */
+export declare function ambientBlock(knowledge: KnowledgeSource, seedQuery: string): Promise<string>;

package/dist/ambient.js

@@ -0,0 +1,18 @@
+import { formatKnowledgeForPrompt } from "@zeroroot-ai/sdk";
+/** How many hits the ambient block carries. Small: it is prompt overhead on every session. */
+const AMBIENT_LIMIT = 5;
+/**
+ * One GraphRAG lookup per session, read by a session-start hook or the gibson://ambient resource. A
+ * knowledge failure never breaks a start: the agent works without prior
+ * context, it just works less well.
+ */
+export async function ambientBlock(knowledge, seedQuery) {
+    try {
+        const hits = await knowledge.query({ text: seedQuery, topK: AMBIENT_LIMIT });
+        const body = formatKnowledgeForPrompt(hits);
+        return body ? `Prior context from the Gibson knowledge graph (recall for more):\n${body}` : "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/ask.d.ts

@@ -0,0 +1,70 @@
+import { type Inbox, type JobInput } from "./inbox.js";
+import { type Log } from "./log.js";
+import type { ToolDefinition } from "./registry.js";
+/**
+ * `ask`: the one way a job reaches a person (gibson#1706, decision 16).
+ *
+ * The wire has no `INPUT_KIND_QUESTION`. `gibson.job.v1.InputKind` carries
+ * `TURN`, `ANSWER` and `WRAP_UP`, and issue #59 expected a
+ * `JobService.SendEvent` that B1 did not ship. So the question is signalled
+ * two ways with what exists: `ReportJobState(job_id, WAITING)` is the state
+ * the console renders and the stale-limit reaper reads, and the text rides
+ * on an input, which is the only field on the wire that carries prose. The
+ * id the daemon returns for that input is remembered, so a member that is
+ * handed back its own question says so instead of answering itself.
+ *
+ * A job runs Claude Code with `--dangerously-skip-permissions`; the gVisor
+ * sandbox and the per-turn grant are the controls. So there is no permission
+ * dialog, and a question has to travel the same path as every other input:
+ * out through the job, back through the inbox. The driver wires this tool as
+ * `--permission-prompt-tool mcp__gibson__ask`.
+ *
+ * The job enters `waiting` while the question is outstanding, and the next
+ * input for that job is the answer. Input for another job is not an answer
+ * to this question, so it is left in the stream for its own turn.
+ *
+ * The reply is the shape Claude Code's permission-prompt contract expects:
+ * `{"behavior":"allow","updatedInput":{...}}` or
+ * `{"behavior":"deny","message":"..."}`. A free-text answer to a plain
+ * question comes back as an allow carrying the text, because that is how a
+ * question that is not about a tool call is answered.
+ */
+/** What Claude Code reads back from a permission-prompt tool. */
+export type PermissionDecision = {
+    behavior: "allow";
+    updatedInput: Record<string, unknown>;
+} | {
+    behavior: "deny";
+    message: string;
+};
+export declare function decisionFrom(answer: string, toolInput: Record<string, unknown>): PermissionDecision;
+/** A source of answers: the next input for one job. */
+export interface AnswerSource {
+    /** Resolve with the next input for `jobId`, or reject when it cannot come. */
+    next(jobId: string, signal?: AbortSignal): Promise<JobInput>;
+}
+/**
+ * Route inbox messages to whoever is waiting for that job.
+ *
+ * One reader of the stream, many waiters: two jobs can each hold an open
+ * question at the same time, and a message for one must not wake the other.
+ */
+export declare class AnswerRouter implements AnswerSource {
+    private readonly waiting;
+    private readonly pending;
+    /** Offer a message. Returns true when a waiter took it. */
+    offer(input: JobInput): boolean;
+    /** Hold a message that arrived before anyone asked for it. */
+    hold(input: JobInput): void;
+    next(jobId: string, signal?: AbortSignal): Promise<JobInput>;
+}
+export interface AskOptions {
+    /** The job the current turn belongs to. */
+    jobId: () => string | undefined;
+    inbox: Pick<Inbox, "send" | "reportState">;
+    answers: AnswerSource;
+    /** The Claude Code session this job runs, when the driver knows it. */
+    claudeSessionId?: () => string | undefined;
+    log?: Log;
+}
+export declare function askTool(opts: AskOptions): ToolDefinition;

package/dist/ask.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { InputKind, JobState } from "./inbox.js";
+import { TAG } from "./log.js";
+import { defineTool } from "./tool.js";
+import { failure, text } from "./tools/result.js";
+/** Words an answer may use to refuse. Anything else allows. */
+const DENIALS = /^\s*(no|deny|denied|reject|rejected|refuse|refused|stop|do not|don't)\b/i;
+export function decisionFrom(answer, toolInput) {
+    if (DENIALS.test(answer))
+        return { behavior: "deny", message: answer.trim() };
+    return { behavior: "allow", updatedInput: toolInput };
+}
+/**
+ * Route inbox messages to whoever is waiting for that job.
+ *
+ * One reader of the stream, many waiters: two jobs can each hold an open
+ * question at the same time, and a message for one must not wake the other.
+ */
+export class AnswerRouter {
+    waiting = new Map();
+    pending = new Map();
+    /** Offer a message. Returns true when a waiter took it. */
+    offer(input) {
+        const queue = this.waiting.get(input.jobId);
+        if (!queue)
+            return false;
+        const resolve = queue.shift();
+        if (!resolve)
+            return false;
+        if (queue.length === 0)
+            this.waiting.delete(input.jobId);
+        resolve(input);
+        return true;
+    }
+    /** Hold a message that arrived before anyone asked for it. */
+    hold(input) {
+        if (this.offer(input))
+            return;
+        const queue = this.pending.get(input.jobId) ?? [];
+        queue.push(input);
+        this.pending.set(input.jobId, queue);
+    }
+    next(jobId, signal) {
+        const held = this.pending.get(jobId);
+        const first = held?.shift();
+        if (first) {
+            if (held && held.length === 0)
+                this.pending.delete(jobId);
+            return Promise.resolve(first);
+        }
+        return new Promise((resolve, reject) => {
+            const queue = this.waiting.get(jobId) ?? [];
+            queue.push(resolve);
+            this.waiting.set(jobId, queue);
+            signal?.addEventListener("abort", () => {
+                const q = this.waiting.get(jobId);
+                const i = q?.indexOf(resolve) ?? -1;
+                if (q && i >= 0)
+                    q.splice(i, 1);
+                reject(new Error("the question was cancelled before an answer arrived"));
+            }, { once: true });
+        });
+    }
+}
+export function askTool(opts) {
+    return defineTool({
+        name: "ask",
+        description: "Ask the person or the agent that opened this job a question, and wait for the answer. Use it " +
+            "when you need a decision you cannot make yourself: a choice between two approaches, a missing " +
+            "fact, or permission for something outside the job's declared deliverable. The job waits while " +
+            "the question is open, so ask once and ask precisely.",
+        input: {
+            question: z.string().describe("The question, in one or two sentences. Say what you will do with each answer."),
+            tool_name: z.string().optional().describe("When this is a permission prompt, the tool Claude Code wants to run."),
+            input: z.record(z.string(), z.unknown()).optional().describe("When this is a permission prompt, the input Claude Code wants to run it with."),
+        },
+        handler: async (args, ctx) => {
+            const jobId = opts.jobId();
+            if (!jobId) {
+                return failure("no job is open", "ask reaches the person through the job's inbox, and this turn belongs to no job. " +
+                    "The driver sets the job with POST /turn before it feeds a message.");
+            }
+            const question = args.tool_name ? `${args.question}\n\nClaude Code wants to run ${args.tool_name} with:\n${JSON.stringify(args.input ?? {}, null, 2)}` : args.question;
+            try {
+                // The wait is armed before the question is sent. Arming it after
+                // would drop an answer that came back faster than this call returns.
+                const answer = opts.answers.next(jobId, ctx.signal);
+                // WAITING is the signal that a question is open: it is what the
+                // console renders and what the stale-limit reaper reads. The text
+                // rides on an input, because that is the only field on the wire that
+                // carries prose.
+                await opts.inbox.reportState(jobId, JobState.WAITING, opts.claudeSessionId?.());
+                const sent = await opts.inbox.send(jobId, question, InputKind.TURN);
+                opts.log?.(`${TAG} job ${jobId} is waiting on a question`);
+                const input = await answer.finally(async () => {
+                    await opts.inbox.reportState(jobId, JobState.WORKING, opts.claudeSessionId?.()).catch(() => { });
+                });
+                opts.log?.(`${TAG} job ${jobId} got its answer from ${input.sender || "the inbox"}`);
+                if (input.id && input.id === sent.id) {
+                    return failure("ask heard its own question", "The inbox returned the question this job just posted. The daemon must not deliver a member its own input.");
+                }
+                if (args.tool_name)
+                    return text("", JSON.stringify(decisionFrom(input.message, args.input ?? {})));
+                return text("", input.message);
+            }
+            catch (e) {
+                return failure("ask failed", e.message);
+            }
+        },
+    });
+}

package/dist/build.d.ts

@@ -0,0 +1,83 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport as ConnectTransport } from "@connectrpc/connect";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { ToolRegistry, type ToolDefinition, type ToolGroup } from "./registry.js";
+import type { TurnRoute } from "./http.js";
+import { type Discovery } from "./discovery.js";
+import { type Inbox } from "./inbox.js";
+import { type RpcChannels } from "./rpc.js";
+import { type AmbientSource } from "./resources.js";
+import { type Gibson } from "./session.js";
+import { type ConnectDeps } from "./tools/connect.js";
+/**
+ * @zeroroot-ai/gibson-mcp: the one MCP server every coding agent host loads
+ * (gibson#1706, decisions 1 to 4). It exposes what the SDK produces and adds
+ * Gibson to the session: one live mission per session (ADR-0007 decision 3),
+ * memory and knowledge, findings, tools, delegation. It never routes LLM
+ * traffic and never reads a model provider key.
+ *
+ * The surface is one tool registry that every attached protocol server
+ * reads. `upgrade` swaps the connection (after `gibson_connect`) and
+ * re-registers the posture's tools, and every attached session hears
+ * `tools/list_changed`.
+ */
+export interface BuildDeps extends ConnectDeps {
+    streamLimit?: number;
+    /** How often to look for newly checked-in platform tools. `0` runs one pass. */
+    discoveryIntervalMs?: number;
+}
+export interface Surface {
+    registry: ToolRegistry;
+    /** The current connection. Changes on gibson_connect. */
+    current(): Gibson;
+    /** Replace the connection and re-register the posture's tools. */
+    upgrade(next: Gibson): Promise<void>;
+    /** Bind a new protocol server to a transport. */
+    attach(transport: Transport): Promise<Server>;
+    /** Small JSON for /healthz. */
+    health(): Record<string, unknown>;
+    /**
+     * The per-turn grant control, when this posture holds a task grant. The
+     * HTTP transport serves it at `/turn`; the stdio transport does not expose
+     * it, because a host that spawns one process per session has one grant.
+     */
+    turn?: TurnRoute;
+    /** The member inbox, when this posture holds a task grant. */
+    inbox?: Inbox;
+    /** End the mission, stop the heartbeat, drop the state file. Idempotent. */
+    close(): Promise<void>;
+}
+export declare function buildSurface(env: NodeJS.ProcessEnv, cwd: string, deps?: BuildDeps): Promise<Surface>;
+export interface PostureContext {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    streamLimit: number;
+    /** The session's ambient block, for the hook handoff. */
+    ambient?: AmbientSource;
+    discoveryIntervalMs?: number;
+    /** The per-turn transport, when this posture serves turns. */
+    taskTransport?: ConnectTransport;
+    /** The `ask` tool, when this posture has an inbox to ask through. */
+    ask?: ToolDefinition;
+}
+/**
+ * Which transports this posture holds, for the generated RPC tools.
+ *
+ * `taskTransport` is the per-turn transport when there is one. The harness
+ * object is passed through whole, because the RPC tools also read its
+ * `context` to fill `ContextInfo`; only the transport is swapped.
+ */
+export declare function channelsOf(gibson: Gibson, taskTransport?: ConnectTransport): RpcChannels;
+/**
+ * The tools a posture carries: one per RPC, one per SDK helper, one per
+ * checked-in platform tool.
+ *
+ * A standalone posture holds no transport, so it carries no RPC tools: a
+ * tool with no daemon behind it answers every call with a dial error, which
+ * reads to a model like a broken platform rather than an unconnected
+ * session. Its helper tools are the ones that need no platform.
+ *
+ * Returns the discovery poller when this posture has a catalog to poll, so
+ * the caller can stop it on upgrade or close.
+ */
+export declare function registerPosture(group: ToolGroup, gibson: Gibson, ctx: PostureContext): Promise<Discovery | undefined>;