@runa-cmd/mcp 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,185 @@
+# @runa-cmd/mcp
+
+Turn any Runa CLI into an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server with a single flag.
+
+Every command becomes an MCP tool. Zod schemas pass directly to the MCP SDK — zero schema conversion needed.
+
+## Install
+
+```bash
+pnpm add @runa-cmd/mcp
+```
+
+> Peer dependencies: `@runa-cmd/core` and `zod ^4.0.0`.
+> Runtime dependency: `@modelcontextprotocol/sdk ^1.29.0`.
+
+## Quick Start
+
+```ts
+import { defineCLI, defineCommand } from '@runa-cmd/core';
+import { z } from '@runa-cmd/core/zod';
+import { mcpPlugin } from '@runa-cmd/mcp';
+
+const deploy = defineCommand({
+  meta: { name: 'deploy', description: 'Deploy a service' },
+  args: { service: z.string().describe('Service name') },
+  options: { env: z.enum(['staging', 'production']).describe('Target') },
+  output: z.object({ url: z.string(), status: z.string() }),
+  async run({ args, options }) {
+    return {
+      url: `https://${options.env}.example.com/${args.service}`,
+      status: 'deployed',
+    };
+  },
+});
+
+const cli = defineCLI({
+  meta: { name: 'my-tool', version: '1.0.0' },
+  commands: { deploy },
+  plugins: [mcpPlugin()],
+});
+
+cli.run();
+```
+
+```bash
+# Normal CLI usage
+$ my-tool deploy api --env staging
+
+# MCP server mode — for AI agents (Claude, Cursor, etc.)
+$ my-tool --mcp
+```
+
+When `--mcp` is passed, the CLI starts a stdio-based MCP server instead of normal execution. AI agents can then discover and call your commands as tools.
+
+## How It Works
+
+1. The plugin adds a `--mcp` global boolean flag
+2. On `onGlobalFlags` hook, if `--mcp` is true:
+   - Introspects the CLI schema via `getSchema()`
+   - Gets the live command tree via `getCommands()`
+   - Maps each leaf command to an MCP tool
+   - Starts an MCP server over stdio transport
+   - Short-circuits normal CLI execution
+
+### Command → Tool Mapping
+
+| CLI Command | MCP Tool Name | Why |
+|---|---|---|
+| `deploy` | `deploy` | Direct mapping |
+| `config get` | `config_get` | Nested commands join with `_` |
+| `db migrate` | `db_migrate` | Same pattern |
+
+### Schema Mapping
+
+Args and options merge into a single MCP `inputSchema`:
+
+```
+CLI: deploy <service> --env staging
+MCP: { "service": "api", "env": "staging" }
+```
+
+The plugin tracks which keys are args vs options internally, so it can reconstruct the proper `RunContext` when executing the command.
+
+### Output Handling
+
+| Scenario | MCP Response |
+|---|---|
+| Command has `output` schema | `structuredContent` with typed data |
+| Command returns a string (no output schema) | `text` content |
+| Command returns an object (no output schema) | `text` content (JSON stringified) |
+| Command returns void | `text: "ok"` |
+| Command throws | `isError: true` with error message |
+
+## API
+
+### `mcpPlugin(options?)`
+
+Creates the MCP plugin. Returns a `PluginConfig` compatible with `defineCLI`.
+
+```ts
+import { mcpPlugin } from '@runa-cmd/mcp';
+
+mcpPlugin({
+  name: 'my-server',          // MCP server name (defaults to CLI name)
+  version: '2.0.0',           // MCP server version (defaults to CLI version)
+  instructions: 'Use deploy before running tests', // Cross-tool workflow hints for AI
+});
+```
+
+### `McpPluginOptions`
+
+```ts
+interface McpPluginOptions {
+  name?: string;          // Server name override
+  version?: string;       // Server version override
+  instructions?: string;  // Workflow instructions for AI agents
+}
+```
+
+## With Help Plugin
+
+MCP and help work together — just add both:
+
+```ts
+import { helpPlugin } from '@runa-cmd/help';
+import { mcpPlugin } from '@runa-cmd/mcp';
+
+const cli = defineCLI({
+  meta: { name: 'my-tool', version: '1.0.0' },
+  commands: { deploy, init },
+  plugins: [helpPlugin(), mcpPlugin()],
+});
+```
+
+```bash
+$ my-tool --help   # Human-readable help
+$ my-tool --mcp    # Machine-readable MCP server
+```
+
+## MCP Server Details
+
+- **Transport**: stdio (stdin/stdout JSON-RPC)
+- **Graceful shutdown**: Handles SIGINT and SIGTERM
+- **SDK**: Uses `@modelcontextprotocol/sdk` v1.29+ with `McpServer` API
+- **Zod v4 native**: Zod v4 implements [Standard Schema](https://github.com/standard-schema/standard-schema), so schemas pass directly to `registerTool()` — no conversion layer
+
+### Testing with MCP Inspector
+
+You can test your MCP server with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx @modelcontextprotocol/inspector my-tool --mcp
+```
+
+### Configuring in Claude Desktop
+
+Add to your Claude Desktop MCP config (`~/.config/claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "my-tool": {
+      "command": "node",
+      "args": ["path/to/my-tool.js", "--mcp"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+mcpPlugin()
+    │
+    ├── plugin.ts     Runa plugin (adds --mcp flag, orchestrates lifecycle)
+    ├── schema.ts     Builds tool registrations from command tree
+    ├── server.ts     Creates MCP server, registers tools, handles execution
+    └── types.ts      McpPluginOptions interface
+```
+
+The package has a single runtime dependency (`@modelcontextprotocol/sdk`) and delegates everything else to `@runa-cmd/core`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @runa-cmd/mcp — Public API
+ *
+ * Barrel re-exports for the MCP plugin package.
+ */
+export { mcpPlugin } from './plugin.js';
+export type { McpPluginOptions } from './types.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;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @runa-cmd/mcp — Public API
+ *
+ * Barrel re-exports for the MCP plugin package.
+ */
+export { mcpPlugin } from './plugin.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;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @runa-cmd/mcp — mcpPlugin()
+ *
+ * A Runa plugin that exposes CLI commands as MCP tools.
+ * When `--mcp` is passed, the plugin short-circuits normal CLI execution,
+ * starts an MCP server on stdio transport, and registers every CLI
+ * command as an MCP tool.
+ */
+import type { PluginConfig } from '@runa-cmd/core';
+import type { McpPluginOptions } from './types.js';
+/**
+ * Create an MCP plugin that exposes CLI commands as MCP tools.
+ *
+ * @param opts - Optional server name, version, or instructions override
+ */
+export declare function mcpPlugin(opts?: McpPluginOptions): PluginConfig;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAKhE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,gBAAqB,GAAG,YAAY,CAuCnE"}

package/dist/plugin.js

@@ -0,0 +1,42 @@
+import { definePlugin } from '@runa-cmd/core';
+import { z } from 'zod';
+import { buildToolRegistrations } from './schema.js';
+import { createMcpServer, registerTools, startServer } from './server.js';
+/**
+ * Create an MCP plugin that exposes CLI commands as MCP tools.
+ *
+ * @param opts - Optional server name, version, or instructions override
+ */
+export function mcpPlugin(opts = {}) {
+    return definePlugin({
+        meta: {
+            name: '@runa-cmd/mcp',
+            version: '0.1.0',
+            description: 'MCP server generation from CLI commands',
+        },
+        capabilities: { addGlobalOptions: true },
+        setup(api) {
+            // Add --mcp as a global boolean option
+            api.addGlobalOption('mcp', z.boolean().optional().default(false).describe('Start MCP server'));
+            // Intercept via onGlobalFlags hook
+            api.hook('onGlobalFlags', async (ctx) => {
+                if (!ctx.globalOptions?.mcp)
+                    return;
+                const schema = api.getSchema();
+                const commands = api.getCommands();
+                const registrations = buildToolRegistrations(commands, schema);
+                const server = createMcpServer({
+                    name: opts.name ?? schema.meta.name,
+                    version: opts.version ?? schema.meta.version ?? '0.0.0',
+                    instructions: opts.instructions,
+                });
+                registerTools(server, registrations);
+                await startServer(server);
+                // Short-circuit — MCP server now running, don't execute CLI command
+                // NOTE: Do NOT call process.exit() — server must stay alive for tool invocations
+                ctx.shortCircuit?.();
+            });
+        },
+    });
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1E;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB,EAAE;IACpD,OAAO,YAAY,CAAC;QACnB,IAAI,EAAE;YACL,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,OAAO;YAChB,WAAW,EAAE,yCAAyC;SACtD;QACD,YAAY,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE;QACxC,KAAK,CAAC,GAAG;YACR,uCAAuC;YACvC,GAAG,CAAC,eAAe,CAClB,KAAK,EACL,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAClE,CAAC;YAEF,mCAAmC;YACnC,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,KAAK,EAAE,GAAgB,EAAE,EAAE;gBACpD,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG;oBAAE,OAAO;gBAEpC,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;gBAC/B,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;gBAEnC,MAAM,aAAa,GAAG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAE/D,MAAM,MAAM,GAAG,eAAe,CAAC;oBAC9B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;oBACnC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,OAAO;oBACvD,YAAY,EAAE,IAAI,CAAC,YAAY;iBAC/B,CAAC,CAAC;gBAEH,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;gBACrC,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;gBAE1B,oEAAoE;gBACpE,iFAAiF;gBACjF,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC;YACtB,CAAC,CAAC,CAAC;QACJ,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @runa-cmd/mcp — Command → MCP tool schema mapping
+ *
+ * Walks the CommandTree and builds ToolRegistration objects
+ * that map each command to an MCP tool with merged input schema.
+ */
+import type { CLISchema, Command, CommandTree } from '@runa-cmd/core';
+import type { ZodType } from 'zod';
+/**
+ * Represents a single MCP tool registration derived from a CLI command.
+ */
+export interface ToolRegistration {
+    /** MCP tool name (e.g., 'config_set') */
+    name: string;
+    /** Tool description from command metadata */
+    description: string;
+    /** Merged args + options as a Zod shape (Record<string, ZodType>) */
+    inputShape: Record<string, ZodType>;
+    /** Command output schema if defined */
+    outputSchema?: ZodType;
+    /** Reference to the Command for executing run() */
+    command: Command;
+    /** Keys that belong to args (for splitting input back on invocation) */
+    argKeys: Set<string>;
+    /** Keys that belong to options */
+    optionKeys: Set<string>;
+}
+/**
+ * Build MCP tool registrations from a CommandTree and CLISchema.
+ *
+ * Walks the tree, maps each leaf command to a ToolRegistration with:
+ * - Merged args + options as inputShape
+ * - Output schema if defined
+ * - Arg/option key sets for splitting input on invocation
+ */
+export declare function buildToolRegistrations(commands: CommandTree, schema: CLISchema): ToolRegistration[];
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAiB,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,uCAAuC;IACvC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,kCAAkC;IAClC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AAyFD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,SAAS,GACf,gBAAgB,EAAE,CAEpB"}

package/dist/schema.js

@@ -0,0 +1,82 @@
+// ─── Helpers ────────────────────────────────────────────────
+function isCommand(value) {
+    return '_type' in value && value._type === 'runa:command';
+}
+/**
+ * Find the matching CommandSchema from CLISchema for a given fullPath.
+ */
+function findCommandSchema(schemas, fullPath) {
+    for (const schema of schemas) {
+        if (pathsMatch(schema.fullPath, fullPath))
+            return schema;
+        if (schema.subcommands) {
+            const found = findCommandSchema(schema.subcommands, fullPath);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+function pathsMatch(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((segment, i) => segment === b[i]);
+}
+// ─── Core ───────────────────────────────────────────────────
+/**
+ * Walk a CommandTree and build ToolRegistration[] for all leaf commands.
+ * Group nodes (non-leaf, no run()) are skipped.
+ */
+function walkTree(tree, parentPath, cliSchema) {
+    const registrations = [];
+    for (const [name, entry] of Object.entries(tree)) {
+        const fullPath = [...parentPath, name];
+        if (isCommand(entry)) {
+            const toolName = fullPath.join('_');
+            const cmdSchema = findCommandSchema(cliSchema.commands, fullPath);
+            // Merge args + options into a single input shape
+            const inputShape = {};
+            const argKeys = new Set();
+            const optionKeys = new Set();
+            if (entry.args) {
+                for (const [key, schema] of Object.entries(entry.args)) {
+                    inputShape[key] = schema;
+                    argKeys.add(key);
+                }
+            }
+            if (entry.options) {
+                for (const [key, schema] of Object.entries(entry.options)) {
+                    inputShape[key] = schema;
+                    optionKeys.add(key);
+                }
+            }
+            registrations.push({
+                name: toolName,
+                description: cmdSchema?.description ?? entry.meta.description,
+                inputShape,
+                outputSchema: entry.output,
+                command: entry,
+                argKeys,
+                optionKeys,
+            });
+        }
+        else {
+            // It's a subtree — recurse
+            registrations.push(...walkTree(entry, fullPath, cliSchema));
+        }
+    }
+    return registrations;
+}
+// ─── Public API ─────────────────────────────────────────────
+/**
+ * Build MCP tool registrations from a CommandTree and CLISchema.
+ *
+ * Walks the tree, maps each leaf command to a ToolRegistration with:
+ * - Merged args + options as inputShape
+ * - Output schema if defined
+ * - Arg/option key sets for splitting input on invocation
+ */
+export function buildToolRegistrations(commands, schema) {
+    return walkTree(commands, [], schema);
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @runa-cmd/mcp — MCP server creation and tool registration
+ *
+ * Creates an MCP server, registers tools from ToolRegistrations,
+ * and manages the server lifecycle (stdio transport, signal handlers).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolRegistration } from './schema.js';
+/**
+ * Create an MCP server with the given metadata.
+ */
+export declare function createMcpServer(opts: {
+    name: string;
+    version: string;
+    instructions?: string;
+}): McpServer;
+/**
+ * Register MCP tools on the server from ToolRegistration objects.
+ *
+ * Each tool's handler:
+ * 1. Splits the input back into args/options using stored key sets
+ * 2. Calls command.run() with a constructed RunContext
+ * 3. Returns structured content if outputSchema exists, text otherwise
+ * 4. Catches errors and returns isError: true
+ */
+export declare function registerTools(server: McpServer, registrations: ToolRegistration[]): void;
+/**
+ * Start the MCP server on stdio transport.
+ * Registers signal handlers for graceful shutdown.
+ *
+ * Returns a close function for cleanup.
+ */
+export declare function startServer(server: McpServer): Promise<{
+    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":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,SAAS,CAKZ;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,IAAI,CA6BxF;AAmED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAiB5F"}

package/dist/server.js

@@ -0,0 +1,125 @@
+/**
+ * @runa-cmd/mcp — MCP server creation and tool registration
+ *
+ * Creates an MCP server, registers tools from ToolRegistrations,
+ * and manages the server lifecycle (stdio transport, signal handlers).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// ─── Server Creation ────────────────────────────────────────
+/**
+ * Create an MCP server with the given metadata.
+ */
+export function createMcpServer(opts) {
+    return new McpServer({ name: opts.name, version: opts.version }, { instructions: opts.instructions });
+}
+// ─── Tool Registration ──────────────────────────────────────
+/**
+ * Register MCP tools on the server from ToolRegistration objects.
+ *
+ * Each tool's handler:
+ * 1. Splits the input back into args/options using stored key sets
+ * 2. Calls command.run() with a constructed RunContext
+ * 3. Returns structured content if outputSchema exists, text otherwise
+ * 4. Catches errors and returns isError: true
+ */
+export function registerTools(server, registrations) {
+    for (const reg of registrations) {
+        const hasInput = Object.keys(reg.inputShape).length > 0;
+        if (hasInput) {
+            server.registerTool(reg.name, {
+                description: reg.description,
+                inputSchema: reg.inputShape,
+                ...(reg.outputSchema ? { outputSchema: reg.outputSchema } : {}),
+            }, async (input) => {
+                return executeToolHandler(reg, input);
+            });
+        }
+        else {
+            server.registerTool(reg.name, {
+                description: reg.description,
+                ...(reg.outputSchema ? { outputSchema: reg.outputSchema } : {}),
+            }, async () => {
+                return executeToolHandler(reg, {});
+            });
+        }
+    }
+}
+/**
+ * Execute a tool handler — splits input into args/options, runs the command,
+ * and returns the appropriate MCP result.
+ */
+async function executeToolHandler(reg, input) {
+    // Split input back into args and options
+    const runArgs = {};
+    const runOptions = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (reg.argKeys.has(key)) {
+            runArgs[key] = value;
+        }
+        else {
+            runOptions[key] = value;
+        }
+    }
+    try {
+        const result = await reg.command.run({
+            args: runArgs,
+            options: runOptions,
+            globalOptions: {},
+            command: reg.command.meta,
+            rawArgs: [],
+        });
+        // Command has output schema — return structured content
+        if (reg.outputSchema) {
+            reg.outputSchema.parse(result);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        // Command returned something (but no output schema)
+        if (result !== undefined && result !== null) {
+            const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            return {
+                content: [{ type: 'text', text }],
+            };
+        }
+        // Void command — success message
+        return {
+            content: [{ type: 'text', text: `Command '${reg.name}' executed successfully.` }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: err instanceof Error ? err.message : String(err),
+                },
+            ],
+        };
+    }
+}
+// ─── Server Lifecycle ───────────────────────────────────────
+/**
+ * Start the MCP server on stdio transport.
+ * Registers signal handlers for graceful shutdown.
+ *
+ * Returns a close function for cleanup.
+ */
+export async function startServer(server) {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const close = async () => {
+        await server.close();
+    };
+    const handleShutdown = async () => {
+        await close();
+        process.exit(0);
+    };
+    process.on('SIGINT', handleShutdown);
+    process.on('SIGTERM', handleShutdown);
+    return { 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/dist/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @runa-cmd/mcp — Type definitions
+ *
+ * Plugin options for mcpPlugin().
+ */
+/**
+ * Options for mcpPlugin().
+ */
+export interface McpPluginOptions {
+    /** Custom server name override (defaults to CLI meta.name) */
+    name?: string;
+    /** Custom server version override (defaults to CLI meta.version) */
+    version?: string;
+    /** Server instructions for cross-tool workflows */
+    instructions?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * @runa-cmd/mcp — Type definitions
+ *
+ * Plugin options for mcpPlugin().
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@runa-cmd/mcp",
+  "version": "0.1.0",
+  "description": "MCP (Model Context Protocol) server mode for Runa CLIs. Turn commands into AI-callable tools.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "cli",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "tools",
+    "runa"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "@runa-cmd/core": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jrodrigopuca/runa-cmd.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/jrodrigopuca/runa-cmd/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/jrodrigopuca/runa-cmd/issues"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.2",
+    "zod": "^4.3.6",
+    "@runa-cmd/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "clean": "rm -rf dist"
+  }
+}