Smart Shell MCP Server

# smart-shell (MCP Server) [](https://www.npmjs.com/package/smart-shell-mcp) [](https://github.com/mr-wolf-gb/smart-shell-mcp/actions/workflows/ci.yml) [](https://nodejs.org/) [](https://opensource.org/licenses/GPL-3.0) [](https://modelcontextprotocol.io/) MCP Tool Server – Cross-Platform & Project-Aware Command Runner. This server exposes tools that execute shell commands in an OS-aware way and adapt to each project's preferred package/runtime manager (npm ↔ bun, pip ↔ poetry, etc.). Agents can read and modify per-project command mappings at runtime. ## Features - OS-aware command translation (e.g., `ls` → `dir` on Windows). - Project-specific overrides stored in `src/project-commands.json` and editable via tools. - Execute mapped commands with additional args and return `{ stdout, stderr, exitCode }`. - Structured error objects with actionable suggestions when a command fails. - Tools: `executeCommand`, `getProjectCommands`, `setProjectCommand`, `removeProjectCommand`, `translateCommand`. ## Requirements - Node.js 18+ (20+ recommended) ## Install ```bash # Dev (inside this repo) npm install # Production (global CLI) npm install -g smart-shell-mcp # or per-project without global install npx smart-shell-mcp ``` ## Run - Dev (no build): ```bash npx tsx src/server.ts ``` - Build + run: ```bash npm run build npm start ``` This starts an MCP server over stdio. Point your MCP-compatible client at the command above. ## Configuration Files - `src/command-map.json`: base translation from generic commands → per-OS variants. Example: ```json { "base": { "ls": { "windows": "dir", "linux": "ls", "darwin": "ls" }, "open": { "windows": "start", "linux": "xdg-open", "darwin": "open" } } } ``` - `src/project-commands.json`: project-specific command overrides. Example: ```json { "default": { "install": "npm install", "run": "npm start" }, "my-bun-project": { "install": "bun install", "run": "bun run dev" }, "python-api": { "install": "pip install -r requirements.txt", "run": "uvicorn app:app --reload" } } ``` Files are looked up in the current working directory first. If not found, the copies in `src/` are used and will be created automatically if missing. ## Tools - `executeCommand({ projectName, commandKey, args?, options? })` - Resolve project override → fallback to `default` → translate for OS → run. - `options` (all optional): - `shell`: `auto | cmd | powershell | bash` - `activateVenv`: `auto | on | off` - `venvPath`: path to a venv root if not `.venv`/`venv` - `cwd`: working directory for the command - `env`: key/value environment overrides - Returns on success: ```json { "stdout": "...", "stderr": "", "exitCode": 0, "resolvedCommand": "npm install" } ``` - On failure returns structured error inside the tool result body (not thrown): ```json { "errorCode": "COMMAND_FAILED", "message": "Command failed with exit code 1", "suggestion": "poetry install", "resolvedCommand": "pip install -r requirements.txt", "stdout": "...", "stderr": "...", "exitCode": 1 } ``` - `getProjectCommands({ projectName })` → merged view `{ ...default, ...project }`. - `setProjectCommand({ projectName, key, value })` → upsert and persist. - `removeProjectCommand({ projectName, key })` → delete and persist. - `translateCommand({ rawCommand })` → `{ os, original, translated }`. ## Error Handling & Suggestions When a command exits non‑zero the server embeds a structured error with optional suggestions, e.g.: - If `npm` fails and the workspace looks like a Bun project (`bun.lockb` or `package.json: { packageManager: "bun@..." }`), suggestion: `bun install` (or `bun run dev` for `run`). - If `pip` fails and `poetry.lock` or `[tool.poetry]` in `pyproject.toml` is present, suggestion: `poetry install`. - Also detects Yarn (`yarn.lock`) and pnpm (`pnpm-lock.yaml`). ## MCP JSON-RPC Examples All examples assume stdio transport. - List tools: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } ``` - Call `executeCommand`: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "executeCommand", "arguments": { "projectName": "python-api", "commandKey": "install", "args": ["-q"] } } } ``` - Call `setProjectCommand`: ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "setProjectCommand", "arguments": { "projectName": "my-bun-project", "key": "lint", "value": "bun run lint" } } } ``` ## IDE Integration (Production) After installing globally (`npm i -g smart-shell-mcp`), configure your IDE to run the `smart-shell` executable over stdio. - Cursor, Kiro, Windsurf (example) ```json { "mcpServers": { "smart-shell": { "command": "npx", "args": [ "-y", "smart-shell-mcp" ], "env": {} } } } ``` Or ```json { "mcpServers": { "smart-shell": { "command": "smart-shell", "args": [], "env": {} } } } ``` - Claude Desktop (reference) ```json { "mcpServers": { "smart-shell": { "command": "smart-shell" } } } ``` Notes - If you prefer not to install globally, replace `smart-shell` with `npx smart-shell-mcp` in the examples above. - Windows users can switch to PowerShell execution with the tool options (see below) if needed. ## Project Scripts - `npm run dev` – start in dev (tsx) - `npm run build` – build TypeScript to `dist/` - `npm start` – run compiled server - `npm run typecheck` – TypeScript type checking **Made with ❤️ by [Mr-Wolf-GB](https://github.com/mr-wolf-gb) for the MCP community**