smart-shell (MCP Server)

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

Run

• Dev (no build):

• Build + run:

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:

• src/project-commands.json: project-specific command overrides. Example:

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:

    { "stdout": "...", "stderr": "", "exitCode": 0, "resolvedCommand": "npm install" }

  • On failure returns structured error inside the tool result body (not thrown):

    { "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:

• Call executeCommand:

• Call setProjectCommand:

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)

Or

• Claude Desktop (reference)

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