bash-command-mcp 0.1.0

package/Dockerfile

@@ -0,0 +1,13 @@
+FROM oven/bun:1.3.2
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile --production
+
+COPY index.ts tsconfig.json ./
+
+WORKDIR /workspace
+VOLUME ["/workspace"]
+
+CMD ["bun", "run", "/app/index.ts"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrorigo@gmail.com
+
+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,102 @@
+# bash-command-mcp
+
+A highly sophisticated Bash MCP server for safe, structured command execution with first-class background job orchestration.
+
+## Important Security Warning
+
+This server executes shell commands on the machine where it is running.
+
+If you run `bun run index.ts` directly on your host, commands run on your host with your user permissions.
+Use Docker to isolate execution unless you fully trust the MCP client and prompts.
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+To run via npm/npx (published package):
+
+```bash
+npx -y bash-command-mcp
+```
+
+## Why This Server
+
+- High-fidelity shell execution with clear exit-code semantics.
+- Advanced background process lifecycle controls (`run_background`, `wait_background`, `kill_background`).
+- Built-in observability via per-process stdout/stderr log files.
+- OpenTelemetry traces and metrics for production visibility.
+- Agent-friendly ergonomics with `cwd` and `env` overrides for precise execution context.
+
+## Tool Behavior
+
+Tools:
+- `run`: run command in foreground.
+  Args: `command` or `cmd`, `timeoutSeconds` (default `60`, min `1`), optional `cwd`, optional `env`.
+- `run_background`: start command in background with stdout/stderr written to log files.
+  Args: `command` or `cmd`, optional `cwd`, optional `env`.
+- `list_background`: list tracked background processes, including log file paths.
+- `kill_background`: stop tracked background process by `pid`.
+- `tail_background`: show last N lines from background process logs.
+  Args: `pid`, optional `lines` (default `200`, max `5000`).
+- `wait_background`: wait for background process completion and return final status/output.
+  Args: `pid`, optional `timeoutSeconds` (default `60`, min `1`).
+## OpenTelemetry
+
+This server includes optional OpenTelemetry instrumentation for traces and metrics.
+
+- If OTel packages are available and `OTEL_ENABLED` is not set to `false`, telemetry is initialized.
+- If `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces/metrics are exported via OTLP HTTP.
+- If no OTLP endpoint is configured, console exporters are used.
+- If OTel packages are not installed, the server continues normally with telemetry disabled.
+
+Instrumented operations:
+- Tool call spans for `run`, `run_background`, `list_background`, `tail_background`, `wait_background`, and `kill_background`.
+- Background lifecycle spans/counters (`started`, `ended`).
+- Metrics for tool calls, failures, timeouts, and duration histograms.
+
+Common env vars:
+- `OTEL_ENABLED=true|false`
+- `OTEL_SERVICE_NAME=bash-command-mcp`
+- `OTEL_SERVICE_VERSION=1.0.0`
+- `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`
+- `OTEL_METRIC_EXPORT_INTERVAL_MS=10000`
+- `BASH_COMMAND_MCP_LOG_DIR=/path/to/log-dir`
+
+Example (OTLP Collector on localhost):
+
+```bash
+OTEL_ENABLED=true \
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+OTEL_SERVICE_NAME=bash-command-mcp \
+npx -y bash-command-mcp
+```
+
+## Docker
+
+Build the image:
+
+```bash
+docker build -t bash-command-mcp .
+```
+
+Run with a local folder mounted at `/workspace`:
+
+```bash
+docker run --rm -i -v "$(pwd):/workspace" bash-command-mcp
+```
+
+`/workspace` mapping explained:
+- Left side (`$(pwd)`) is a folder on your host machine.
+- Right side (`/workspace`) is the path inside the container.
+- Commands run by this MCP server should target files under `/workspace`; those changes are written back to the mapped host folder.
+
+Example:
+- If your host has `./project/file.txt` and you run the container from `./project`, the same file is available in the container at `/workspace/file.txt`.

package/dist/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { BackgroundProcessManager, } from "./src/background-manager.js";
+import { Observability } from "./src/observability.js";
+import { registerTools } from "./src/tools.js";
+const server = new McpServer({
+    name: "bash-command-mcp",
+    version: "1.0.0",
+});
+const observability = new Observability();
+function onBackgroundLifecycle(event, view) {
+    if (event === "started") {
+        observability.backgroundEvent("started", {
+            "mcp.command.pid": view.pid,
+            "mcp.command.status": view.status,
+            "mcp.command.cwd": view.cwd,
+        });
+        return;
+    }
+    observability.backgroundEvent("ended", {
+        "mcp.command.pid": view.pid,
+        "mcp.command.status": view.status,
+        "mcp.command.exit_code": view.exitCode ?? -1,
+        "mcp.command.signal": view.signal ?? "none",
+    });
+}
+const backgroundManager = new BackgroundProcessManager(process.env.BASH_COMMAND_MCP_LOG_DIR, onBackgroundLifecycle);
+registerTools(server, backgroundManager, observability);
+async function shutdownWithCode(exitCode) {
+    try {
+        await observability.shutdown();
+    }
+    catch (error) {
+        console.error("Observability shutdown error:", error);
+    }
+    finally {
+        process.exit(exitCode);
+    }
+}
+async function main() {
+    await observability.init();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const status = observability.getStatus();
+    console.error(`bash-command-mcp running on stdio (observability=${status.enabled ? "on" : "off"}, reason=${status.reason})`);
+    process.on("SIGINT", () => {
+        void shutdownWithCode(0);
+    });
+    process.on("SIGTERM", () => {
+        void shutdownWithCode(0);
+    });
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    void shutdownWithCode(1);
+});

package/dist/src/background-manager.js

@@ -0,0 +1,263 @@
+import { closeSync, existsSync, mkdirSync, openSync, statSync } from "node:fs";
+import { readFile, open } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import { terminateProcess } from "./shell.js";
+import { getErrorMessage } from "./error-utils.js";
+function defaultLogDir() {
+    return (process.env.BASH_COMMAND_MCP_LOG_DIR || join(tmpdir(), "bash-command-mcp"));
+}
+async function readTail(filePath, lines) {
+    const maxBytes = 256 * 1024;
+    if (!existsSync(filePath)) {
+        return "";
+    }
+    const fileSize = statSync(filePath).size;
+    if (fileSize === 0) {
+        return "";
+    }
+    const start = Math.max(0, fileSize - maxBytes);
+    const length = fileSize - start;
+    const file = await open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        await file.read(buffer, 0, length, start);
+        let text = buffer.toString("utf8");
+        if (start > 0) {
+            const firstNewline = text.indexOf("\n");
+            if (firstNewline >= 0) {
+                text = text.slice(firstNewline + 1);
+            }
+        }
+        const split = text.split(/\r?\n/);
+        const trimmed = split.at(-1) === "" ? split.slice(0, -1) : split;
+        return trimmed.slice(-lines).join("\n");
+    }
+    finally {
+        await file.close();
+    }
+}
+function toView(record) {
+    return {
+        pid: record.pid,
+        command: record.command,
+        cwd: record.cwd,
+        startedAt: record.startedAt,
+        status: record.status,
+        exitCode: record.exitCode,
+        signal: record.signal,
+        endedAt: record.endedAt,
+        error: record.error,
+        stdoutLogPath: record.stdoutLogPath,
+        stderrLogPath: record.stderrLogPath,
+    };
+}
+export class BackgroundProcessManager {
+    records = new Map();
+    logDir;
+    onLifecycleEvent;
+    constructor(logDir = defaultLogDir(), onLifecycleEvent) {
+        this.logDir = logDir;
+        this.onLifecycleEvent = onLifecycleEvent;
+        mkdirSync(this.logDir, { recursive: true });
+    }
+    start(command, overrides) {
+        const unique = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const stdoutLogPath = join(this.logDir, `bg-${unique}.stdout.log`);
+        const stderrLogPath = join(this.logDir, `bg-${unique}.stderr.log`);
+        const stdoutFd = openSync(stdoutLogPath, "a");
+        const stderrFd = openSync(stderrLogPath, "a");
+        try {
+            const child = spawn(command, {
+                shell: true,
+                detached: true,
+                cwd: overrides.cwd,
+                env: overrides.env ? { ...process.env, ...overrides.env } : process.env,
+                stdio: ["ignore", stdoutFd, stderrFd],
+            });
+            child.unref();
+            if (!child.pid) {
+                throw new Error("failed to start process (missing pid)");
+            }
+            let resolveCompletion = () => { };
+            const completion = new Promise((resolve) => {
+                resolveCompletion = resolve;
+            });
+            const record = {
+                pid: child.pid,
+                command,
+                cwd: overrides.cwd || process.cwd(),
+                startedAt: new Date().toISOString(),
+                status: "running",
+                exitCode: null,
+                signal: null,
+                endedAt: null,
+                error: null,
+                stdoutLogPath,
+                stderrLogPath,
+                child,
+                completion,
+                resolveCompletion,
+                completed: false,
+            };
+            this.records.set(record.pid, record);
+            this.onLifecycleEvent?.("started", toView(record));
+            child.on("close", (code, signal) => {
+                const current = this.records.get(record.pid);
+                if (!current) {
+                    return;
+                }
+                if (current.completed) {
+                    return;
+                }
+                current.exitCode = typeof code === "number" ? code : null;
+                current.signal = signal ?? null;
+                current.endedAt = new Date().toISOString();
+                if (current.status === "running") {
+                    current.status = signal ? "killed" : "exited";
+                }
+                current.completed = true;
+                this.onLifecycleEvent?.(signal ? "killed" : "completed", toView(current));
+                current.resolveCompletion(toView(current));
+            });
+            child.on("error", (error) => {
+                const current = this.records.get(record.pid);
+                if (!current || current.completed) {
+                    return;
+                }
+                current.status = "error";
+                current.error = error.message;
+                current.endedAt = new Date().toISOString();
+                current.completed = true;
+                this.onLifecycleEvent?.("error", toView(current));
+                current.resolveCompletion(toView(current));
+            });
+            return toView(record);
+        }
+        finally {
+            closeSync(stdoutFd);
+            closeSync(stderrFd);
+        }
+    }
+    list() {
+        return Array.from(this.records.values())
+            .sort((a, b) => a.pid - b.pid)
+            .map((record) => toView(record));
+    }
+    get(pid) {
+        const record = this.records.get(pid);
+        return record ? toView(record) : null;
+    }
+    countRunning() {
+        return Array.from(this.records.values()).filter((record) => record.status === "running").length;
+    }
+    kill(pid) {
+        const record = this.records.get(pid);
+        if (!record) {
+            return {
+                ok: false,
+                message: `No tracked background process found for PID ${pid}.`,
+                view: null,
+            };
+        }
+        if (record.status !== "running") {
+            return {
+                ok: true,
+                message: `Process ${pid} is already ${record.status}.`,
+                view: toView(record),
+            };
+        }
+        try {
+            terminateProcess(pid);
+            record.status = "killed";
+            record.signal = "SIGTERM";
+            record.endedAt = new Date().toISOString();
+            this.onLifecycleEvent?.("killed", toView(record));
+            return {
+                ok: true,
+                message: `Sent SIGTERM to background process ${pid}.`,
+                view: toView(record),
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                message: `Failed to kill process ${pid}: ${getErrorMessage(error)}`,
+                view: toView(record),
+            };
+        }
+    }
+    async tail(pid, lines) {
+        const record = this.records.get(pid);
+        if (!record) {
+            return {
+                ok: false,
+                message: `No tracked background process found for PID ${pid}.`,
+                view: null,
+                stdout: "",
+                stderr: "",
+            };
+        }
+        const stdout = await readTail(record.stdoutLogPath, lines);
+        const stderr = await readTail(record.stderrLogPath, lines);
+        return {
+            ok: true,
+            message: `Showing last ${lines} line(s) for PID ${pid}.`,
+            view: toView(record),
+            stdout,
+            stderr,
+        };
+    }
+    async wait(pid, timeoutSeconds) {
+        const record = this.records.get(pid);
+        if (!record) {
+            return {
+                ok: false,
+                timedOut: false,
+                message: `No tracked background process found for PID ${pid}.`,
+                view: null,
+            };
+        }
+        if (record.status !== "running") {
+            return {
+                ok: true,
+                timedOut: false,
+                message: `Process ${pid} is already ${record.status}.`,
+                view: toView(record),
+            };
+        }
+        const timeoutMs = timeoutSeconds * 1000;
+        const timeoutResult = await Promise.race([
+            record.completion.then((view) => ({ type: "done", view })),
+            new Promise((resolve) => {
+                setTimeout(() => resolve({ type: "timeout" }), timeoutMs);
+            }),
+        ]);
+        if (timeoutResult.type === "timeout") {
+            return {
+                ok: false,
+                timedOut: true,
+                message: `Timed out waiting for PID ${pid} after ${timeoutSeconds} second(s).`,
+                view: toView(record),
+            };
+        }
+        return {
+            ok: true,
+            timedOut: false,
+            message: `Process ${pid} completed with status ${timeoutResult.view.status}.`,
+            view: timeoutResult.view,
+        };
+    }
+    async readLogs(pid) {
+        const record = this.records.get(pid);
+        if (!record) {
+            return null;
+        }
+        const [stdout, stderr] = await Promise.all([
+            readFile(record.stdoutLogPath, "utf8").catch(() => ""),
+            readFile(record.stderrLogPath, "utf8").catch(() => ""),
+        ]);
+        return { stdout, stderr };
+    }
+}

package/dist/src/error-utils.js

@@ -0,0 +1,14 @@
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}

package/dist/src/observability.js

@@ -0,0 +1,261 @@
+import { createRequire } from "node:module";
+import { getErrorMessage } from "./error-utils.js";
+function sanitizeAttributes(attrs) {
+    const out = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === undefined)
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+function assertObject(value, context) {
+    if (!value || typeof value !== "object") {
+        throw new Error(`${context}: expected object`);
+    }
+    return value;
+}
+function asCallable(value, context) {
+    if (typeof value !== "function") {
+        throw new Error(`${context}: expected function`);
+    }
+    return value;
+}
+function asConstructor(value, context) {
+    if (typeof value !== "function") {
+        throw new Error(`${context}: expected constructor`);
+    }
+    return value;
+}
+function asTracerLike(value) {
+    const obj = assertObject(value, "tracer");
+    return {
+        startSpan: asCallable(obj.startSpan, "tracer.startSpan"),
+    };
+}
+function asMeterLike(value) {
+    const obj = assertObject(value, "meter");
+    return {
+        createCounter: asCallable(obj.createCounter, "meter.createCounter"),
+        createHistogram: asCallable(obj.createHistogram, "meter.createHistogram"),
+    };
+}
+class NoopToolSpan {
+    setAttribute() { }
+    addEvent() { }
+    recordException() { }
+    end() { }
+}
+export class Observability {
+    tracer = null;
+    sdk = null;
+    spanStatusCodeError = null;
+    status;
+    toolCalls = null;
+    toolFailures = null;
+    toolTimeouts = null;
+    toolDuration = null;
+    bgStarted = null;
+    bgEnded = null;
+    constructor() {
+        this.status = {
+            enabled: false,
+            reason: "not_initialized",
+            serviceName: process.env.OTEL_SERVICE_NAME || "bash-command-mcp",
+            exporter: "none",
+        };
+    }
+    async init() {
+        if (process.env.OTEL_ENABLED === "false") {
+            this.status = {
+                ...this.status,
+                enabled: false,
+                reason: "disabled_by_env",
+            };
+            return;
+        }
+        const requireFn = createRequire(import.meta.url);
+        try {
+            const otelApiUnknown = requireFn("@opentelemetry/api");
+            const sdkNodeUnknown = requireFn("@opentelemetry/sdk-node");
+            const resourcesUnknown = requireFn("@opentelemetry/resources");
+            const otelApiObj = assertObject(otelApiUnknown, "@opentelemetry/api");
+            const sdkNodeObj = assertObject(sdkNodeUnknown, "@opentelemetry/sdk-node");
+            const resourcesObj = assertObject(resourcesUnknown, "@opentelemetry/resources");
+            const traceObj = assertObject(otelApiObj.trace, "otelApi.trace");
+            const metricsObj = assertObject(otelApiObj.metrics, "otelApi.metrics");
+            const spanStatusObj = assertObject(otelApiObj.SpanStatusCode, "otelApi.SpanStatusCode");
+            const getTracer = asCallable(traceObj.getTracer, "otelApi.trace.getTracer");
+            const getMeter = asCallable(metricsObj.getMeter, "otelApi.metrics.getMeter");
+            const otelApi = {
+                trace: {
+                    getTracer: (name, version) => asTracerLike(getTracer(name, version)),
+                },
+                metrics: {
+                    getMeter: (name, version) => asMeterLike(getMeter(name, version)),
+                },
+                SpanStatusCode: {
+                    ERROR: typeof spanStatusObj.ERROR === "number" ? spanStatusObj.ERROR : 2,
+                },
+            };
+            const nodeSdkCtor = asConstructor(sdkNodeObj.NodeSDK, "NodeSDK");
+            const resourceCtor = asConstructor(resourcesObj.Resource, "Resource");
+            const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+            let traceExporter;
+            let metricReader;
+            let exporterName = "console";
+            if (endpoint) {
+                const traceHttpUnknown = requireFn("@opentelemetry/exporter-trace-otlp-http");
+                const metricHttpUnknown = requireFn("@opentelemetry/exporter-metrics-otlp-http");
+                const metricsSdkUnknown = requireFn("@opentelemetry/sdk-metrics");
+                const traceHttpObj = assertObject(traceHttpUnknown, "trace exporter module");
+                const metricHttpObj = assertObject(metricHttpUnknown, "metric exporter module");
+                const metricsSdkObj = assertObject(metricsSdkUnknown, "metrics sdk module");
+                const otlpTraceCtor = asConstructor(traceHttpObj.OTLPTraceExporter, "OTLPTraceExporter");
+                const otlpMetricCtor = asConstructor(metricHttpObj.OTLPMetricExporter, "OTLPMetricExporter");
+                const periodicReaderCtor = asConstructor(metricsSdkObj.PeriodicExportingMetricReader, "PeriodicExportingMetricReader");
+                const baseEndpoint = endpoint.replace(/\/$/, "");
+                traceExporter = new otlpTraceCtor({
+                    url: `${baseEndpoint}/v1/traces`,
+                });
+                const metricExporter = new otlpMetricCtor({
+                    url: `${baseEndpoint}/v1/metrics`,
+                });
+                metricReader = new periodicReaderCtor({
+                    exporter: metricExporter,
+                    exportIntervalMillis: Number(process.env.OTEL_METRIC_EXPORT_INTERVAL_MS || 10000),
+                });
+                exporterName = "otlp_http";
+            }
+            else {
+                const traceBaseUnknown = requireFn("@opentelemetry/sdk-trace-base");
+                const metricsSdkUnknown = requireFn("@opentelemetry/sdk-metrics");
+                const traceBaseObj = assertObject(traceBaseUnknown, "trace base module");
+                const metricsSdkObj = assertObject(metricsSdkUnknown, "metrics sdk module");
+                const consoleSpanCtor = asConstructor(traceBaseObj.ConsoleSpanExporter, "ConsoleSpanExporter");
+                const periodicReaderCtor = asConstructor(metricsSdkObj.PeriodicExportingMetricReader, "PeriodicExportingMetricReader");
+                const consoleMetricCtor = asConstructor(metricsSdkObj.ConsoleMetricExporter, "ConsoleMetricExporter");
+                traceExporter = new consoleSpanCtor();
+                metricReader = new periodicReaderCtor({
+                    exporter: new consoleMetricCtor(),
+                    exportIntervalMillis: Number(process.env.OTEL_METRIC_EXPORT_INTERVAL_MS || 15000),
+                });
+            }
+            const serviceName = process.env.OTEL_SERVICE_NAME || "bash-command-mcp";
+            const serviceVersion = process.env.OTEL_SERVICE_VERSION || "1.0.0";
+            const resource = new resourceCtor({
+                "service.name": serviceName,
+                "service.version": serviceVersion,
+            });
+            this.sdk = new nodeSdkCtor({
+                resource,
+                traceExporter,
+                metricReader,
+            });
+            await this.sdk.start();
+            this.tracer = otelApi.trace.getTracer(serviceName, serviceVersion);
+            const meter = otelApi.metrics.getMeter(serviceName, serviceVersion);
+            this.spanStatusCodeError = otelApi.SpanStatusCode.ERROR;
+            this.toolCalls = meter.createCounter("mcp_tool_calls_total", {
+                description: "Total MCP tool invocations",
+            });
+            this.toolFailures = meter.createCounter("mcp_tool_failures_total", {
+                description: "Total failed MCP tool invocations",
+            });
+            this.toolTimeouts = meter.createCounter("mcp_tool_timeouts_total", {
+                description: "Total timed out MCP tool invocations",
+            });
+            this.toolDuration = meter.createHistogram("mcp_tool_duration_ms", {
+                description: "MCP tool execution duration",
+                unit: "ms",
+            });
+            this.bgStarted = meter.createCounter("mcp_background_started_total", {
+                description: "Total started background processes",
+            });
+            this.bgEnded = meter.createCounter("mcp_background_ended_total", {
+                description: "Total ended background processes",
+            });
+            this.status = {
+                enabled: true,
+                reason: "active",
+                serviceName,
+                exporter: exporterName,
+            };
+        }
+        catch (error) {
+            this.status = {
+                enabled: false,
+                reason: `otel_unavailable: ${getErrorMessage(error)}`,
+                serviceName: process.env.OTEL_SERVICE_NAME || "bash-command-mcp",
+                exporter: "none",
+            };
+        }
+    }
+    getStatus() {
+        return this.status;
+    }
+    toolSpan(name, attrs = {}) {
+        if (!this.tracer) {
+            return new NoopToolSpan();
+        }
+        const startedAt = process.hrtime.bigint();
+        const span = this.tracer.startSpan(`mcp.tool.${name}`, {
+            attributes: sanitizeAttributes({
+                "mcp.tool.name": name,
+                ...attrs,
+            }),
+        });
+        this.toolCalls?.add(1, { tool: name });
+        return {
+            setAttribute: (key, value) => span.setAttribute(key, value),
+            addEvent: (eventName, eventAttrs) => {
+                span.addEvent(eventName, sanitizeAttributes(eventAttrs || {}));
+            },
+            recordException: (error) => {
+                if (error instanceof Error) {
+                    span.recordException(error);
+                }
+                else {
+                    span.recordException(new Error(getErrorMessage(error)));
+                }
+            },
+            end: (ok, endAttrs = {}) => {
+                const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+                this.toolDuration?.record(durationMs, { tool: name, ok: String(ok) });
+                if (!ok) {
+                    this.toolFailures?.add(1, { tool: name });
+                    if (this.spanStatusCodeError !== null) {
+                        span.setStatus({
+                            code: this.spanStatusCodeError,
+                        });
+                    }
+                }
+                const finalAttrs = sanitizeAttributes(endAttrs);
+                for (const [k, v] of Object.entries(finalAttrs)) {
+                    span.setAttribute(k, v);
+                }
+                span.end();
+            },
+        };
+    }
+    markTimeout(toolName) {
+        this.toolTimeouts?.add(1, { tool: toolName });
+    }
+    backgroundEvent(event, attrs = {}) {
+        const span = this.tracer?.startSpan(`mcp.background.${event}`, {
+            attributes: sanitizeAttributes(attrs),
+        });
+        if (event === "started") {
+            this.bgStarted?.add(1);
+        }
+        if (event === "ended") {
+            this.bgEnded?.add(1);
+        }
+        span?.end();
+    }
+    async shutdown() {
+        if (!this.sdk)
+            return;
+        await this.sdk.shutdown();
+    }
+}

package/dist/src/shell.js

@@ -0,0 +1,70 @@
+import { spawn } from "node:child_process";
+function isWindows() {
+    return process.platform === "win32";
+}
+export function normalizeCommand(command, cmd) {
+    const normalized = (Array.isArray(command)
+        ? command.join(" ")
+        : Array.isArray(cmd)
+            ? cmd.join(" ")
+            : (command ?? cmd))?.trim();
+    return normalized || null;
+}
+export function terminateProcess(pid) {
+    if (!isWindows()) {
+        process.kill(-pid, "SIGTERM");
+        return;
+    }
+    process.kill(pid, "SIGTERM");
+}
+export async function runForegroundCommand(command, timeoutSeconds, overrides) {
+    return await new Promise((resolve) => {
+        const child = spawn(command, {
+            shell: true,
+            detached: !isWindows(),
+            cwd: overrides.cwd,
+            env: overrides.env ? { ...process.env, ...overrides.env } : process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                if (child.pid)
+                    terminateProcess(child.pid);
+                else
+                    child.kill("SIGTERM");
+            }
+            catch {
+                child.kill("SIGTERM");
+            }
+        }, timeoutSeconds * 1000);
+        child.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: null,
+                stdout,
+                stderr,
+                timedOut,
+                errorMessage: error.message,
+            });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode: typeof code === "number" ? code : null,
+                stdout,
+                stderr,
+                timedOut,
+                errorMessage: null,
+            });
+        });
+    });
+}

package/dist/src/tools.js

@@ -0,0 +1,348 @@
+import { z } from "zod";
+import { normalizeCommand, runForegroundCommand, } from "./shell.js";
+import { getErrorMessage } from "./error-utils.js";
+const commandSchema = z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .describe("Command as a string or string array.");
+const envSchema = z
+    .record(z.string(), z.string())
+    .optional()
+    .describe("Environment variable overrides for the command.");
+function formatCommandResult(exitCode, stdout, stderr, fallback) {
+    let output = `EXIT_CODE: ${exitCode}\n`;
+    if (stdout)
+        output += `STDOUT:\n${stdout}\n`;
+    if (stderr)
+        output += `STDERR:\n${stderr}\n`;
+    return output.trim() || `EXIT_CODE: ${exitCode}\n${fallback}`;
+}
+function formatBackgroundView(view) {
+    return [
+        `PID: ${view.pid}`,
+        `STATUS: ${view.status}`,
+        `EXIT_CODE: ${view.exitCode ?? "N/A"}`,
+        `SIGNAL: ${view.signal ?? "N/A"}`,
+        `STARTED_AT: ${view.startedAt}`,
+        `ENDED_AT: ${view.endedAt ?? "N/A"}`,
+        `CWD: ${view.cwd}`,
+        `STDOUT_LOG: ${view.stdoutLogPath}`,
+        `STDERR_LOG: ${view.stderrLogPath}`,
+        `COMMAND: ${view.command}`,
+        view.error ? `ERROR: ${view.error}` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function resolveOverrides(cwd, env) {
+    return { cwd, env };
+}
+export function registerTools(server, backgroundManager, observability) {
+    server.registerTool("run", {
+        description: "Run a shell command in the foreground and return stdout/stderr with exit code.",
+        inputSchema: {
+            command: commandSchema,
+            cmd: commandSchema,
+            timeoutSeconds: z
+                .number()
+                .int()
+                .min(1)
+                .max(24 * 3600)
+                .default(60)
+                .describe("Execution timeout in seconds. Default 60."),
+            cwd: z.string().optional().describe("Working directory override."),
+            env: envSchema,
+        },
+    }, async ({ command, cmd, timeoutSeconds, cwd, env }) => {
+        const span = observability.toolSpan("run", {
+            "mcp.command.cwd": cwd,
+            "mcp.command.timeout_seconds": timeoutSeconds,
+        });
+        try {
+            const normalizedCommand = normalizeCommand(command, cmd);
+            if (!normalizedCommand) {
+                span.end(false, { "mcp.command.valid": false });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: 'EXIT_CODE: unknown\nEither "command" or "cmd" must be provided.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            span.setAttribute("mcp.command.value", normalizedCommand);
+            const result = await runForegroundCommand(normalizedCommand, timeoutSeconds, resolveOverrides(cwd, env));
+            if (result.errorMessage) {
+                span.recordException(new Error(result.errorMessage));
+                span.end(false, {
+                    "mcp.command.status": "spawn_error",
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatCommandResult("unknown", result.stdout, result.stderr, `Command failed with error:\n${result.errorMessage}`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const exitCode = typeof result.exitCode === "number"
+                ? String(result.exitCode)
+                : "unknown";
+            const timedOutMessage = result.timedOut
+                ? `Command timed out after ${timeoutSeconds} second(s).`
+                : "No output returned.";
+            if (result.timedOut) {
+                observability.markTimeout("run");
+            }
+            const ok = !result.timedOut && result.exitCode === 0;
+            span.end(ok, {
+                "mcp.command.exit_code": typeof result.exitCode === "number" ? result.exitCode : -1,
+                "mcp.command.timed_out": result.timedOut,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatCommandResult(exitCode, result.stdout, result.stderr, timedOutMessage),
+                    },
+                ],
+                isError: !ok,
+            };
+        }
+        catch (error) {
+            span.recordException(error);
+            span.end(false, { "mcp.command.status": "exception" });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `EXIT_CODE: unknown\nUnexpected error:\n${getErrorMessage(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("run_background", {
+        description: "Start a shell command in the background and capture stdout/stderr to log files.",
+        inputSchema: {
+            command: commandSchema,
+            cmd: commandSchema,
+            cwd: z.string().optional().describe("Working directory override."),
+            env: envSchema,
+        },
+    }, async ({ command, cmd, cwd, env }) => {
+        const span = observability.toolSpan("run_background", {
+            "mcp.command.cwd": cwd,
+        });
+        try {
+            const normalizedCommand = normalizeCommand(command, cmd);
+            if (!normalizedCommand) {
+                span.end(false, { "mcp.command.valid": false });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: 'Either "command" or "cmd" must be provided.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            span.setAttribute("mcp.command.value", normalizedCommand);
+            const started = backgroundManager.start(normalizedCommand, resolveOverrides(cwd, env));
+            span.end(true, {
+                "mcp.command.pid": started.pid,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Started background process.\n${formatBackgroundView(started)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            span.recordException(error);
+            span.end(false);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to start background process:\n${getErrorMessage(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("list_background", {
+        description: "List tracked background processes and their status/log paths.",
+        inputSchema: {},
+    }, async () => {
+        const span = observability.toolSpan("list_background");
+        const entries = backgroundManager.list();
+        span.end(true, {
+            "mcp.background.count": entries.length,
+        });
+        if (entries.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No tracked background processes.",
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: entries
+                        .map((entry) => formatBackgroundView(entry))
+                        .join("\n\n"),
+                },
+            ],
+        };
+    });
+    server.registerTool("kill_background", {
+        description: "Stop a tracked background process by PID.",
+        inputSchema: {
+            pid: z
+                .number()
+                .int()
+                .positive()
+                .describe("PID of the process to stop."),
+        },
+    }, async ({ pid }) => {
+        const span = observability.toolSpan("kill_background", {
+            "mcp.command.pid": pid,
+        });
+        const result = backgroundManager.kill(pid);
+        span.end(result.ok, {
+            "mcp.command.status": result.ok ? "ok" : "error",
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.view
+                        ? `${result.message}\n${formatBackgroundView(result.view)}`
+                        : result.message,
+                },
+            ],
+            isError: !result.ok,
+        };
+    });
+    server.registerTool("tail_background", {
+        description: "Read the last N lines from stdout/stderr logs for a tracked background process.",
+        inputSchema: {
+            pid: z.number().int().positive().describe("PID to inspect."),
+            lines: z
+                .number()
+                .int()
+                .min(1)
+                .max(5000)
+                .default(200)
+                .describe("Number of lines to read from the end of each log."),
+        },
+    }, async ({ pid, lines }) => {
+        const span = observability.toolSpan("tail_background", {
+            "mcp.command.pid": pid,
+            "mcp.command.tail_lines": lines,
+        });
+        const result = await backgroundManager.tail(pid, lines);
+        if (!result.ok || !result.view) {
+            span.end(false);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result.message,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        span.end(true, {
+            "mcp.command.status": result.view.status,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        result.message,
+                        formatBackgroundView(result.view),
+                        `STDOUT_TAIL:\n${result.stdout || "<empty>"}`,
+                        `STDERR_TAIL:\n${result.stderr || "<empty>"}`,
+                    ].join("\n\n"),
+                },
+            ],
+        };
+    });
+    server.registerTool("wait_background", {
+        description: "Wait for a tracked background process to finish and return final status.",
+        inputSchema: {
+            pid: z.number().int().positive().describe("PID to wait on."),
+            timeoutSeconds: z
+                .number()
+                .int()
+                .min(1)
+                .max(24 * 3600)
+                .default(60)
+                .describe("How long to wait before returning timeout."),
+        },
+    }, async ({ pid, timeoutSeconds }) => {
+        const span = observability.toolSpan("wait_background", {
+            "mcp.command.pid": pid,
+            "mcp.command.timeout_seconds": timeoutSeconds,
+        });
+        const result = await backgroundManager.wait(pid, timeoutSeconds);
+        if (!result.view) {
+            span.end(false, { "mcp.command.status": "missing_process" });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result.message,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (result.timedOut) {
+            observability.markTimeout("wait_background");
+        }
+        const logs = await backgroundManager.readLogs(pid);
+        const failed = !result.ok ||
+            result.timedOut ||
+            (typeof result.view.exitCode === "number" &&
+                result.view.exitCode !== 0);
+        span.end(!failed, {
+            "mcp.command.status": result.view.status,
+            "mcp.command.exit_code": result.view.exitCode ?? -1,
+            "mcp.command.timed_out": result.timedOut,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        result.message,
+                        formatBackgroundView(result.view),
+                        `STDOUT:\n${logs?.stdout?.trim() || "<empty>"}`,
+                        `STDERR:\n${logs?.stderr?.trim() || "<empty>"}`,
+                    ].join("\n\n"),
+                },
+            ],
+            isError: failed,
+        };
+    });
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "bash-command-mcp",
+  "version": "0.1.0",
+  "description": "Sophisticated bash command MCP server that runs and manages shell execution.",
+  "license": "MIT",
+  "homepage": "https://github.com/mrorigo/bash-command-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/mrorigo/bash-command-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrorigo/bash-command-mcp.git"
+  },
+  "main": "./dist/index.js",
+  "bin": {
+    "bash-command-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "Dockerfile",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bash",
+    "cli",
+    "stdio",
+    "server"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "start": "node dist/index.js",
+    "dev": "bun run --watch index.ts",
+    "lint": "oxlint -D typescript/no-explicit-any .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "mcpName": "io.github.mrorigo/bash-command-mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "oxlint": "^1.48.0",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.57.2",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.2",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-metrics": "^1.30.1",
+    "@opentelemetry/sdk-node": "^0.57.2",
+    "@opentelemetry/sdk-trace-base": "^1.30.1"
+  }
+}