A person's client: the mesh's tools from a workstation

Design 25 §7's second item. Two surfaces over one thing — a command line for somebody
at a terminal, an MCP server for an agent — and both are adapters over the same three
calls: what tools are there, what does this one take, call it. A second way of reaching
a tool would be a second thing to keep correct.

It uses the client a module's runtime uses. Not a bridge and not a second protocol: a
person connects as their own bus user and publishes on the tool subjects their account
permits, so "what may this person do" is answered by the same permission list that
answers it for a module, and an audit has nothing separate to read.

`mesh tools` lists what the *catalogue* has, not what this credential may call. The two
differ and the difference is the point: somebody seeing only their own tools cannot tell
"not installed" from "not yours", and those need different people to fix them.

A failed call says which of three things happened, because the remedies are in three
different places: nobody serves that tool, this credential may not call it, or the tool
itself was slow. Without that they are one timeout and a stack trace.

The MCP surface decides nothing. The tool names are the ones a person types, the schemas
are the modules' own, and an answer is passed through unshaped — an adapter that
summarised somebody else's answer would be deciding what matters in it. A tool that fails
comes back as a tool error rather than a protocol error, because the request was
well-formed and the mesh answered it.

Written against the protocol directly: it is three methods and one framing, and a
dependency here would be a dependency on every workstation.

Tests drive both surfaces against a real bus, including that a host's notification is
answered with nothing and an unknown method is refused. They run one file at a time,
because each stands up a module serving the same tool subjects and run together their
requests get split between them — which showed up as one test reading another's answer.

src/mcp.ts

@@ -0,0 +1,139 @@
+/**
+ * The mesh's tools as an MCP server, over stdio (novox/hq design 25 §7).
+ *
+ * **A thin adapter and nothing more.** Every tool an agent sees is one the catalogue listed and one
+ * this credential may call; the schema is the module's own; the answer is the module's own. Nothing
+ * here decides anything, which is why it is short — an MCP surface that reshaped arguments or
+ * summarised answers would be a second definition of what a tool is, and the module's manifest is the
+ * first.
+ *
+ * Implemented against the protocol directly rather than through a library: the surface is three
+ * methods and one framing, and a dependency here would be a dependency on every workstation.
+ */
+import type { Broker } from "@novox/mesh-sdk/messaging";
+
+import { callTool, toolsOn, whyItFailed, type Tool } from "./client.js";
+
+/** The protocol version this speaks. Stated, because a host that wants another should be told so
+ *  rather than discovering it through a shape it did not expect. */
+const PROTOCOL = "2024-11-05";
+
+interface Request {
+  jsonrpc: string;
+  id?: number | string | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+/**
+ * Serve until stdin closes, which is how a host ends a session.
+ *
+ * The tool list is fetched once, on the first `tools/list`, and kept. An agent asks for it repeatedly
+ * and the catalogue's answer does not change mid-session; refetching would make every turn cost a
+ * round trip to a module for something nobody changed.
+ */
+export async function serveMcp(bus: Broker, who: string): Promise<void> {
+  let known: Tool[] | undefined;
+
+  const say = (message: unknown) => {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+  };
+  const answer = (id: Request["id"], result: unknown) => say({ jsonrpc: "2.0", id, result });
+  const refuse = (id: Request["id"], code: number, message: string) =>
+    say({ jsonrpc: "2.0", id, error: { code, message } });
+
+  for await (const line of lines()) {
+    let request: Request;
+    try {
+      request = JSON.parse(line) as Request;
+    } catch {
+      // Unparseable, and with no id there is nobody to tell. Skipped rather than answered, because a
+      // reply to a request that was never framed is noise on the same channel.
+      continue;
+    }
+    // A notification has no id and expects no answer; `initialized` is the one every host sends.
+    const notification = request.id === undefined || request.id === null;
+
+    switch (request.method) {
+      case "initialize":
+        answer(request.id, {
+          protocolVersion: PROTOCOL,
+          capabilities: { tools: {} },
+          serverInfo: { name: "mesh", version: "1" },
+          // Said in the handshake, because an agent that knows whose authority it is acting under can
+          // say so when a call is refused — and a refusal is the one thing here that is not the
+          // mesh's fault or the tool's.
+          instructions:
+            `These are the tools of a Novox mesh, reached as ${who}. Every call goes to the module ` +
+            `that serves it; what may be called was fixed when this credential was issued, so a ` +
+            `refusal means the credential, not the tool.`,
+        });
+        break;
+
+      case "notifications/initialized":
+        break;
+
+      case "tools/list": {
+        try {
+          known ??= await toolsOn(bus);
+        } catch (e) {
+          refuse(request.id, -32603, whyItFailed("mesh-catalog.catalog_tools", e));
+          break;
+        }
+        answer(request.id, {
+          tools: known.map((t) => ({
+            name: `${t.module}.${t.name}`,
+            description: t.description ?? `${t.name}, served by ${t.module}`,
+            // The module's own schema, passed through. An empty object is a tool that takes nothing,
+            // which is a real answer and not a missing one.
+            inputSchema: t.input ?? { type: "object", properties: {} },
+          })),
+        });
+        break;
+      }
+
+      case "tools/call": {
+        const name = String(request.params?.name ?? "");
+        const args = request.params?.arguments ?? {};
+        try {
+          const result = await callTool(bus, name, args);
+          // Text, because that is what every host renders. The content is the module's answer as
+          // JSON, unshaped: an adapter that flattened it would be deciding what matters in somebody
+          // else's answer.
+          answer(request.id, {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          });
+        } catch (e) {
+          // **An error the agent can act on, not a stack.** isError rather than a protocol failure,
+          // because the call was well-formed and the mesh answered it — with a refusal, an absence or
+          // a fault, and the words say which.
+          answer(request.id, {
+            content: [{ type: "text", text: whyItFailed(name, e) }],
+            isError: true,
+          });
+        }
+        break;
+      }
+
+      default:
+        if (!notification) {
+          refuse(request.id, -32601, `mesh's MCP surface has no ${request.method}`);
+        }
+    }
+  }
+}
+
+/** stdin as newline-framed messages, which is what MCP over stdio is. */
+async function* lines(): AsyncGenerator<string> {
+  let buffered = "";
+  for await (const chunk of process.stdin) {
+    buffered += (chunk as Buffer).toString("utf8");
+    let at: number;
+    while ((at = buffered.indexOf("\n")) >= 0) {
+      const line = buffered.slice(0, at).trim();
+      buffered = buffered.slice(at + 1);
+      if (line !== "") yield line;
+    }
+  }
+  if (buffered.trim() !== "") yield buffered.trim();
+}