@ikuma.cloud/pix-mcp 0.0.1

package/README.md

@@ -0,0 +1,175 @@
+# @ikuma.cloud/pix-mcp
+
+A small Pi MCP adapter: discover tools, load their schemas on demand, then call
+those tools natively. No scripting engine or model-provider-specific API is
+required.
+
+**Read [CONTRIBUTING.md](../../CONTRIBUTING.md) before making changes.**
+
+## Development
+
+From the repository root:
+
+```sh
+mise run mcp:dev
+mise run test --project pix-mcp
+mise run check
+```
+
+The development task runs from `packages/mcp` and disables other extensions so
+another MCP adapter cannot collide with the `mcp` tool or flags. Pass arguments
+through the task, for example:
+
+```sh
+mise run mcp:dev --mcp-config /absolute/path/to/mcp.json
+```
+
+For an existing Pi installation, load this package with
+`pi --no-extensions -e /absolute/path/to/pix/packages/mcp`.
+
+## Configuration and trust
+
+By default, read only `.mcp.json` in Pi's working directory. There is no ancestor
+search, global config merge, automatic import, or persistent metadata cache.
+Relative `--mcp-config` paths resolve from that working directory; a stdio
+server's `cwd` resolves from the config directory and defaults to that directory.
+
+A bare `.mcp.json` is not protected by Pi's project-trust mechanism. This adapter
+asks before using the default file. In a headless session, it remains disabled
+unless explicitly trusted. Either of these authorizes the file for one session:
+
+- `--mcp-config <path>`: select **and trust** a file.
+- `--mcp-trust-config`: trust the default `.mcp.json`.
+
+Review the file first: trusting it can launch arbitrary local programs and
+contact remote services. Configuration trust is not an OS sandbox.
+
+```json
+{
+  "mcpServers": {
+    "local": {
+      "command": "node",
+      "args": ["server.js"],
+      "cwd": "./service",
+      "env": { "SERVICE_TOKEN": "${SERVICE_TOKEN}" },
+      "description": "Local project documentation tools"
+    },
+    "remote": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": { "Authorization": "Bearer ${SERVICE_TOKEN}" },
+      "description": "Issue tracking tools",
+      "timeoutMs": 30000,
+      "approve": true
+    }
+  }
+}
+```
+
+Supported fields:
+
+| Field | Behavior |
+| --- | --- |
+| `type` | `stdio` or `http`; inferred from `command` or `url` when omitted |
+| `command`, `args`, `env`, `cwd` | Stdio only; executable and argument array, not a shell command |
+| `url`, `headers` | Streamable HTTP only; no SSE fallback or redirect following |
+| `description` | Optional short capability summary for discovery |
+| `timeoutMs` | Request/discovery timeout, default 30000; allowed range 100–120000 |
+| `approve` | Require confirmation for every invocation, default `true` |
+| `disabled` | Skip this server when `true` |
+
+Only `env` and `headers` values expand `${VARIABLE}` references. Missing
+variables fail without echoing their values. Stdio inherits the SDK's minimal
+platform environment plus explicit `env`, not the entire Pi environment.
+Credentials in HTTP URLs are rejected; use headers instead. Unknown fields fail
+rather than silently accepting unsupported configuration.
+
+Tool invocation requires confirmation independently of config trust. In headless
+mode, calls fail closed unless the reviewed configuration explicitly sets
+`"approve": false` for that server. Native calls still pass through Pi's normal
+tool hooks. Server annotations never grant permission. Child stderr and raw SDK
+errors are not printed because they can contain credentials; debug a failing
+server separately in a trusted environment.
+
+## Discovery and execution
+
+At session startup, the adapter connects to trusted servers and fetches their
+paginated tool catalogs. One failure does not hide tools from other servers.
+Full schemas stay out of model context until selected. **Schema exposure is lazy;
+initial connections and metadata discovery are not.**
+
+The agent uses the `mcp` tool:
+
+```js
+mcp({ action: "list", server: "local", limit: 20, offset: 0 })
+mcp({ action: "search", query: "documentation", limit: 5 })
+mcp({ action: "load", names: ["exact_name_from_discovery"] })
+```
+
+`list` returns paginated summaries without loading tools. `search` uses local,
+deterministic name/description matching and activates up to 10 matches. `load`
+activates up to 10 exact names. A result's `active` field reports whether Pi
+allowed activation. No separate describe call is required: the full tool schema
+is available on the next model request. Loading never executes the tool.
+Selection is tied to the current schema fingerprint: use `search`/`load`, not
+Pi's generic tool-name toggles, to enable a native MCP tool.
+
+Native names include a readable server/tool prefix and a deterministic hash to
+avoid normalization collisions. Independent, preapproved native calls can run
+concurrently. Calls requiring confirmation run sequentially to avoid overlapping
+approval dialogs. Discovered tools stay active until session shutdown or a server
+catalog change.
+Changed and removed definitions are withdrawn; changed tools require loading
+again. Unsupported input schemas or metadata, name collisions, and task-only
+tools are counted as `unsupportedTools` in discovery results. An unsupported
+output schema fails that server's discovery. Losing an established HTTP
+notification stream also withdraws tools rather than silently keeping a stale
+catalog; servers that decline the optional stream with HTTP 405 remain usable.
+Reload Pi to reconnect a failed server or reread configuration.
+
+Pi handles provider compatibility. Some providers support transcript-anchored
+schema additions; others rebuild the tool set and may invalidate prompt caches.
+For very small catalogs, eager loading would avoid a discovery round trip, but
+v1 intentionally offers only the deferred mode.
+
+## Output and limits
+
+Text, supported images, and structured content are retained. Long text gets a
+24 KiB / 1000-line preview; structured details are bounded to 16 KiB. At most four
+PNG/JPEG/GIF/WebP images of up to 4 MiB each are shown. Unsupported or oversized
+content is explicitly omitted from the preview, not silently discarded. Pi's
+error-result path is text-only, so images in MCP errors are preserved in a
+full-result artifact rather than displayed inline.
+
+When necessary, the full MCP result is written to `pix-mcp-*/result.json` under
+the system temp directory (directory mode 0700, file mode 0600). Pi can inspect it
+with `read`. These artifacts may contain sensitive data and are **not deleted at
+session shutdown**; remove them when no longer needed. Output limits are not a
+complete memory or security sandbox.
+
+Configuration is limited to 256 KiB and 32 servers. Startup connects at most four
+servers concurrently. Each catalog is limited to 1000 tools, 100 pagination
+cursors, and 2 MiB of metadata; individual input/output schemas are limited to
+64 KiB. Tool names must use 1–128 ASCII letters, digits, underscores, hyphens, or
+periods; descriptions are limited to 16 KiB. Stdio messages are limited to 16 MiB.
+Schemas are syntax-checked before compilation. Only the default MCP dialect,
+JSON Schema 2020-12, is supported; explicit legacy dialects (including embedded
+resources) are rejected rather than interpreted with incorrect reference
+semantics. External schema references are unsupported, but literal `$ref` fields
+inside instance data are allowed. Requests and the entire initialization
+handshake use fixed deadlines, not progress-extended timeouts.
+
+The adapter never automatically retries `tools/call`: a timeout or lost response
+may occur after a mutating operation took effect. Successful output is validated
+against the schema captured when the call began; MCP error results are exempt
+from that success schema. Cancellation is best-effort at the server and does not
+roll back effects.
+
+## Deliberately out of scope
+
+OAuth, legacy SSE transport, MCP prompts/resources APIs, sampling, elicitation,
+MCP apps, task execution, semantic search, scripting, config UI, and persistent
+catalog caching. Use a fuller adapter when those capabilities are required.
+
+Tests use local stdio/HTTP fixture servers and isolated Pi configuration, without
+model requests or personal credentials.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ikuma.cloud/pix-mcp",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "MCP discovery and lazily activated native tools for Pi Coding Agent",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/fixtures"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "ajv": "8.20.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "typebox": "1.3.27"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+
+export interface Entry {
+  name: string;
+  server: string;
+  tool: Tool;
+  fingerprint: string;
+}
+
+export function toolName(server: string, original: string): string {
+  const suffix = createHash("sha256")
+    .update(JSON.stringify([server, original]))
+    .digest("hex")
+    .slice(0, 12);
+  const readable = `${server}_${original}`
+    .replace(/[^A-Za-z0-9_]/g, "_")
+    .slice(0, 47);
+  return `mcp_${readable}_${suffix}`;
+}
+
+export function entry(server: string, tool: Tool): Entry {
+  return {
+    name: toolName(server, tool.name),
+    server,
+    tool,
+    fingerprint: createHash("sha256")
+      .update(JSON.stringify(tool))
+      .digest("hex"),
+  };
+}
+
+export function search(
+  entries: Entry[],
+  query: string,
+  server?: string,
+): Entry[] {
+  const words = [
+    ...new Set(
+      query
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}_-]+/u)
+        .filter(Boolean),
+    ),
+  ];
+  if (!words.length) return [];
+  return entries
+    .filter((item) => !server || item.server === server)
+    .map((item) => {
+      const name =
+        `${item.server} ${item.tool.name} ${item.name}`.toLowerCase();
+      const description = (item.tool.description ?? "").toLowerCase();
+      const score = words.reduce(
+        (sum, word) =>
+          sum +
+          (name.includes(word) ? 4 : 0) +
+          (description.includes(word) ? 1 : 0),
+        0,
+      );
+      return { item, score };
+    })
+    .filter((match) => match.score > 0)
+    .sort(
+      (a, b) =>
+        b.score - a.score || a.item.name.localeCompare(b.item.name, "en"),
+    )
+    .map((match) => match.item);
+}
+
+export function summary(item: Entry) {
+  return {
+    name: item.name,
+    server: item.server,
+    tool: item.tool.name,
+    description: compact(item.tool.description ?? "", 200),
+  };
+}
+
+export function compact(value: string, limit: number): string {
+  const text = value
+    .replace(/\p{Cc}/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text.length <= limit ? text : `${text.slice(0, limit)}…`;
+}

package/src/client.ts

@@ -0,0 +1,343 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { mediaTypeEssence } from "@modelcontextprotocol/sdk/shared/mediaType.js";
+import {
+  CallToolResultSchema,
+  ListToolsResultSchema,
+  ToolSchema,
+  ToolListChangedNotificationSchema,
+  type Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { ServerConfig } from "./config.ts";
+import { compileSchema, schemaValidator } from "./schema.ts";
+
+// SDK 1.30's property decoder incorrectly requires every property schema to be
+// an object. JSON Schema 2020-12 also permits true/false. Preserve those values
+// through the wire decoder; our meta-schema checks validate their actual syntax.
+const catalogResultSchema = ListToolsResultSchema.extend({
+  tools: ToolSchema.extend({
+    inputSchema: ToolSchema.shape.inputSchema.omit({ properties: true }),
+    outputSchema: ToolSchema.shape.outputSchema
+      .unwrap()
+      .omit({ properties: true })
+      .optional(),
+  }).array(),
+});
+
+export class Connection {
+  readonly client: Client;
+  readonly config: ServerConfig;
+  status = "Not connected";
+  instructions = "";
+  #transport: StdioClientTransport | StreamableHTTPClientTransport;
+  #lifetime = new AbortController();
+  #initializing: Promise<void> | undefined;
+  #refreshing: Promise<void> | undefined;
+  #closing: Promise<void> | undefined;
+  #dirty = false;
+  #stopped = false;
+  #changed: (tools: Tool[]) => void;
+  #outputValidators = new Map<string, ReturnType<typeof compileSchema>>();
+
+  constructor(config: ServerConfig, changed: (tools: Tool[]) => void) {
+    this.config = config;
+    this.#changed = changed;
+    this.client = new Client(
+      { name: "pix-mcp", version: "0.0.0" },
+      { capabilities: {}, jsonSchemaValidator: schemaValidator },
+    );
+    this.#transport =
+      config.type === "stdio"
+        ? new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            cwd: config.cwd,
+            env: config.env,
+            stderr: "ignore",
+            maxBufferSize: 16 * 1024 * 1024,
+          })
+        : new StreamableHTTPClientTransport(new URL(config.url), {
+            requestInit: { headers: config.headers, redirect: "error" },
+            reconnectionOptions: {
+              maxRetries: 0,
+              initialReconnectionDelay: 1000,
+              maxReconnectionDelay: 1000,
+              reconnectionDelayGrowFactor: 1,
+            },
+            fetch: (url, init) => this.#fetch(url, init),
+          });
+    this.client.onerror = () => {
+      /* Request failures are reported without leaking SDK error payloads. */
+    };
+    this.client.onclose = () => this.#disconnect();
+    this.client.setNotificationHandler(
+      ToolListChangedNotificationSchema,
+      async () => {
+        if (this.#stopped) return;
+        try {
+          await this.refresh();
+        } catch {
+          /* refresh already clears the stale catalog */
+        }
+      },
+    );
+  }
+
+  #disconnect() {
+    if (this.#stopped || this.#lifetime.signal.aborted) return;
+    this.status = "Disconnected; reload Pi to reconnect";
+    this.#lifetime.abort(
+      new Error("MCP connection is unavailable; reload Pi to reconnect."),
+    );
+    this.#outputValidators.clear();
+    this.#changed([]);
+    void this.client.close().catch(() => {});
+  }
+
+  async #fetch(
+    url: Parameters<typeof fetch>[0],
+    init: Parameters<typeof fetch>[1],
+  ) {
+    // Teardown must still send DELETE after the connection lifetime is aborted.
+    if (init?.method === "DELETE")
+      return globalThis.fetch(url, {
+        ...init,
+        redirect: "error",
+        signal: AbortSignal.timeout(2000),
+      });
+    const signals = [
+      this.#lifetime.signal,
+      ...(init?.signal ? [init.signal] : []),
+    ];
+    if (init?.method !== "GET") {
+      return globalThis.fetch(url, {
+        ...init,
+        redirect: "error",
+        signal: AbortSignal.any([
+          ...signals,
+          AbortSignal.timeout(this.config.timeoutMs),
+        ]),
+      });
+    }
+    // GET is optional (405 is valid), but an established notification stream
+    // cannot disappear silently: with retries disabled its catalog is stale.
+    const headersDeadline = new AbortController();
+    const timer = setTimeout(
+      () => headersDeadline.abort(),
+      this.config.timeoutMs,
+    );
+    try {
+      const response = await globalThis.fetch(url, {
+        ...init,
+        redirect: "error",
+        signal: AbortSignal.any([...signals, headersDeadline.signal]),
+      });
+      if (response.status === 405) return response;
+      if (
+        !response.ok ||
+        !response.body ||
+        mediaTypeEssence(response.headers.get("content-type")) !==
+          "text/event-stream"
+      ) {
+        await response.body?.cancel();
+        throw new Error("MCP notification stream unavailable.");
+      }
+      const stream = new TransformStream<Uint8Array, Uint8Array>();
+      void response.body.pipeTo(stream.writable).then(
+        () => this.#disconnect(),
+        () => this.#disconnect(),
+      );
+      return new Response(stream.readable, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    } catch (error) {
+      this.#disconnect();
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  start(): Promise<void> {
+    this.#initializing ??= this.#start();
+    return this.#initializing;
+  }
+
+  async #start(): Promise<void> {
+    try {
+      this.#lifetime.signal.throwIfAborted();
+      this.status = "Connecting";
+      // SDK transport getters include undefined while its optional Transport field
+      // does not under exactOptionalPropertyTypes; the runtime contract is identical.
+      // SDK request timeouts do not cover the awaited notifications/initialized
+      // send. Bound the whole handshake and close the transport to release it.
+      const handshakeTimer = setTimeout(
+        () => this.#disconnect(),
+        this.config.timeoutMs,
+      );
+      try {
+        await this.client.connect(this.#transport as Transport, {
+          signal: this.#lifetime.signal,
+          timeout: this.config.timeoutMs,
+        });
+      } finally {
+        clearTimeout(handshakeTimer);
+      }
+      this.#lifetime.signal.throwIfAborted();
+      this.instructions = this.client.getInstructions() ?? "";
+      await this.refresh();
+    } catch {
+      if (!this.#stopped) {
+        this.status =
+          "Connection or discovery failed; check configuration/authentication and reload Pi";
+        this.#changed([]);
+      }
+      await this.client.close().catch(() => {});
+      throw new Error(
+        `MCP server ${this.config.name}: connection or discovery failed.`,
+      );
+    }
+  }
+
+  refresh(): Promise<void> {
+    this.#dirty = true;
+    this.#refreshing ??= this.#refresh().finally(() => {
+      this.#refreshing = undefined;
+    });
+    return this.#refreshing;
+  }
+
+  async #refresh(): Promise<void> {
+    try {
+      while (this.#dirty && !this.#stopped) {
+        this.#dirty = false;
+        const tools: Tool[] = [];
+        const cursors = new Set<string>();
+        const names = new Set<string>();
+        let cursor: string | undefined;
+        let bytes = 0;
+        const signal = AbortSignal.any([
+          this.#lifetime.signal,
+          AbortSignal.timeout(this.config.timeoutMs),
+        ]);
+        if (this.client.getServerCapabilities()?.tools) {
+          do {
+            const page = await this.client.request(
+              {
+                method: "tools/list",
+                params: cursor === undefined ? {} : { cursor },
+              },
+              catalogResultSchema,
+              {
+                signal,
+                timeout: this.config.timeoutMs,
+              },
+            );
+            bytes += Buffer.byteLength(JSON.stringify(page));
+            if (
+              bytes > 2 * 1024 * 1024 ||
+              tools.length + page.tools.length > 1000
+            )
+              throw new Error("Catalog limit");
+            for (const tool of page.tools) {
+              if (names.has(tool.name)) throw new Error("Duplicate tool name");
+              names.add(tool.name);
+              tools.push(tool);
+            }
+            cursor = page.nextCursor;
+            if (cursor !== undefined) {
+              if (cursors.has(cursor) || cursors.size >= 100)
+                throw new Error("Invalid pagination");
+              cursors.add(cursor);
+            }
+          } while (cursor !== undefined);
+        }
+        // Keep a complete, atomic validator snapshot rather than the SDK's
+        // per-page mutable cache, including when a catalog changes during a call.
+        const validators = new Map<string, ReturnType<typeof compileSchema>>();
+        for (const tool of tools) {
+          if (tool.outputSchema)
+            validators.set(tool.name, compileSchema(tool.outputSchema));
+        }
+        signal.throwIfAborted();
+        if (!this.#stopped) {
+          this.#outputValidators = validators;
+          this.status = "Connected";
+          this.#changed(tools);
+        }
+      }
+    } catch {
+      if (!this.#stopped) {
+        this.status = "Discovery failed; reload Pi to retry";
+        this.#changed([]);
+      }
+      throw new Error(`MCP server ${this.config.name}: discovery failed.`);
+    }
+  }
+
+  async call(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ) {
+    await this.start();
+    const combined = signal
+      ? AbortSignal.any([signal, this.#lifetime.signal])
+      : this.#lifetime.signal;
+    combined.throwIfAborted();
+    const outputValidator = this.#outputValidators.get(name);
+    try {
+      // SDK callTool consults a mutable per-page validator after the response and
+      // validates error payloads against success schemas. Use one typed request,
+      // then our captured validator; task-only tools are excluded during discovery.
+      // Never retry: a lost response does not prove the operation did not run.
+      const result = await this.client.request(
+        { method: "tools/call", params: { name, arguments: args } },
+        CallToolResultSchema,
+        {
+          signal: combined,
+          timeout: this.config.timeoutMs,
+          resetTimeoutOnProgress: false,
+        },
+      );
+      const parsed = CallToolResultSchema.parse(result);
+      if (
+        !parsed.isError &&
+        outputValidator &&
+        !outputValidator.Check(parsed.structuredContent)
+      ) {
+        throw new Error("MCP output does not match the advertised schema.");
+      }
+      return parsed;
+    } catch {
+      combined.throwIfAborted();
+      throw new Error(
+        `MCP server ${this.config.name}: call failed or timed out. It may already have taken effect; do not retry blindly.`,
+      );
+    }
+  }
+
+  close(): Promise<void> {
+    this.#closing ??= this.#close();
+    return this.#closing;
+  }
+
+  async #close(): Promise<void> {
+    this.#stopped = true;
+    this.#lifetime.abort();
+    this.status = "Closed";
+    if (
+      this.#transport instanceof StreamableHTTPClientTransport &&
+      this.#transport.sessionId
+    ) {
+      await this.#transport.terminateSession().catch(() => {});
+    }
+    await this.client.close().catch(() => {});
+    await this.#initializing?.catch(() => {});
+    await this.#refreshing?.catch(() => {});
+  }
+}