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

# 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):

npx tsx src/server.ts

• Build + run:

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:

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

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

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

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

• Call executeCommand:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "executeCommand",
    "arguments": {
      "projectName": "python-api",
      "commandKey": "install",
      "args": ["-q"]
    }
  }
}

• Call setProjectCommand:

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

{
  "mcpServers": {
    "smart-shell": {
      "command": "npx",
      "args": [
        "-y",
        "smart-shell-mcp"
      ],
      "env": {}
    }
  }
}

Or

{
  "mcpServers": {
    "smart-shell": {
      "command": "smart-shell",
      "args": [],
      "env": {}
    }
  }
}

• Claude Desktop (reference)

{
  "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 for the MCP community