@fcannizzaro/exocommand 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Saverio Cannizzaro
+
+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,108 @@
+<p align="center">
+  <img src="media/animation.webp" width="256" alt="exocommand" />
+</p>
+
+<h1 align="center">@fcannizzaro/exocommand</h1>
+
+<p align="center">
+  An MCP server that exposes user-defined shell commands as tools for AI coding assistants.
+</p>
+
+[![Publish Package](https://github.com/fcannizzaro/exocommand/actions/workflows/publish.yaml/badge.svg)](https://github.com/fcannizzaro/exocommand/actions/workflows/publish.yaml)
+
+## Overview
+
+Exocommand lets you define a curated set of shell commands in a simple YAML file and makes them available to any [MCP](https://modelcontextprotocol.io)-compatible AI client. Instead of giving an AI agent unrestricted terminal access, you control exactly which commands it can discover and execute.
+
+## Features
+
+- **YAML configuration** -- Define commands in a `.exocommand` file with a name, description, and shell command.
+- **Live reload** -- The server watches the config file for changes and notifies connected clients automatically.
+- **Streaming output** -- stdout and stderr are streamed line-by-line back to the client in real time.
+- **Cancellation** -- Long-running commands can be cancelled by the client; the spawned process is killed immediately.
+- **Multi-session** -- Uses the Streamable HTTP transport, supporting multiple concurrent MCP sessions.
+- **Configurable port** -- Set via the config file, the `EXO_PORT` environment variable, or defaults to `3000`.
+
+## Usage
+
+Run the server in your project directory:
+
+```bash
+bunx @fcannizzaro/exocommand
+```
+
+The server starts on `http://127.0.0.1:5555/mcp` by default.
+
+## Configuration
+
+Create a `.exocommand` file in the project root (or set a custom path with the `EXO_COMMAND_FILE` env var):
+
+```yaml
+# Optional: override the default port
+port: 4444
+
+build:
+  description: "Run the production build"
+  command: "cargo build --release"
+
+run:
+  description: "Run the application"
+  command: "cargo run"
+
+clippy:
+  description: "Run clippy linter"
+  command: "cargo clippy"
+```
+
+Each top-level key (except `port`) is a command. Commands must have a `description` and a `command` field. Names may contain letters, numbers, hyphens, and underscores.
+
+## Safety
+
+Remember to mount the `.exocommand` as read-only volume on Docker, to prevent the agent from modifying it.
+
+If you have already use a script to start containerized agents, you can modify it to automatically mount the `.exocommand` file when present in the launch directory:
+
+```bash
+extra_mounts=()
+
+[ -f "$PWD/.exocommand" ] && extra_mounts+=(-v "$PWD/.exocommand:$PWD/.exocommand:ro")
+
+docker run \
+  # ...
+	"${extra_mounts[@]}" \
+  # ...
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `EXO_COMMAND_FILE` | Path to the `.exocommand` config file | `./.exocommand` |
+| `EXO_PORT` | Server port (overrides config file) | `3000` |
+
+## Connecting an AI Client
+
+Point any MCP-compatible client at the server's `/mcp` endpoint. For example, with [OpenCode](https://opencode.ai):
+
+```json
+{
+  "mcp": {
+    "exocommand": {
+      "enabled": true,
+      "type": "remote",
+      "url": "http://host.docker.internal:5555/mcp"
+    }
+  }
+}
+```
+
+The server exposes two tools:
+
+| Tool | Description |
+| --- | --- |
+| `listCommands()` | Returns all available commands from the config file. |
+| `execute(name)` | Executes a command by name, streaming output back to the client. |
+
+## License
+
+[MIT](LICENSE)

package/dist/config.js

@@ -0,0 +1,46 @@
+import { parse as parseYaml } from "yaml";
+const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const RESERVED_KEYS = new Set(["port"]);
+export async function loadConfig(filePath) {
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+        throw new Error(`Config file not found: ${filePath}`);
+    }
+    const content = await file.text();
+    const parsed = parseYaml(content);
+    if (parsed === null || parsed === undefined || typeof parsed !== "object") {
+        throw new Error(`Invalid config: expected a YAML mapping, got ${typeof parsed}`);
+    }
+    const config = { commands: [] };
+    // Parse port
+    const rawPort = parsed.port;
+    if (rawPort !== undefined) {
+        const port = Number(rawPort);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error(`Invalid port "${rawPort}": must be an integer between 1 and 65535`);
+        }
+        config.port = port;
+    }
+    // Parse commands
+    for (const [name, value] of Object.entries(parsed)) {
+        if (RESERVED_KEYS.has(name)) {
+            continue;
+        }
+        if (!NAME_PATTERN.test(name)) {
+            throw new Error(`Invalid command name "${name}": must match ${NAME_PATTERN}`);
+        }
+        if (typeof value !== "object" ||
+            value === null ||
+            typeof value.description !== "string" ||
+            typeof value.command !== "string") {
+            throw new Error(`Invalid command "${name}": must have "description" (string) and "command" (string)`);
+        }
+        const { description, command } = value;
+        config.commands.push({ name, description, command: command.trim() });
+    }
+    return config;
+}
+export async function loadCommands(filePath) {
+    const config = await loadConfig(filePath);
+    return config.commands;
+}

package/dist/executor.js

@@ -0,0 +1,53 @@
+export async function executeCommand(command, log, signal) {
+    if (signal.aborted) {
+        return { exitCode: -1, killed: true };
+    }
+    const proc = Bun.spawn(["sh", "-c", command], {
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    const onAbort = () => {
+        proc.kill();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    const streamLines = async (stream, logger) => {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop();
+                for (const line of lines) {
+                    if (line.length > 0) {
+                        await log(logger === "stderr" ? "error" : "info", logger, line);
+                    }
+                }
+            }
+            // flush remaining buffer
+            if (buffer.length > 0) {
+                await log(logger === "stderr" ? "error" : "info", logger, buffer);
+            }
+        }
+        catch {
+            // stream may error if process is killed; ignore when aborted
+            if (!signal.aborted) {
+                throw new Error(`Error reading ${logger} stream`);
+            }
+        }
+    };
+    await Promise.all([
+        streamLines(proc.stdout, "stdout"),
+        streamLines(proc.stderr, "stderr"),
+    ]);
+    const exitCode = await proc.exited;
+    signal.removeEventListener("abort", onAbort);
+    return {
+        exitCode,
+        killed: signal.aborted,
+    };
+}

package/dist/index.js

@@ -0,0 +1,100 @@
+import { watch } from "fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "./server.js";
+import { loadConfig } from "./config.js";
+import { logger } from "./logger.js";
+const CONFIG_PATH = process.env.EXO_COMMAND_FILE || "./.exocommand";
+// Load config to get port
+const config = await loadConfig(CONFIG_PATH);
+const PORT = parseInt(process.env.EXO_PORT || String(config.port ?? 3000), 10);
+const transports = new Map();
+const servers = new Set();
+async function handleMcp(req) {
+    const url = new URL(req.url);
+    if (url.pathname !== "/mcp") {
+        return new Response("Not Found", { status: 404 });
+    }
+    const sessionId = req.headers.get("mcp-session-id") ?? undefined;
+    if (req.method === "GET") {
+        if (!sessionId || !transports.has(sessionId)) {
+            return new Response("Invalid or missing session ID", { status: 400 });
+        }
+        return transports.get(sessionId).handleRequest(req);
+    }
+    if (req.method === "DELETE") {
+        if (!sessionId || !transports.has(sessionId)) {
+            return new Response("Invalid or missing session ID", { status: 400 });
+        }
+        return transports.get(sessionId).handleRequest(req);
+    }
+    if (req.method === "POST") {
+        // reuse existing session
+        if (sessionId && transports.has(sessionId)) {
+            return transports.get(sessionId).handleRequest(req);
+        }
+        // parse body to check if it's an initialize request
+        const body = await req.json();
+        if (!sessionId && isInitializeRequest(body)) {
+            const transport = new WebStandardStreamableHTTPServerTransport({
+                sessionIdGenerator: () => crypto.randomUUID(),
+                onsessioninitialized: (sid) => {
+                    transports.set(sid, transport);
+                    logger.info("session", `created ${sid}`);
+                },
+                onsessionclosed: (sid) => {
+                    transports.delete(sid);
+                    logger.warn("session", `closed ${sid}`);
+                },
+            });
+            const server = createServer();
+            servers.add(server);
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    transports.delete(transport.sessionId);
+                }
+                servers.delete(server);
+            };
+            await server.connect(transport);
+            return transport.handleRequest(req, { parsedBody: body });
+        }
+        return Response.json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Bad Request: no valid session ID",
+            },
+            id: null,
+        }, { status: 400 });
+    }
+    return new Response("Method Not Allowed", { status: 405 });
+}
+Bun.serve({
+    port: PORT,
+    hostname: "127.0.0.1",
+    idleTimeout: 0,
+    fetch: handleMcp,
+});
+logger.info("server", `listening on http://127.0.0.1:${PORT}/mcp`);
+// Watch .exocommand for changes and notify connected clients
+let debounceTimer = null;
+watch(CONFIG_PATH, (eventType) => {
+    if (eventType !== "change")
+        return;
+    if (debounceTimer)
+        clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        logger.info("watcher", ".exocommand changed, notifying clients");
+        for (const server of servers) {
+            try {
+                server.sendToolListChanged();
+            }
+            catch {
+                // client may have disconnected
+            }
+        }
+    }, 200);
+});
+logger.info("watcher", `watching ${CONFIG_PATH} for changes`);

package/dist/logger.js

@@ -0,0 +1,31 @@
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+function timestamp() {
+    const now = new Date();
+    const h = String(now.getHours()).padStart(2, "0");
+    const m = String(now.getMinutes()).padStart(2, "0");
+    const s = String(now.getSeconds()).padStart(2, "0");
+    return `${h}:${m}:${s}`;
+}
+function format(color, event, message) {
+    return `${DIM}${timestamp()}${RESET} ${color}${BOLD}[${event}]${RESET} ${message}`;
+}
+export const logger = {
+    info(event, message) {
+        console.log(format(CYAN, event, message));
+    },
+    success(event, message) {
+        console.log(format(GREEN, event, message));
+    },
+    warn(event, message) {
+        console.log(format(YELLOW, event, message));
+    },
+    error(event, message) {
+        console.log(format(RED, event, message));
+    },
+};

package/dist/server.js

@@ -0,0 +1,140 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { loadCommands } from "./config.js";
+import { executeCommand } from "./executor.js";
+import { logger } from "./logger.js";
+const CONFIG_PATH = process.env.EXO_COMMAND_FILE || "./.exocommand";
+export function createServer() {
+    const server = new McpServer({
+        name: "exocommand",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            logging: {},
+        },
+    });
+    server.registerTool("listCommands", {
+        title: "List Commands",
+        description: "List all available commands defined in the .exocommand config file",
+    }, async () => {
+        try {
+            const commands = await loadCommands(CONFIG_PATH);
+            logger.info("listCommands", `found ${commands.length} command(s)`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(commands.map((c) => ({
+                            name: c.name,
+                            description: c.description,
+                            command: c.command,
+                        })), null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error loading commands: ${err.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("execute", {
+        title: "Execute Command",
+        description: "Execute a predefined command by name. Streams stdout and stderr via logging notifications.",
+        inputSchema: {
+            name: z.string().describe("The command name/id to execute"),
+        },
+    }, async ({ name: commandName }, extra) => {
+        logger.warn("execute", `running "${commandName}"`);
+        let commands;
+        try {
+            commands = await loadCommands(CONFIG_PATH);
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error loading config: ${err.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const cmd = commands.find((c) => c.name === commandName);
+        if (!cmd) {
+            const available = commands.map((c) => c.name).join(", ");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Command "${commandName}" not found. Available commands: ${available}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const log = async (level, logger, data) => {
+            await extra.sendNotification({
+                method: "notifications/message",
+                params: { level, logger, data },
+            });
+        };
+        try {
+            const result = await executeCommand(cmd.command, log, extra.signal);
+            if (result.killed) {
+                logger.warn("execute", `"${commandName}" was cancelled`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Command "${commandName}" was cancelled.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (result.exitCode !== 0) {
+                logger.error("execute", `"${commandName}" exited with code ${result.exitCode}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Command "${commandName}" exited with code ${result.exitCode}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            logger.success("execute", `"${commandName}" completed (exit code 0)`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Command "${commandName}" completed successfully (exit code 0)`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            logger.error("execute", `"${commandName}" failed: ${err.message}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Command "${commandName}" failed: ${err.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fcannizzaro/exocommand",
+  "module": "index.ts",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "author": {
+    "name": "Francesco Saverio Cannizzaro (fcannizzaro)",
+    "url": "https://fcannizzaro.com"
+  },
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/fcannizzaro"
+    }
+  ],
+  "bugs": {
+    "url": "https://github.com/fcannizzaro/exocommand/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fcannizzaro/exocommand"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "bin": {
+    "exocommand": "./index.js"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "yaml": "^2.8.2"
+  },
+  "keywords": [
+    "exocommand",
+    "mcp",
+    "agentic-programming",
+    "mcp",
+    "model-context-protocol"
+  ]
+}