@zeroroot-ai/gibson-mcp 0.1.0 → 0.2.0

package/README.md

@@ -36,22 +36,61 @@ snippets and their smoke tests live in
 
 ## The tool surface
 
-The surface is 1:1 with everything the SDK produces. One flat tier, no
-curated subset.
+Coverage is 1:1 with everything the SDK produces. **Exposure** is in two
+tiers, because 188 tool descriptions on every turn cost more context than
+they are worth, bury the tools an agent reaches for, and trip the tool cap
+some hosts impose.
+
+### Front tier, in `tools/list`
 
 | 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 |
+| the session's own tools | `gibson_status`, `gibson_login`, `gibson_connect`, `gibson_call_tool`, `ask` | 5 |
+| the door to the full API | `gibson_api_search`, `gibson_api_call` | 2 |
+
+Discovery repeats every 60 seconds and emits `tools/list_changed`, so a tool
+a person enrols now is callable in the same session.
+
+### Full tier, behind the door
+
+Every RPC of every SDK service, generated from the proto descriptors and
+named `<service>_<method>` in snake case: **188 across 12 services** today.
+They are all built and all callable. They are simply not listed.
+
+```
+gibson_api_search("")                    -> the 12 services, with a count each
+gibson_api_search("open a job on a bank") -> job_service_open_job, with its input schema
+gibson_api_call("job_service_open_job", {...})
+```
+
+`gibson_api_search` ranks on the RPC name, the service name and the proto
+comment, and returns each match with its exact tool name, its description,
+its service and the **full input JSON schema**, so one search is enough to
+make the call. An empty query lists the services instead, so an agent can
+orient before it searches. `gibson_api_call` runs the same handler the flat
+tier would register, so the two paths cannot disagree; an unknown name comes
+back with the three closest.
+
+An SDK bump regenerates the full tier. A drift guard fails CI when the
+generated table and the descriptors disagree, in either direction, so
+hiding a tool never means losing one.
+
+### `--expose-all-rpcs`
 
-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.
+Registers the full tier in `tools/list` as well, which is what the server
+did before this became two tiers. Off by default. A host with a large
+context window and no tool cap can take the flat 1:1 surface. The door stays
+open with the flag on, because finding one RPC among 188 is still cheaper
+through a search than through the list.
 
 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`.
+`validate_component`, plus `gibson_login` and `gibson_connect`, and no RPC
+tool at all: 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.
 
 ## Resources and prompts
 
@@ -72,7 +111,8 @@ one calls the `gibson_ambient` prompt instead. Either way it is one lookup.
 
 `--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`.
+RPC tool returns before it reports `truncated`. `--expose-all-rpcs` lists the
+full RPC tier as well; see the tool surface below.
 
 ### The HTTP routes
 
@@ -81,7 +121,7 @@ RPC tool returns before it reports `truncated`.
 | `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 |
+| `GET /healthz` | liveness, plus the check-in source, the posture, the listed tool count, the reachable RPC 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 |

package/dist/api.d.ts

@@ -0,0 +1,40 @@
+import type { ToolDefinition } from "./registry.js";
+import type { RpcEntry } from "./rpc.js";
+export declare const DEFAULT_SEARCH_LIMIT = 10;
+export declare const MAX_SEARCH_LIMIT = 50;
+export declare const SUGGESTIONS = 3;
+export declare function terms(query: string): string[];
+/**
+ * Rank one RPC against a query.
+ *
+ * The weights say what a person searching for an RPC is actually naming: the
+ * method first, the service second, the prose last. A whole-word hit beats a
+ * substring, so "job" does not rank `job_service_get_job` below something
+ * that merely contains "jobs" in a sentence.
+ */
+export declare function score(entry: RpcEntry, query: string): number;
+export interface SearchHit {
+    name: string;
+    description: string;
+    service: string;
+    input_schema: unknown;
+    score: number;
+}
+/** Rank the catalog. Ties break on the shorter name, then alphabetically. */
+export declare function search(catalog: RpcEntry[], query: string, limit: number): SearchHit[];
+/** The services in the catalog, with a method count each. */
+export declare function services(catalog: RpcEntry[]): {
+    service: string;
+    tools: number;
+    example: string;
+}[];
+/** Dice coefficient over character bigrams. Survives a typo; an equality test does not. */
+export declare function similarity(a: string, b: string): number;
+/** The names closest to `name`, for a caller that mistyped one. */
+export declare function closest(catalog: RpcEntry[], name: string, count?: number): string[];
+export interface ApiToolOptions {
+    catalog: RpcEntry[];
+    /** True when the flat set is also in `tools/list`, which changes what to say. */
+    exposeAll?: boolean;
+}
+export declare function apiTools(opts: ApiToolOptions): ToolDefinition[];

package/dist/api.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import { defineTool } from "./tool.js";
+import { failure, json } from "./tools/result.js";
+/**
+ * The door to the full API (sdk-ts#70).
+ *
+ * The platform's whole surface is one tool per RPC, and there are 188 of
+ * them. Every host loads every description into the model context on each
+ * turn, so putting all of them in `tools/list` costs the same tokens whether
+ * or not the agent needs a single one, buries the tools it actually reaches
+ * for, and trips the tool cap some hosts impose.
+ *
+ * So the generated tools stay built and stay 1:1 with the descriptors, and
+ * two tools stand in front of them: one to find an RPC, one to call it.
+ * Coverage is unchanged. Only exposure changed, and `--expose-all-rpcs`
+ * puts the flat set back in `tools/list` for a host that wants it.
+ */
+/** Words that carry no signal in a search over RPC names. */
+const STOPWORDS = new Set(["a", "an", "the", "to", "for", "of", "in", "on", "with", "and", "or", "is", "are", "be", "please", "me", "my"]);
+export const DEFAULT_SEARCH_LIMIT = 10;
+export const MAX_SEARCH_LIMIT = 50;
+export const SUGGESTIONS = 3;
+export function terms(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+/** True when `haystack` holds `term` as a whole underscore- or space-separated word. */
+function wholeWord(haystack, term) {
+    return new RegExp(`(^|[^a-z0-9])${term}([^a-z0-9]|$)`).test(haystack);
+}
+/**
+ * Rank one RPC against a query.
+ *
+ * The weights say what a person searching for an RPC is actually naming: the
+ * method first, the service second, the prose last. A whole-word hit beats a
+ * substring, so "job" does not rank `job_service_get_job` below something
+ * that merely contains "jobs" in a sentence.
+ */
+export function score(entry, query) {
+    const words = terms(query);
+    if (words.length === 0)
+        return 0;
+    const method = entry.method.name.toLowerCase();
+    const methodSnake = entry.tool.name.slice(entry.tool.name.length - method.length);
+    const service = entry.service.name.toLowerCase();
+    const comment = entry.comment.toLowerCase();
+    const toolName = entry.tool.name;
+    let total = 0;
+    let hit = 0;
+    for (const term of words) {
+        let best = 0;
+        if (wholeWord(methodSnake, term))
+            best = 10;
+        else if (methodSnake.includes(term))
+            best = 6;
+        if (best === 0 && wholeWord(service, term))
+            best = 4;
+        else if (best === 0 && service.includes(term))
+            best = 2;
+        if (best === 0 && wholeWord(comment, term))
+            best = 3;
+        else if (best === 0 && comment.includes(term))
+            best = 1;
+        if (best > 0)
+            hit += 1;
+        total += best;
+    }
+    if (total === 0)
+        return 0;
+    // A query whose every word landed beats one that matched half of itself,
+    // whatever the raw weights add up to.
+    total += hit === words.length ? 8 : 0;
+    // The whole phrase written as a tool name is the strongest signal there is.
+    if (toolName.includes(words.join("_")))
+        total += 8;
+    return total;
+}
+/** Rank the catalog. Ties break on the shorter name, then alphabetically. */
+export function search(catalog, query, limit) {
+    return catalog
+        .map((entry) => ({ entry, score: score(entry, query) }))
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score || a.entry.tool.name.length - b.entry.tool.name.length || (a.entry.tool.name < b.entry.tool.name ? -1 : 1))
+        .slice(0, limit)
+        .map(({ entry, score: value }) => ({
+        name: entry.tool.name,
+        description: entry.tool.description,
+        service: entry.service.typeName,
+        input_schema: entry.tool.inputSchema,
+        score: value,
+    }));
+}
+/** The services in the catalog, with a method count each. */
+export function services(catalog) {
+    const byService = new Map();
+    for (const entry of catalog) {
+        const list = byService.get(entry.service.typeName) ?? [];
+        list.push(entry);
+        byService.set(entry.service.typeName, list);
+    }
+    return [...byService.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([name, entries]) => ({ service: name, tools: entries.length, example: entries[0].tool.name }));
+}
+/** Dice coefficient over character bigrams. Survives a typo; an equality test does not. */
+export function similarity(a, b) {
+    const grams = (s) => Array.from({ length: Math.max(0, s.length - 1) }, (_, i) => s.slice(i, i + 2));
+    const left = grams(a);
+    const right = new Map();
+    for (const g of grams(b))
+        right.set(g, (right.get(g) ?? 0) + 1);
+    let shared = 0;
+    for (const g of left) {
+        const n = right.get(g) ?? 0;
+        if (n > 0) {
+            shared += 1;
+            right.set(g, n - 1);
+        }
+    }
+    return left.length + grams(b).length === 0 ? 0 : (2 * shared) / (left.length + grams(b).length);
+}
+/** The names closest to `name`, for a caller that mistyped one. */
+export function closest(catalog, name, count = SUGGESTIONS) {
+    return catalog
+        .map((entry) => ({ name: entry.tool.name, score: similarity(name.toLowerCase(), entry.tool.name) }))
+        .sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : 1))
+        .slice(0, count)
+        .map((c) => c.name);
+}
+/**
+ * The description both meta-tools carry.
+ *
+ * It has one job: tell a model the door exists. A model that never reads the
+ * 188 entries has no other way to learn that `CreateBank`, `OpenJob` or
+ * `PutSessionContext` are reachable at all, so the examples are not
+ * decoration.
+ */
+function surfaceLine(catalog) {
+    const count = catalog.length;
+    const serviceCount = new Set(catalog.map((e) => e.service.typeName)).size;
+    return (`The Gibson platform's whole API is reachable this way: ${count} RPCs across ${serviceCount} services, ` +
+        "including banks of always-on agents (CreateBank, ListMembers), jobs (OpenJob, SendInput, CloseJob), " +
+        "missions (CreateMission, RunMission), the knowledge graph (QueryNodes, Observe), findings, targets, " +
+        "component registration, credentials and the session store. These RPCs are not in your tool list, " +
+        "because listing all of them would cost more context than it is worth. Search here first.");
+}
+export function apiTools(opts) {
+    const { catalog } = opts;
+    const byName = new Map(catalog.map((e) => [e.tool.name, e]));
+    const surface = surfaceLine(catalog);
+    return [
+        defineTool({
+            name: "gibson_api_search",
+            description: `Find an RPC on the Gibson platform API. ${surface} ` +
+                "Returns each match with its exact tool name, its description, its service, and the full JSON " +
+                "schema of its input, so the result is everything you need to call it with gibson_api_call. " +
+                'Call it with an empty query to see the services and how many RPCs each one has, e.g. query "" first, ' +
+                'then query "open a job" or "submit a finding".',
+            input: {
+                query: z
+                    .string()
+                    .describe('What you want to do, in your own words, e.g. "submit a finding" or "list the members of a bank". Empty lists the services instead.'),
+                limit: z.number().int().min(1).max(MAX_SEARCH_LIMIT).optional().describe(`Maximum matches. Defaults to ${DEFAULT_SEARCH_LIMIT}, capped at ${MAX_SEARCH_LIMIT}.`),
+            },
+            annotations: { readOnlyHint: true },
+            handler: async (args) => {
+                if (catalog.length === 0) {
+                    return failure("no platform API", "This session is not checked in to a platform, so no RPC is reachable. Call gibson_status.");
+                }
+                // An empty query is an agent orienting itself, not a failed search.
+                // Answering with "no matches" would teach it the API is empty.
+                if (!args.query.trim()) {
+                    return json({ services: services(catalog), rpcs: catalog.length, next: 'Search again with what you want to do, e.g. "open a job".' });
+                }
+                const limit = Math.min(args.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+                const hits = search(catalog, args.query, limit);
+                if (hits.length === 0) {
+                    return json({
+                        query: args.query,
+                        matches: [],
+                        services: services(catalog).map((s) => s.service),
+                        next: "Nothing matched. Try one word from the thing you want to act on, or search with an empty query to see the services.",
+                    });
+                }
+                return json({ query: args.query, matches: hits, showing: hits.length, of: catalog.length });
+            },
+        }),
+        defineTool({
+            name: "gibson_api_call",
+            description: `Call one RPC on the Gibson platform API by its exact tool name. ${surface} ` +
+                "Use gibson_api_search first to get the name and the input schema. The input must be canonical " +
+                "protojson for that RPC's request message. A name that does not exist comes back with the closest " +
+                "ones, so a near miss costs one call rather than a guess.",
+            input: {
+                name: z.string().describe('Exact tool name from gibson_api_search, e.g. "harness_callback_service_world_view".'),
+                input: z.record(z.string(), z.unknown()).optional().describe("The request message as protojson. Omit for an RPC whose request has no fields."),
+                timeout_ms: z.number().int().min(1).optional().describe("Per-call deadline in milliseconds."),
+            },
+            handler: async (args, ctx) => {
+                if (catalog.length === 0) {
+                    return failure("no platform API", "This session is not checked in to a platform, so no RPC is reachable. Call gibson_status.");
+                }
+                const entry = byName.get(args.name);
+                if (!entry) {
+                    const suggestions = closest(catalog, args.name);
+                    return failure(`no RPC named ${args.name}`, `The closest names are:\n${suggestions.map((s) => `- ${s}`).join("\n")}\n\nCall gibson_api_search to find the right one.`);
+                }
+                // The same handler the flat tier registers, so the two paths cannot
+                // drift: there is only one of them.
+                return entry.tool.handler(args.input ?? {}, { ...ctx, ...(args.timeout_ms ? { timeoutMs: args.timeout_ms } : {}) });
+            },
+        }),
+    ];
+}

package/dist/build.d.ts

@@ -5,7 +5,7 @@ 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 RpcChannels, type RpcEntry } from "./rpc.js";
 import { type AmbientSource } from "./resources.js";
 import { type Gibson } from "./session.js";
 import { type ConnectDeps } from "./tools/connect.js";
@@ -23,6 +23,8 @@ import { type ConnectDeps } from "./tools/connect.js";
  */
 export interface BuildDeps extends ConnectDeps {
     streamLimit?: number;
+    /** Register the generated RPC tools in `tools/list` as well. Default off. */
+    exposeAllRpcs?: boolean;
     /** How often to look for newly checked-in platform tools. `0` runs one pass. */
     discoveryIntervalMs?: number;
 }
@@ -52,6 +54,8 @@ export interface PostureContext {
     env: NodeJS.ProcessEnv;
     cwd: string;
     streamLimit: number;
+    /** Register the generated RPC tools in `tools/list` as well. Default off. */
+    exposeAllRpcs?: boolean;
     /** The session's ambient block, for the hook handoff. */
     ambient?: AmbientSource;
     discoveryIntervalMs?: number;
@@ -59,6 +63,8 @@ export interface PostureContext {
     taskTransport?: ConnectTransport;
     /** The `ask` tool, when this posture has an inbox to ask through. */
     ask?: ToolDefinition;
+    /** Told the full tier this posture built, for /healthz. */
+    onCatalog?: (catalog: RpcEntry[]) => void;
 }
 /**
  * Which transports this posture holds, for the generated RPC tools.

package/dist/build.js

@@ -7,7 +7,8 @@ import { AnswerRouter, askTool } from "./ask.js";
 import { startDiscovery } from "./discovery.js";
 import { inboxAvailable, openInbox, routeAnswers } from "./inbox.js";
 import { helperToolsFor } from "./helpers/index.js";
-import { rpcTools } from "./rpc.js";
+import { apiTools } from "./api.js";
+import { rpcCatalog } from "./rpc.js";
 import { createTurnController, TURN_GRANT_HEADER } from "./turn.js";
 import { ambientPrompt, ambientSource, resources } from "./resources.js";
 import { openGibson } from "./session.js";
@@ -28,6 +29,10 @@ export async function buildSurface(env, cwd, deps = {}) {
     let inbox;
     const answers = new AnswerRouter();
     let ambient = ambientSource(gibson, env);
+    // The full tier is built but usually not listed, so its size is not the
+    // registry's size. /healthz reports both, because a driver checking the
+    // server is up also wants to know the API is reachable.
+    let fullTier = 0;
     if (gibson.live) {
         turns = createTurnController({ base: gibson.live.harness, insecure: gibson.settings.callbackInsecure, log });
         registry.use((ctx, next) => {
@@ -49,9 +54,13 @@ export async function buildSurface(env, cwd, deps = {}) {
         env,
         cwd,
         streamLimit,
+        ...(deps.exposeAllRpcs ? { exposeAllRpcs: true } : {}),
         ...(deps.discoveryIntervalMs === undefined ? {} : { discoveryIntervalMs: deps.discoveryIntervalMs }),
         ...(turns ? { taskTransport: turns.transport() } : {}),
         ambient: { block: (q) => ambient.block(q) },
+        onCatalog: (catalog) => {
+            fullTier = catalog.length;
+        },
         ...(inbox
             ? {
                 ask: askTool({ jobId: () => turns?.current()?.jobId, inbox, answers, log }),
@@ -80,7 +89,13 @@ export async function buildSurface(env, cwd, deps = {}) {
             resources: resources(() => gibson, { block: (q) => ambient.block(q) }),
             prompts: [ambientPrompt({ block: (q) => ambient.block(q) })],
         }, transport),
-        health: () => ({ source: gibson.source, posture: gibson.mode, tools: registry.size(), ...(turns?.current() ? { job: turns.current().jobId } : {}) }),
+        health: () => ({
+            source: gibson.source,
+            posture: gibson.mode,
+            tools: registry.size(),
+            api_rpcs: fullTier,
+            ...(turns?.current() ? { job: turns.current().jobId } : {}),
+        }),
         ...(inbox ? { inbox } : {}),
         ...(turns
             ? {
@@ -148,11 +163,27 @@ export async function registerPosture(group, gibson, ctx) {
         group.register(tool);
     if (ctx.ask)
         group.register(ctx.ask);
+    // Two tiers (sdk-ts#70). The generated tools are always BUILT, and the
+    // drift guard proves that set is 1:1 with the descriptors. What changes
+    // here is only whether they are listed: by default they sit behind
+    // gibson_api_search and gibson_api_call, because 188 descriptions on every
+    // turn bury the tools an agent reaches for and trip some hosts' tool caps.
     const channels = channelsOf(gibson, ctx.taskTransport);
+    let catalog = [];
     if (channels.session || channels.task) {
-        for (const tool of rpcTools({ channels, streamLimit: ctx.streamLimit }))
+        catalog = rpcCatalog({ channels, streamLimit: ctx.streamLimit });
+        if (ctx.exposeAllRpcs) {
+            for (const entry of catalog)
+                group.register(entry.tool);
+        }
+        // The door is registered either way. With the flat set in front it is
+        // still the cheapest way to find one RPC among 188.
+        for (const tool of apiTools({ catalog, ...(ctx.exposeAllRpcs ? { exposeAll: true } : {}) }))
             group.register(tool);
+        log(`${TAG} ${catalog.length} RPC tool(s) ${ctx.exposeAllRpcs ? "listed and reachable" : "reachable"} through gibson_api_search and gibson_api_call` +
+            `${ctx.exposeAllRpcs ? " (--expose-all-rpcs)" : ""}`);
     }
+    ctx.onCatalog?.(catalog);
     await writeHandoff(gibson, ctx);
     // Discovery reads the tenant catalog, which is a ComponentService call, so
     // it needs the component check-in. A dispatched run has none.
@@ -205,5 +236,7 @@ async function writeHandoff(gibson, ctx) {
 }
 function instructions() {
     return ("Gibson tools. Call gibson_status to see how this session is connected. " +
-        "Without a platform, call gibson_login and then gibson_connect to enroll this host and start a live mission.");
+        "Without a platform, call gibson_login and then gibson_connect to enroll this host and start a live mission. " +
+        "The tools listed here are the ones used most; the platform's whole API is reachable through " +
+        "gibson_api_search and gibson_api_call.");
 }

package/dist/flags.d.ts

@@ -10,6 +10,11 @@
  *    network interface.
  *  - `--stream-limit <n>`: how many messages a server-streaming RPC tool
  *    collects before it returns with `truncated: true` (slice A2).
+ *  - `--expose-all-rpcs`: put the generated RPC tools in `tools/list` as
+ *    well, which is what the server did before sdk-ts#70. Off by default:
+ *    188 descriptions on every turn bury the tools an agent reaches for, and
+ *    some hosts cap the tool count. They are always reachable through
+ *    `gibson_api_search` and `gibson_api_call`, flag or no flag.
  */
 export type TransportKind = "stdio" | "http";
 export interface Listen {
@@ -20,6 +25,8 @@ export interface Flags {
     transport: TransportKind;
     listen: Listen;
     streamLimit: number;
+    /** Register the generated RPC tools in `tools/list` as well. */
+    exposeAllRpcs: boolean;
     help: boolean;
     version: boolean;
 }

package/dist/flags.js

@@ -43,6 +43,7 @@ export function parseFlags(argv) {
             transport: { type: "string", default: "stdio" },
             listen: { type: "string", default: DEFAULT_LISTEN },
             "stream-limit": { type: "string", default: String(DEFAULT_STREAM_LIMIT) },
+            "expose-all-rpcs": { type: "boolean", default: false },
             help: { type: "boolean", short: "h", default: false },
             version: { type: "boolean", default: false },
         },
@@ -59,6 +60,7 @@ export function parseFlags(argv) {
         transport,
         listen: parseListen(values.listen),
         streamLimit,
+        exposeAllRpcs: values["expose-all-rpcs"],
         help: values.help,
         version: values.version,
     };
@@ -74,6 +76,8 @@ export function usage() {
         "  --transport stdio|http   stdio (default) for a host that spawns the server; http for a sandbox.",
         `  --listen host:port       loopback address for the HTTP transport (default ${DEFAULT_LISTEN}).`,
         `  --stream-limit n         messages a streaming RPC tool returns before it truncates (default ${DEFAULT_STREAM_LIMIT}).`,
+        "  --expose-all-rpcs        also list every generated RPC tool in tools/list. Off by default: they are",
+        "                           reachable through gibson_api_search and gibson_api_call either way.",
         "  --version                print the package version.",
         "  -h, --help               this text.",
         "",

package/dist/index.d.ts

@@ -8,7 +8,8 @@ export { attachServer, packageVersion, SERVER_NAME } from "./server.js";
 export { ToolRegistry, type JsonSchema, type ToolContext, type ToolDefinition, type ToolGroup, type ToolHandler } from "./registry.js";
 export { defineTool, jsonSchemaOf, type ToolSpec } from "./tool.js";
 export { openGibson, type Gibson, type OpenGibsonOptions } from "./session.js";
-export { rpcTools, snake, toolNameFor, transportFor, type RpcChannels, type RpcToolOptions } from "./rpc.js";
+export { rpcCatalog, rpcTools, driftBetween, snake, toolNameFor, transportFor, type Drift, type RpcChannels, type RpcEntry, type RpcToolOptions, type ServiceDoc } from "./rpc.js";
+export { apiTools, closest, score, search, services, similarity, terms, DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, type ApiToolOptions, type SearchHit, } from "./api.js";
 export { messageSchema, requestSchema, MAX_DEPTH } from "./schema.js";
 export { startDiscovery, toolKey, pluginKey, DISCOVERY_INTERVAL_MS, type Discovery, type DiscoveryOutcome } from "./discovery.js";
 export { helperTools, helperToolsFor, helperContext, HELPER_TOOL_FOR_EXPORT, NOT_A_TOOL, TOOL_WITHOUT_EXPORT, type HelperContext } from "./helpers/index.js";

package/dist/index.js

@@ -10,7 +10,8 @@ export { attachServer, packageVersion, SERVER_NAME } from "./server.js";
 export { ToolRegistry } from "./registry.js";
 export { defineTool, jsonSchemaOf } from "./tool.js";
 export { openGibson } from "./session.js";
-export { rpcTools, snake, toolNameFor, transportFor } from "./rpc.js";
+export { rpcCatalog, rpcTools, driftBetween, snake, toolNameFor, transportFor } from "./rpc.js";
+export { apiTools, closest, score, search, services, similarity, terms, DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, } from "./api.js";
 export { messageSchema, requestSchema, MAX_DEPTH } from "./schema.js";
 export { startDiscovery, toolKey, pluginKey, DISCOVERY_INTERVAL_MS } from "./discovery.js";
 export { helperTools, helperToolsFor, helperContext, HELPER_TOOL_FOR_EXPORT, NOT_A_TOOL, TOOL_WITHOUT_EXPORT } from "./helpers/index.js";

package/dist/main.js

@@ -30,7 +30,7 @@ async function main() {
         return;
     }
     const cwd = process.cwd();
-    const surface = await buildSurface(process.env, cwd, { streamLimit: flags.streamLimit });
+    const surface = await buildSurface(process.env, cwd, { streamLimit: flags.streamLimit, ...(flags.exposeAllRpcs ? { exposeAllRpcs: true } : {}) });
     log(`${TAG} ${describeGibson(surface.current()).replaceAll("\n", "; ")}`);
     log(`${TAG} ${surface.registry.size()} tool(s) registered`);
     let closing = false;

package/dist/registry.d.ts

@@ -9,6 +9,8 @@ export interface ToolContext {
     /** Request headers of the transport, when it has any (the HTTP transport). */
     headers?: Record<string, string | string[] | undefined>;
     signal?: AbortSignal;
+    /** Per-call deadline, when the caller set one. `gibson_api_call` does. */
+    timeoutMs?: number;
 }
 export type ToolHandler = (args: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>;
 /**

package/dist/rpc.d.ts

@@ -3,14 +3,21 @@ import { type Transport } from "@connectrpc/connect";
 import type { TaskHarness } from "@zeroroot-ai/sdk";
 import type { ToolDefinition } from "./registry.js";
 /**
- * One MCP tool per RPC of every service the SDK produces (gibson#1706,
- * decision 2). No curated subset and no hand-written list: the table comes
- * from the descriptors, so an SDK bump moves the tool set.
+ * One tool per RPC of every service the SDK produces (gibson#1706, decision
+ * 2). No curated subset and no hand-written list: the table comes from the
+ * descriptors, so an SDK bump moves the tool set.
  *
  * Naming is `<service>_<method>` in snake case, e.g.
  * `harness_callback_service_world_view`. The service prefix is what keeps
  * these apart from the helper tools, which are named after the helper
  * (`world_view`, `remember`, `submit_finding`).
+ *
+ * COVERAGE IS NOT EXPOSURE. Every one of these is built, and the drift guard
+ * proves the set is 1:1 with the descriptors. Whether they appear in
+ * `tools/list` is a separate decision, taken in build.ts: by default they sit
+ * behind `gibson_api_search` and `gibson_api_call` (sdk-ts#70), because 188
+ * descriptions on every turn bury the tools an agent reaches for.
+ * `--expose-all-rpcs` puts them in front as well.
  */
 /** Where an RPC is reached. */
 export interface RpcChannels {
@@ -46,6 +53,14 @@ export interface RpcToolOptions {
     /** Messages a server-streaming RPC returns before it truncates. */
     streamLimit: number;
 }
+/** One built RPC tool, with the descriptor facts a search can rank on. */
+export interface RpcEntry {
+    tool: ToolDefinition;
+    service: DescService;
+    method: DescMethod;
+    /** The RPC's proto comment, or "" when it carries none. */
+    comment: string;
+}
 /**
  * Build every RPC tool that has a transport to ride.
  *
@@ -53,6 +68,8 @@ export interface RpcToolOptions {
  * no daemon behind it would answer every call with a dial error, which reads
  * to a model like a broken platform rather than an unconnected session.
  */
+export declare function rpcCatalog(opts: RpcToolOptions): RpcEntry[];
+/** The same set as {@link rpcCatalog}, as bare tool definitions. */
 export declare function rpcTools(opts: RpcToolOptions): ToolDefinition[];
 /** An empty request message, for a test that needs one. */
 export declare function emptyRequest(method: DescMethod): unknown;

package/dist/rpc.js

@@ -78,7 +78,7 @@ async function collect(stream, output, limit) {
  * no daemon behind it would answer every call with a dial error, which reads
  * to a model like a broken platform rather than an unconnected session.
  */
-export function rpcTools(opts) {
+export function rpcCatalog(opts) {
     const out = [];
     for (const entry of GENERATED_SERVICES) {
         const service = entry.service;
@@ -91,11 +91,16 @@ export function rpcTools(opts) {
         // becomes a tool, and the drift test is what says the table is stale.
         const client = createClient(service, transport);
         for (const method of service.methods) {
-            out.push(rpcTool(service, method, client, comments.get(method.localName) ?? "", opts));
+            const comment = comments.get(method.localName) ?? "";
+            out.push({ tool: rpcTool(service, method, client, comment, opts), service, method, comment });
         }
     }
     return out;
 }
+/** The same set as {@link rpcCatalog}, as bare tool definitions. */
+export function rpcTools(opts) {
+    return rpcCatalog(opts).map((e) => e.tool);
+}
 function rpcTool(service, method, client, comment, opts) {
     const contextKey = contextField(method.input);
     const streaming = method.methodKind === "client_streaming" || method.methodKind === "bidi_streaming";
@@ -134,7 +139,7 @@ async function decode(service, method, client, contextKey, streaming, args, ctx,
     const call = client[method.localName];
     if (!call)
         return failure(`${method.name} is unavailable`, `The generated client for ${service.typeName} has no ${method.localName}.`);
-    const options = { signal: ctx.signal };
+    const options = { signal: ctx.signal, ...(ctx.timeoutMs ? { timeoutMs: ctx.timeoutMs } : {}) };
     if (method.methodKind === "unary") {
         const res = await call(messages[0], options);
         return json(toJson(method.output, res));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/gibson-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Gibson MCP server: one tool surface for every coding agent host. Every RPC of every SDK service, every SDK helper and every checked-in platform tool, over stdio or streamable HTTP on localhost.",
   "license": "MIT",
   "repository": {
@@ -19,19 +19,13 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "generate": "node scripts/generate-tools.ts",
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "sh -c 'tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\"' swallow-forwarded-vitest-args"
-  },
   "dependencies": {
     "@bufbuild/protobuf": "^2.2.0",
     "@connectrpc/connect": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@zeroroot-ai/sdk": "workspace:^",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@zeroroot-ai/sdk": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -54,5 +48,11 @@
     "opencode",
     "security",
     "knowledge-graph"
-  ]
-}
+  ],
+  "scripts": {
+    "generate": "node scripts/generate-tools.ts",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "sh -c 'tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\"' swallow-forwarded-vitest-args"
+  }
+}