mcp-terminal-runner 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# MCP Terminal Runner
+
+An MCP server that allows AI agents to execute terminal commands on the host system.
+
+## Features
+
+- **Execute Command**: Run shell commands and retrieve stdout, stderr, and exit code.
+- **Security**: Strict allowlist system via `ALLOWED_COMMANDS` environment variable.
+- **Cross-Platform**: Works on Linux, macOS, and Windows.
+
+## Prerequisites
+
+- Node.js (version 18 or higher)
+
+## Configuration
+
+### Security: Allowed Commands
+
+For security reasons, this server requires an explicit list of allowed commands. This is configured via the `ALLOWED_COMMANDS` environment variable.
+
+- **Format**: Comma-separated list of command binaries (e.g., `ls,cat,echo`).
+- **Wildcard**: Set to `*` to allow ALL commands (⚠️ **DANGEROUS**: Only use in trusted environments).
+
+### Security (Optional): Allowed Working Directory Roots
+
+If you enable `cwd` (see tool input below), you can optionally restrict which working directories are allowed via `ALLOWED_CWD_ROOTS`.
+
+- **Format**: Comma-separated list of allowed root paths.
+- **Behavior**:
+  - If **unset or empty**, `cwd` is not restricted (any existing directory is allowed).
+  - If set, the resolved and canonical `cwd` must be within at least one configured root.
+  - If set and any configured root cannot be canonicalized (e.g., does not exist), requests that provide `cwd` are rejected (configuration error).
+
+## Usage
+
+### MCP Client Configuration
+
+Add the following to your MCP client configuration (e.g., VS Code `settings.json`):
+
+#### Basic Configuration
+
+```json
+{
+  "mcpServers": {
+    "terminal-runner": {
+      "command": "npx",
+      "args": ["-y", "mcp-terminal-runner"],
+      "env": {
+        "ALLOWED_COMMANDS": "ls,cat,grep,echo"
+      }
+    }
+  }
+}
+```
+
+#### Configuration with Allowed Working Directories
+
+```json
+{
+  "mcpServers": {
+    "terminal-runner": {
+      "command": "npx",
+      "args": ["-y", "mcp-terminal-runner"],
+      "env": {
+        "ALLOWED_COMMANDS": "ls,cat,grep,echo",
+        "ALLOWED_CWD_ROOTS": "/home/user/projects,/tmp"
+      }
+    }
+  }
+}
+```
+
+### Available Tools
+
+#### `execute_command`
+Executes a shell command.
+
+- **Input**:
+  - `command` (string): The full command string to execute (e.g., `ls -la src`).
+  - `cwd` (string, optional): Working directory to execute the command within.
+- **Output**:
+  - Returns a YAML-formatted string containing:
+    - `exit_code`: The command's exit code.
+    - `stdout`: Standard output.
+    - `stderr`: Standard error.
+
+## Development
+
+### Setup
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd mcp-terminal-runner
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the project:
+```bash
+npm run build
+```
+
+### Available Scripts
+
+- `npm run build` - Build the TypeScript project
+- `npm run dev` - Run in development mode
+- `npm start` - Run the built JavaScript version
+- `npm run check` - Check code with Ultracite
+- `npm test` - Run tests with Vitest
+
+### Project Structure
+
+```
+mcp-terminal-runner/
+├── src/
+│   └── index.ts          # Main server implementation
+├── dist/                 # Built JavaScript files
+├── .husky/              # Git hooks
+├── biome.json           # Biome configuration
+├── tsconfig.json        # TypeScript configuration
+├── package.json         # Project dependencies and scripts
+└── README.md           # This file
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `npm run quality` to ensure code quality
+5. Commit your changes (Husky will run pre-commit hooks)
+6. Push to your branch
+7. Create a Pull Request
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Server not starting**: Ensure all dependencies are installed and the project is built
+2. **Tools not appearing**: Check that the MCP client configuration points to the correct path
+3. **Permission errors**: Make sure the built JavaScript file has execute permissions
+
+### Debug Mode
+
+To enable debug logging, set the environment variable:
+```bash
+DEBUG=mcp* npm start
+```

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+declare const server: McpServer;
+export { server };
+//# 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":";AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASpE,QAAA,MAAM,MAAM,WAUX,CAAC;AAwLF,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.server = void 0;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const args_tokenizer_1 = require("args-tokenizer");
+const js_yaml_1 = require("js-yaml");
+const zod_1 = require("zod");
+// Hardcoded version to avoid import issues with outside rootDir
+const version = '0.1.0';
+const server = new mcp_js_1.McpServer({
+    name: 'mcp-terminal-runner',
+    version,
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+exports.server = server;
+const parseCommaSeparatedEnv = (value) => {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+};
+const isWithinRoot = (root, target) => {
+    const rel = (0, node_path_1.relative)(root, target);
+    if (rel === '') {
+        return true;
+    }
+    const isOutsideRoot = rel.startsWith('..') || (0, node_path_1.isAbsolute)(rel);
+    return !isOutsideRoot;
+};
+const resolveAndValidateCwd = async (cwdInput) => {
+    const cwdResolved = (0, node_path_1.resolve)(process.cwd(), cwdInput);
+    try {
+        const cwdStat = await (0, promises_1.stat)(cwdResolved);
+        if (!cwdStat.isDirectory()) {
+            throw new Error(`cwd is not a directory: ${cwdInput}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.includes('cwd is not a directory')) {
+            throw error;
+        }
+        throw new Error(`cwd does not exist: ${cwdInput}`);
+    }
+    const cwdCanonical = await (0, promises_1.realpath)(cwdResolved);
+    const allowedRoots = parseCommaSeparatedEnv(process.env.ALLOWED_CWD_ROOTS);
+    if (allowedRoots.length === 0) {
+        return cwdResolved;
+    }
+    const canonicalRoots = await Promise.all(allowedRoots.map(async (root) => {
+        const rootResolved = (0, node_path_1.resolve)(process.cwd(), root);
+        try {
+            return await (0, promises_1.realpath)(rootResolved);
+        }
+        catch {
+            throw new Error(`Invalid configuration: ALLOWED_CWD_ROOTS contains an invalid root: ${root}`);
+        }
+    }));
+    const allowed = canonicalRoots.some((root) => isWithinRoot(root, cwdCanonical));
+    if (!allowed) {
+        throw new Error('cwd is not allowed by ALLOWED_CWD_ROOTS');
+    }
+    return cwdResolved;
+};
+const runCommand = async (bin, args, cwd) => new Promise((resolvePromise, rejectPromise) => {
+    const child = (0, node_child_process_1.spawn)(bin, args, {
+        cwd,
+        shell: false,
+        windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderr += chunk;
+    });
+    child.on('error', (error) => {
+        rejectPromise(error);
+    });
+    child.on('close', (code) => {
+        resolvePromise({
+            exitCode: typeof code === 'number' ? code : 1,
+            stdout,
+            stderr,
+        });
+    });
+});
+server.tool('execute_command', 'Execute a shell command', {
+    command: zod_1.z.string().describe('The shell command to execute'),
+    cwd: zod_1.z
+        .string()
+        .optional()
+        .describe('Optional working directory to execute the command within'),
+}, async (args) => {
+    const [bin, ...commandArgs] = (0, args_tokenizer_1.tokenizeArgs)(args.command);
+    const allowedCommands = parseCommaSeparatedEnv(process.env.ALLOWED_COMMANDS);
+    try {
+        if (!(allowedCommands.includes('*') || allowedCommands.includes(bin))) {
+            throw new Error(`Command "${bin}" is not allowed, allowed commands: ${allowedCommands.length > 0 ? allowedCommands.join(', ') : '(none)'}`);
+        }
+        const cwdResolved = args.cwd
+            ? await resolveAndValidateCwd(args.cwd)
+            : undefined;
+        const result = await runCommand(bin, commandArgs, cwdResolved);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: (0, js_yaml_1.dump)({
+                        exit_code: result.exitCode,
+                        stdout: result.stdout,
+                        stderr: result.stderr,
+                    }),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error executing command: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error('Fatal error in main:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
+const js_yaml_1 = require("js-yaml");
+const index_js_2 = require("./index.js");
+describe('MCP Server', () => {
+    let client;
+    beforeEach(async () => {
+        const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+        // Connect server
+        await index_js_2.server.connect(serverTransport);
+        // Connect client
+        client = new index_js_1.Client({ name: 'test-client', version: '1.0.0' }, { capabilities: {} });
+        await client.connect(clientTransport);
+    });
+    afterEach(async () => {
+        await client.close();
+        await index_js_2.server.close();
+        process.env.ALLOWED_COMMANDS = '';
+        process.env.ALLOWED_CWD_ROOTS = '';
+    });
+    it('should list execute_command tool', async () => {
+        const result = await client.listTools();
+        expect(result.tools).toBeDefined();
+        expect(result.tools.some((t) => t.name === 'execute_command')).toBe(true);
+    });
+    it('should execute allowed command', async () => {
+        process.env.ALLOWED_COMMANDS = 'echo';
+        const result = await client.callTool({
+            name: 'execute_command',
+            arguments: { command: 'echo hello' },
+        });
+        expect(result.content).toBeDefined();
+        expect(result.content[0].type).toBe('text');
+        const text = result.content[0].text;
+        const output = (0, js_yaml_1.load)(text);
+        expect(output.exit_code).toBe(0);
+        expect(output.stdout).toContain('hello');
+    });
+    it('should fail for disallowed command', async () => {
+        process.env.ALLOWED_COMMANDS = 'ls';
+        const result = await client.callTool({
+            name: 'execute_command',
+            arguments: { command: 'echo hello' },
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('not allowed');
+    });
+    it('should allow all commands with wildcard', async () => {
+        process.env.ALLOWED_COMMANDS = '*';
+        const result = await client.callTool({
+            name: 'execute_command',
+            arguments: { command: 'echo hello' },
+        });
+        expect(result.content).toBeDefined();
+        const text = result.content[0].text;
+        const output = (0, js_yaml_1.load)(text);
+        expect(output.exit_code).toBe(0);
+    });
+    it('should execute command within absolute cwd', async () => {
+        process.env.ALLOWED_COMMANDS = 'node';
+        const cwdDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'mcp-terminal-runner-cwd-'));
+        const result = await client.callTool({
+            name: 'execute_command',
+            arguments: {
+                command: 'node -p process.cwd()',
+                cwd: cwdDir,
+            },
+        });
+        if (result.isError) {
+            const message = result.content?.[0]?.text ?? 'unknown error';
+            throw new Error(message);
+        }
+        expect(result.isError).not.toBe(true);
+        const text = result.content[0].text;
+        const output = (0, js_yaml_1.load)(text);
+        expect(output.exit_code).toBe(0);
+        expect(String(output.stdout)).toContain(cwdDir);
+    });
+    it('should execute command within relative cwd', async () => {
+        process.env.ALLOWED_COMMANDS = 'node';
+        const baseDir = (0, node_path_1.join)(process.cwd(), '.tmp');
+        await (0, promises_1.mkdir)(baseDir, { recursive: true });
+        const cwdDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)(baseDir, 'mcp-terminal-runner-cwd-rel-'));
+        const relativeCwd = (0, node_path_1.relative)(process.cwd(), cwdDir);
+        const result = await client.callTool({
+            name: 'execute_command',
+            arguments: {
+                command: 'node -p process.cwd()',
+                cwd: relativeCwd,
+            },
+        });
+        if (result.isError) {
+            const message = result.content?.[0]?.text ?? 'unknown error';
+            throw new Error(message);
+        }
+        expect(result.isError).not.toBe(true);
+        const text = result.content[0].text;
+        const output = (0, js_yaml_1.load)(text);
+        expect(output.exit_code).toBe(0);
+        expect(String(output.stdout)).toContain(cwdDir);
+    });
+    it('should fail when cwd does not exist', async () => {
+        process.env.ALLOWED_COMMANDS = 'node';
+        const result = await client.callTool({
+            name: 'execute_command',
+            arguments: {
+                command: 'node -p process.cwd()',
+                cwd: 'does-not-exist',
+            },
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('cwd does not exist');
+    });
+    it('should restrict cwd when ALLOWED_CWD_ROOTS is set', async () => {
+        process.env.ALLOWED_COMMANDS = 'node';
+        const rootDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'mcp-terminal-runner-root-'));
+        const childDir = (0, node_path_1.join)(rootDir, 'frontend');
+        await (0, promises_1.mkdir)(childDir, { recursive: true });
+        process.env.ALLOWED_CWD_ROOTS = rootDir;
+        const allowedResult = await client.callTool({
+            name: 'execute_command',
+            arguments: {
+                command: 'node -p process.cwd()',
+                cwd: childDir,
+            },
+        });
+        expect(allowedResult.isError).not.toBe(true);
+        const allowedText = allowedResult.content[0].text;
+        const allowedOutput = (0, js_yaml_1.load)(allowedText);
+        expect(allowedOutput.exit_code).toBe(0);
+        expect(String(allowedOutput.stdout)).toContain(childDir);
+        const disallowedResult = await client.callTool({
+            name: 'execute_command',
+            arguments: {
+                command: 'node -p process.cwd()',
+                cwd: (0, node_os_1.tmpdir)(),
+            },
+        });
+        expect(disallowedResult.isError).toBe(true);
+        expect(disallowedResult.content[0].text).toContain('ALLOWED_CWD_ROOTS');
+    });
+    it('should fail with configuration error when ALLOWED_CWD_ROOTS contains invalid root', async () => {
+        process.env.ALLOWED_COMMANDS = 'node';
+        const rootDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'mcp-terminal-runner-root-invalid-'));
+        const childDir = (0, node_path_1.join)(rootDir, 'frontend');
+        await (0, promises_1.mkdir)(childDir, { recursive: true });
+        process.env.ALLOWED_CWD_ROOTS = `${rootDir},${(0, node_path_1.join)(rootDir, 'does-not-exist')}`;
+        const result = await client.callTool({
+            name: 'execute_command',
+            arguments: {
+                command: 'node -p process.cwd()',
+                cwd: childDir,
+            },
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Invalid configuration');
+        expect(result.content[0].text).toContain('ALLOWED_CWD_ROOTS');
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mcp-terminal-runner",
+  "version": "0.1.0",
+  "main": "index.js",
+  "bin": {
+    "mcp-terminal-runner": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "typecheck": "tsc --noEmit",
+    "quality": "npm run typecheck && npm run check",
+    "test": "vitest --run",
+    "prepare": "husky"
+  },
+  "author": "atman-33",
+  "license": "MIT",
+  "description": "MCP server for executing shell commands safely",
+  "files": [
+    "dist",
+    "README.md",
+    "package.json",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.3.0",
+    "husky": "^9.1.7",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.2",
+    "ultracite": "^6.4.2",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "args-tokenizer": "^0.3.0",
+    "js-yaml": "^4.1.1",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
+  }
+}