@adaptivemcp/mcp-binary 0.1.1

package/README.md

@@ -0,0 +1,143 @@
+# @adaptivemcp/mcp-binary
+
+The **only sanctioned shell-out layer** in Adaptive MCP (see `docs/doubts.md` §12b / D10).
+
+It wraps a CLI binary into an MCP stdio server, mapping the binary's CLI onto
+MCP tools. Binaries like **rtk** (which has no native MCP server) become
+chainable MCP servers this way, then attach to `@adaptivemcp/middleware` like
+any other integration — instead of living at the host layer or shelling out
+inside core.
+
+```ts
+import { createRtkWrapper } from "@adaptivemcp/mcp-binary";
+
+const rtk = createRtkWrapper(); // resolves the user's existing rtk install
+if (rtk.available) {
+  await rtk.start(); // stdio MCP server exposing `rtk_exec`
+}
+```
+
+## What "MCP chaining" means here
+
+Adaptive MCP does **not** chain binaries. It chains **MCP servers**.
+
+- Each MCP server (yours, headroom's, rtk's wrapper) is a first-class node in a
+  `MiddlewareChain`.
+- A middleware runs `beforeCall` / `afterCall` around a tool invocation. The
+  `afterCall` of one middleware sees the output produced by the previous one.
+- The binary wrapper is just *one* node: it turns a CLI subprocess into an MCP
+  tool so it can participate in the chain. The chain itself is protocol-level,
+  not process-level.
+
+So when you add rtk to the chain, you are not injecting rtk into every other
+tool. You are adding a middleware that, for the tools you route through it, runs
+a command via rtk and compresses the result. Other MCP tools are untouched
+unless you explicitly route them through the rtk middleware.
+
+## When / how rtk and headroom run
+
+| | headroom | rtk (via this wrapper) |
+| --- | --- | --- |
+| Native MCP server? | Yes | No — wrapped here |
+| Runs as | MCP server in the chain | CLI subprocess spawned by the wrapper |
+| Trigger | `afterCall` compresses a tool's string output | `rtk_exec` tool runs a command through `rtk gain` |
+| Effect on other tools | Only tools routed through the headroom middleware | Only tools routed through the rtk middleware |
+| Telemetry | `headroom` view in `tools-metadata.yaml` | `rtk_exec` calls recorded like any MCP call |
+
+**headroom** is a normal MCP server. Its `HeadroomMiddleware.afterCall` runs
+after a tool returns and compresses the string output (D9: passthrough on
+failure). It never spawns a process.
+
+**rtk** has no MCP server, so `createRtkWrapper()` wraps the `rtk` CLI into one.
+The wrapper exposes a single `rtk_exec` tool. When a tool in the chain calls
+`rtk_exec`, the wrapper spawns `rtk gain <command>`, captures stdout, and
+returns it. That is the *only* place in Adaptive MCP that spawns a process.
+
+## Layering: this wrapper is NOT the rtk hook
+
+rtk's own value comes from its **PreToolUse hook** (installed by `rtk init -g`),
+which rewrites an agent's Bash calls (`git status` → `rtk git status`) *before*
+they execute. That hook operates at the **agent's shell layer**.
+
+This MCP wrapper is a **different layer**: it runs rtk as a normal CLI
+subprocess *inside the Adaptive MCP middleware chain*, compressing the output of
+a tool call that already returned.
+
+```
+Agent Bash layer:   rtk hook rewrites `git status` → `rtk git status`   (rtk's own feature)
+        │
+        ▼
+MCP tool-output layer:  tool returns → rtk_exec middleware → `rtk gain` → compressed result
+```
+
+The two **compose** rather than conflict: the hook compresses what the agent
+sends to the shell; this wrapper compresses what a tool's MCP result carries
+back. Adaptive MCP does not install, enable, or disable the rtk hook — it only
+reuses the rtk binary if it is already present.
+
+## Graceful coexistence when rtk is already installed
+
+If you already use rtk, Adaptive MCP is **not a nuisance** to your other MCPs:
+
+1. **We reuse your install.** `resolveRtkCommand()` looks up your existing `rtk`
+   on `PATH` (or an explicit `command` path). We never download or install a
+   second copy, and we never touch your shell config or hook.
+2. **We verify it's the right package.** A name collision exists: the Rust
+   *Type Kit* crate on crates.io is also called `rtk`. `resolveRtkCommand()`
+   probes `rtk --version` and only accepts a binary that prints `rtk <semver>`
+   (rtk-ai). If the `rtk` on `PATH` is the wrong package, the wrapper reports
+   `wrong-package` and degrades gracefully instead of silently misbehaving.
+3. **We degrade, not crash.** If rtk is missing (or the wrong package), the
+   wrapper still constructs and registers its tools, but each `rtk_exec` call
+   returns a clear setup message (`isError: true`) instead of spawning a missing
+   binary. Check `server.available` to know the state up front.
+4. **No double-compression surprise.** Because the hook and the wrapper are on
+   different layers, routing a tool through `rtk_exec` does not "double up" with
+   the hook — the hook affects what the agent runs in the shell; the wrapper
+   affects what a tool's MCP result carries back. They are independent knobs.
+
+```ts
+import { createRtkWrapper, resolveRtkCommand } from "@adaptivemcp/mcp-binary";
+
+const resolution = resolveRtkCommand(); // { status: "found" | "missing" | "wrong-package" }
+const rtk = createRtkWrapper();        // uses the resolved command automatically
+
+if (!rtk.available) {
+  // resolution.detail explains why (missing, or wrong `rtk` package on PATH)
+  console.warn(resolution.detail);
+}
+```
+
+## Telemetry integration
+
+Every MCP call — including `rtk_exec` and headroom-compressed results — flows
+through the same pipeline as any other tool:
+
+```
+tool call → TelemetryRecorder → MemoryStore (SQLite)
+          → Evaluator (insights) → ExtensionController
+          → tools-metadata.yaml (dev.adaptivemcp/tools-metadata)
+```
+
+`AdaptiveRuntime.observeCompleted(output)` accepts the (possibly compressed)
+`output` and folds it into `ToolStats`. `MiddlewareChain.contributeView()`
+surfaces per-middleware state under the `middleware:` map in
+`tools-metadata.yaml` — e.g. `middleware: { headroom: { hash, savingsPercent } }`.
+rtk's *own* opt-in telemetry (GDPR-gated, off by default) is separate and
+untouched; Adaptive MCP only records the MCP-level calls it makes.
+
+## API
+
+- `createRtkWrapper(options?: RtkWrapperOptions): BinaryMcpServer` — wraps the
+  rtk CLI. `options.command` overrides discovery; `options.timeoutMs` bounds
+  each spawn; `options.version` sets the advertised server version.
+- `resolveRtkCommand(command?: string): RtkResolution` — locates and verifies a
+  usable rtk-ai binary. Returns `{ status, command?, detail? }`.
+- `BinaryMcpServer` — generic CLI→MCP wrapper. `available` getter, `name` /
+  `version` getters, `toolNames()`, `start()`, `close()`.
+- `RTK_TOOLS` — the reference `BinaryToolSpec[]` (`rtk_exec` → `rtk gain`).
+
+> **Secure by default.** Discovery is read-only: it probes `rtk --version` and
+> never writes to the filesystem, mutates `PATH`, or installs software. If you
+> need rtk, install it yourself from <https://rtk-ai.app> (Homebrew, the official
+> checksum-hardened installer, or `cargo install`).

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @adaptivemcp/mcp-binary
+ *
+ * The **only** sanctioned shell-out layer in Adaptive MCP (doubts.md §12b / D10).
+ *
+ * It wraps a CLI binary into an MCP stdio server, mapping the binary's CLI onto
+ * MCP tools. Binaries like **rtk** (which has no native MCP server) become
+ * chainable MCP servers this way, then attach to `@adaptivemcp/middleware` like
+ * any other integration — instead of living at the host layer or shelling out
+ * inside core. `RtkWrapper` is the reference binary config.
+ */
+export { BinaryMcpServer } from "./server.js";
+export type { BinaryMcpServerOptions, BinaryToolSpec } from "./server.js";
+export { createRtkWrapper, RTK_TOOLS, resolveRtkCommand } from "./rtk.js";
+export type { RtkWrapperOptions, RtkResolution } from "./rtk.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC1E,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @adaptivemcp/mcp-binary
+ *
+ * The **only** sanctioned shell-out layer in Adaptive MCP (doubts.md §12b / D10).
+ *
+ * It wraps a CLI binary into an MCP stdio server, mapping the binary's CLI onto
+ * MCP tools. Binaries like **rtk** (which has no native MCP server) become
+ * chainable MCP servers this way, then attach to `@adaptivemcp/middleware` like
+ * any other integration — instead of living at the host layer or shelling out
+ * inside core. `RtkWrapper` is the reference binary config.
+ */
+export { BinaryMcpServer } from "./server.js";
+export { createRtkWrapper, RTK_TOOLS, resolveRtkCommand } from "./rtk.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/rtk.d.ts

@@ -0,0 +1,78 @@
+import { BinaryMcpServer, type BinaryToolSpec } from "./server.js";
+/**
+ * Reference binary config for **rtk** (rtk-ai.app).
+ *
+ * rtk has no native MCP server (doubts.md §12b, issue #1442 is "gauging
+ * interest" only), so it is wrapped here into an MCP server. The wrapper exposes
+ * a single `rtk_exec` tool that runs an arbitrary shell command through rtk's
+ * output compression. Once rtk ships a native MCP server, this wrapper becomes
+ * redundant and rtk can be chained directly like headroom.
+ *
+ * **Layering — this is NOT the rtk hook.** rtk's own value comes from its
+ * PreToolUse hook (installed by `rtk init -g`), which rewrites an agent's Bash
+ * calls (`git status` → `rtk git status`) *before* they execute. That hook
+ * operates at the agent's shell layer. This MCP wrapper is a *different* layer:
+ * it runs rtk as a normal CLI subprocess inside the Adaptive MCP middleware
+ * chain, compressing the output of a tool call that already returned. The two
+ * compose — the hook compresses what the agent sends to the shell, this wrapper
+ * compresses what a tool's MCP result carries back. See `docs/doubts.md` §12b.
+ */
+export declare const RTK_TOOLS: BinaryToolSpec[];
+export interface RtkWrapperOptions {
+    /**
+     * Path or name of the rtk binary. Defaults to `"rtk"`.
+     *
+     * If omitted, `resolveRtkCommand()` is used to locate the user's existing
+     * install (graceful coexistence — we prefer the binary the user already has
+     * and configured over bundling or re-installing one).
+     */
+    command?: string;
+    version?: string;
+    timeoutMs?: number;
+}
+/**
+ * The result of locating the rtk binary on the host.
+ *
+ * `status` tells the caller how to behave:
+ *  - `"found"`: a working rtk-ai binary is available — wrap it directly.
+ *  - `"missing"`: no rtk on PATH — the caller should degrade gracefully
+ *    (e.g. skip the rtk middleware, or surface a setup hint) rather than
+ *    spawn a binary that does not exist.
+ *  - `"wrong-package"`: a binary named `rtk` exists but it is the unrelated
+ *    Rust *Type Kit* crate from crates.io (its `rtk gain` fails). The caller
+ *    must NOT treat this as rtk-ai; it should warn and skip.
+ */
+export interface RtkResolution {
+    status: "found" | "missing" | "wrong-package";
+    /** The command/path to use, when `status === "found"`. */
+    command?: string;
+    /** Human-readable detail for logs / `contributeView`. */
+    detail?: string;
+}
+/**
+ * Locate a usable rtk-ai binary on the host.
+ *
+ * 1. If `command` is an absolute/relative path, verify it exists and that
+ *    `rtk --version` reports an `rtk <semver>` line (the rtk-ai binary),
+ *    not the Rust Type Kit crate.
+ * 2. Otherwise search `PATH` for `rtk`, then probe it the same way.
+ *
+ * This is the sanctioned, read-only discovery step. It never downloads or
+ * installs anything — Adaptive MCP must not mutate the host's toolchain. If the
+ * user already has rtk (from Homebrew, the official installer, or cargo), we
+ * reuse it; if not, we report `missing` and let the caller degrade.
+ */
+export declare function resolveRtkCommand(command?: string): RtkResolution;
+/**
+ * Build an `BinaryMcpServer` that wraps the rtk CLI. This is the sanctioned
+ * shell-out layer (D4/D10): rtk becomes a chainable MCP server instead of
+ * living at the host layer or shelling out inside core.
+ *
+ * Discovery is graceful: when `command` is omitted we resolve the user's
+ * existing rtk install via `resolveRtkCommand()`. If none is found (or the
+ * `rtk` name collides with another package), the returned server is marked
+ * `unavailable` and its `rtk_exec` tool will report a clear setup message
+ * instead of spawning a missing binary. Call `server.available` to check.
+ */
+export declare function createRtkWrapper(options?: RtkWrapperOptions): BinaryMcpServer;
+//# sourceMappingURL=rtk.d.ts.map

package/dist/rtk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rtk.d.ts","sourceRoot":"","sources":["../src/rtk.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAA+B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS,EAAE,cAAc,EAWrC,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,eAAe,CAAC;IAC9C,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAoCjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,eAAe,CAWjF"}

package/dist/rtk.js

@@ -0,0 +1,107 @@
+import { execFileSync } from "node:child_process";
+import { z } from "zod";
+import { BinaryMcpServer } from "./server.js";
+/**
+ * Reference binary config for **rtk** (rtk-ai.app).
+ *
+ * rtk has no native MCP server (doubts.md §12b, issue #1442 is "gauging
+ * interest" only), so it is wrapped here into an MCP server. The wrapper exposes
+ * a single `rtk_exec` tool that runs an arbitrary shell command through rtk's
+ * output compression. Once rtk ships a native MCP server, this wrapper becomes
+ * redundant and rtk can be chained directly like headroom.
+ *
+ * **Layering — this is NOT the rtk hook.** rtk's own value comes from its
+ * PreToolUse hook (installed by `rtk init -g`), which rewrites an agent's Bash
+ * calls (`git status` → `rtk git status`) *before* they execute. That hook
+ * operates at the agent's shell layer. This MCP wrapper is a *different* layer:
+ * it runs rtk as a normal CLI subprocess inside the Adaptive MCP middleware
+ * chain, compressing the output of a tool call that already returned. The two
+ * compose — the hook compresses what the agent sends to the shell, this wrapper
+ * compresses what a tool's MCP result carries back. See `docs/doubts.md` §12b.
+ */
+export const RTK_TOOLS = [
+    {
+        name: "rtk_exec",
+        description: "Run a shell command through rtk's CLI-output compression. Returns the compressed command output.",
+        subcommand: "gain",
+        inputSchema: {
+            command: z.string().describe("The shell command to run and compress."),
+        },
+        argStyle: "positionals",
+    },
+];
+/**
+ * Locate a usable rtk-ai binary on the host.
+ *
+ * 1. If `command` is an absolute/relative path, verify it exists and that
+ *    `rtk --version` reports an `rtk <semver>` line (the rtk-ai binary),
+ *    not the Rust Type Kit crate.
+ * 2. Otherwise search `PATH` for `rtk`, then probe it the same way.
+ *
+ * This is the sanctioned, read-only discovery step. It never downloads or
+ * installs anything — Adaptive MCP must not mutate the host's toolchain. If the
+ * user already has rtk (from Homebrew, the official installer, or cargo), we
+ * reuse it; if not, we report `missing` and let the caller degrade.
+ */
+export function resolveRtkCommand(command) {
+    const candidates = command ? [command] : ["rtk"];
+    for (const candidate of candidates) {
+        // Probe: rtk-ai prints "rtk <version>"; the Rust Type Kit crate does not.
+        // `execFileSync` resolves PATH names itself, so a bare "rtk" works.
+        try {
+            const out = execFileSync(candidate, ["--version"], {
+                encoding: "utf8",
+                timeout: 5000,
+                windowsHide: true,
+            });
+            if (/^rtk\s+\d+\.\d+/.test(out.trim())) {
+                return { status: "found", command: candidate, detail: out.trim() };
+            }
+            // A binary named `rtk` exists but is not rtk-ai (name collision).
+            return {
+                status: "wrong-package",
+                detail: `Found a binary named 'rtk' at ${candidate}, but it is not rtk-ai (its --version is "${out.trim()}"). This is likely the unrelated Rust 'Type Kit' crate. Install rtk-ai from https://rtk-ai.app instead.`,
+            };
+        }
+        catch {
+            // Probe failed: not on PATH, not executable, or the wrong package that
+            // errors on --version. If an explicit path was given, report it as a
+            // collision; otherwise keep looking (PATH name collision).
+            if (command) {
+                return {
+                    status: "wrong-package",
+                    detail: `The binary at '${command}' did not respond to 'rtk --version' like rtk-ai. Verify it is the rtk-ai binary (https://rtk-ai.app).`,
+                };
+            }
+            continue;
+        }
+    }
+    return {
+        status: "missing",
+        detail: "rtk-ai not found on PATH. Install it from https://rtk-ai.app (or set RtkWrapperOptions.command to an explicit path). The rtk middleware will be skipped.",
+    };
+}
+/**
+ * Build an `BinaryMcpServer` that wraps the rtk CLI. This is the sanctioned
+ * shell-out layer (D4/D10): rtk becomes a chainable MCP server instead of
+ * living at the host layer or shelling out inside core.
+ *
+ * Discovery is graceful: when `command` is omitted we resolve the user's
+ * existing rtk install via `resolveRtkCommand()`. If none is found (or the
+ * `rtk` name collides with another package), the returned server is marked
+ * `unavailable` and its `rtk_exec` tool will report a clear setup message
+ * instead of spawning a missing binary. Call `server.available` to check.
+ */
+export function createRtkWrapper(options = {}) {
+    const resolution = resolveRtkCommand(options.command);
+    const opts = {
+        name: "adaptive-rtk-wrapper",
+        version: options.version ?? "0.1.0",
+        command: resolution.command ?? "rtk",
+        tools: RTK_TOOLS,
+        timeoutMs: options.timeoutMs,
+        unavailable: resolution.status !== "found" ? resolution.detail : undefined,
+    };
+    return new BinaryMcpServer(opts);
+}
+//# sourceMappingURL=rtk.js.map

package/dist/rtk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rtk.js","sourceRoot":"","sources":["../src/rtk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAoD,MAAM,aAAa,CAAC;AAEhG;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,kGAAkG;QACpG,UAAU,EAAE,MAAM;QAClB,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;SACvE;QACD,QAAQ,EAAE,aAAa;KACxB;CACF,CAAC;AAmCF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,0EAA0E;QAC1E,oEAAoE;QACpE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,EAAE;gBACjD,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,IAAI;gBACb,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;YACH,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;YACrE,CAAC;YACD,kEAAkE;YAClE,OAAO;gBACL,MAAM,EAAE,eAAe;gBACvB,MAAM,EAAE,iCAAiC,SAAS,6CAA6C,GAAG,CAAC,IAAI,EAAE,yGAAyG;aACnN,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,qEAAqE;YACrE,2DAA2D;YAC3D,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO;oBACL,MAAM,EAAE,eAAe;oBACvB,MAAM,EAAE,kBAAkB,OAAO,wGAAwG;iBAC1I,CAAC;YACJ,CAAC;YACD,SAAS;QACX,CAAC;IACH,CAAC;IACD,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,0JAA0J;KACnK,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA6B,EAAE;IAC9D,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,IAAI,GAA2B;QACnC,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,OAAO;QACnC,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,KAAK;QACpC,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,WAAW,EAAE,UAAU,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;KAC3E,CAAC;IACF,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * A single CLI subcommand exposed as an MCP tool.
+ *
+ * The wrapper shells out to `<command> <subcommand> [args...]` and returns the
+ * combined stdout/stderr as the tool result. This is the **only** place in
+ * Adaptive MCP permitted to spawn processes (doubts.md §12b / D10) — it is the
+ * sanctioned shell-out layer that lets binaries like rtk become chainable MCP
+ * servers instead of living at the host layer or shelling out inside core.
+ */
+export interface BinaryToolSpec {
+    /** MCP tool name, e.g. `rtk_exec`. */
+    name: string;
+    /** Human description shown in `tools/list`. */
+    description: string;
+    /** The subcommand passed to the binary (e.g. `gain`, `compress`). */
+    subcommand: string;
+    /**
+     * Zod-validated input schema for the tool. The parsed args are forwarded to
+     * the binary as CLI flags/positionals. Use `argStyle` to control formatting.
+     */
+    inputSchema: z.ZodRawShape;
+    /** How to render parsed args on the command line. Defaults to `--key value`. */
+    argStyle?: "flags" | "positionals";
+}
+export interface BinaryMcpServerOptions {
+    /** Server identity advertised in `initialize`. */
+    name: string;
+    version?: string;
+    /** The binary to invoke, e.g. `"rtk"` or `"/usr/local/bin/rtk"`. */
+    command: string;
+    /** Base args always prepended (e.g. `["--json"]`). */
+    baseArgs?: string[];
+    /** Tools to expose. */
+    tools: BinaryToolSpec[];
+    /** Shell out timeout in ms (per invocation). Defaults to 30s. */
+    timeoutMs?: number;
+    /**
+     * When set, the binary could not be located/verified (e.g. rtk not installed,
+     * or the `rtk` name collides with another package). The server still registers
+     * its tools, but each invocation returns this message instead of spawning a
+     * missing binary. Lets the chain degrade gracefully rather than erroring.
+     */
+    unavailable?: string;
+}
+/**
+ * Wraps a CLI binary into an MCP stdio server. Each `BinaryToolSpec` becomes an
+ * MCP tool that runs `<command> <subcommand> <args>` and returns the output.
+ *
+ * This is intentionally generic (D10): rtk is the reference binary, but any
+ * CLI tool whose output benefits from in-loop transformation can be wrapped the
+ * same way and then chained through `@adaptivemcp/middleware`.
+ */
+export declare class BinaryMcpServer {
+    private server;
+    private opts;
+    constructor(options: BinaryMcpServerOptions);
+    private registerTool;
+    /** Whether the wrapped binary was located and verified at construction. */
+    get available(): boolean;
+    /** Server identity advertised in `initialize`. */
+    get name(): string;
+    /** Server version advertised in `initialize`. */
+    get version(): string;
+    /** Names of the tools registered on this server. */
+    toolNames(): string[];
+    /** Spawn the binary, write `input` (if any) to stdin, resolve with stdout. */
+    private run;
+    private renderArgs;
+    /** Attach to stdio and start listening. */
+    start(): Promise<void>;
+    /** Stop the server. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,uBAAuB;IACvB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,IAAI,CAAyB;gBAEzB,OAAO,EAAE,sBAAsB;IAW3C,OAAO,CAAC,YAAY;IAuBpB,2EAA2E;IAC3E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,kDAAkD;IAClD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,iDAAiD;IACjD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,oDAAoD;IACpD,SAAS,IAAI,MAAM,EAAE;IAIrB,8EAA8E;IAC9E,OAAO,CAAC,GAAG;IA+BX,OAAO,CAAC,UAAU;IAYlB,2CAA2C;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,uBAAuB;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/server.js

@@ -0,0 +1,110 @@
+import { spawn } from "node:child_process";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+/**
+ * Wraps a CLI binary into an MCP stdio server. Each `BinaryToolSpec` becomes an
+ * MCP tool that runs `<command> <subcommand> <args>` and returns the output.
+ *
+ * This is intentionally generic (D10): rtk is the reference binary, but any
+ * CLI tool whose output benefits from in-loop transformation can be wrapped the
+ * same way and then chained through `@adaptivemcp/middleware`.
+ */
+export class BinaryMcpServer {
+    server;
+    opts;
+    constructor(options) {
+        this.opts = options;
+        this.server = new McpServer({ name: options.name, version: options.version ?? "0.1.0" }, { capabilities: {} });
+        for (const tool of options.tools) {
+            this.registerTool(tool);
+        }
+    }
+    registerTool(tool) {
+        this.server.registerTool(tool.name, {
+            title: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, async (args) => {
+            if (this.opts.unavailable) {
+                return {
+                    content: [{ type: "text", text: this.opts.unavailable }],
+                    isError: true,
+                };
+            }
+            const out = await this.run(tool.subcommand, args, tool.argStyle ?? "flags");
+            return {
+                content: [{ type: "text", text: out }],
+            };
+        });
+    }
+    /** Whether the wrapped binary was located and verified at construction. */
+    get available() {
+        return !this.opts.unavailable;
+    }
+    /** Server identity advertised in `initialize`. */
+    get name() {
+        return this.opts.name;
+    }
+    /** Server version advertised in `initialize`. */
+    get version() {
+        return this.opts.version ?? "0.1.0";
+    }
+    /** Names of the tools registered on this server. */
+    toolNames() {
+        return this.opts.tools.map((t) => t.name);
+    }
+    /** Spawn the binary, write `input` (if any) to stdin, resolve with stdout. */
+    run(subcommand, args, style) {
+        const cliArgs = [
+            ...(this.opts.baseArgs ?? []),
+            subcommand,
+            ...this.renderArgs(args, style),
+        ];
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.opts.command, cliArgs, {
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            let stdout = "";
+            let stderr = "";
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error(`binary ${this.opts.command} timed out after ${this.opts.timeoutMs ?? 30000}ms`));
+            }, this.opts.timeoutMs ?? 30000);
+            child.stdout.on("data", (d) => (stdout += d.toString()));
+            child.stderr.on("data", (d) => (stderr += d.toString()));
+            child.on("error", (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                if (code === 0)
+                    resolve(stdout.trim());
+                else
+                    reject(new Error(`${this.opts.command} exited ${code}: ${stderr.trim() || stdout.trim()}`));
+            });
+        });
+    }
+    renderArgs(args, style) {
+        if (style === "positionals") {
+            return Object.values(args).map(String);
+        }
+        const out = [];
+        for (const [key, value] of Object.entries(args)) {
+            if (value === undefined || value === null)
+                continue;
+            out.push(`--${key}`, String(value));
+        }
+        return out;
+    }
+    /** Attach to stdio and start listening. */
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+    /** Stop the server. */
+    async close() {
+        await this.server.close();
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@adaptivemcp/mcp-binary",
+  "version": "0.1.1",
+  "description": "Generic CLI-binary -> MCP-server stdio wrapper (the only sanctioned shell-out layer).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --config ../../vitest.config.ts"
+  },
+  "dependencies": {
+    "@adaptivemcp/spec": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}