{"id":30901384,"url":"https://github.com/mr-wolf-gb/smart-shell-mcp","last_synced_at":"2026-01-20T16:48:10.127Z","repository":{"id":313356143,"uuid":"1051091618","full_name":"mr-wolf-gb/smart-shell-mcp","owner":"mr-wolf-gb","description":"MCP Tool Server – Cross-Platform \u0026 Project-Aware Command Runner.","archived":false,"fork":false,"pushed_at":"2025-09-06T07:18:24.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-22T01:52:39.497Z","etag":null,"topics":["agentic-ai","ai","bash","cmd","linux","mcp-server","python","shell","tool","windows"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mr-wolf-gb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T12:33:53.000Z","updated_at":"2025-09-06T07:18:27.000Z","dependencies_parsed_at":"2025-09-05T15:31:25.453Z","dependency_job_id":null,"html_url":"https://github.com/mr-wolf-gb/smart-shell-mcp","commit_stats":null,"previous_names":["mr-wolf-gb/smart-shell-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mr-wolf-gb/smart-shell-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-wolf-gb%2Fsmart-shell-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-wolf-gb%2Fsmart-shell-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-wolf-gb%2Fsmart-shell-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-wolf-gb%2Fsmart-shell-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mr-wolf-gb","download_url":"https://codeload.github.com/mr-wolf-gb/smart-shell-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mr-wolf-gb%2Fsmart-shell-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28132549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-30T02:00:05.476Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai","bash","cmd","linux","mcp-server","python","shell","tool","windows"],"created_at":"2025-09-09T06:57:11.320Z","updated_at":"2025-12-30T21:06:47.820Z","avatar_url":"https://github.com/mr-wolf-gb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# smart-shell (MCP Server)\n\n[![npm version](https://img.shields.io/npm/v/smart-shell-mcp)](https://www.npmjs.com/package/smart-shell-mcp)\n[![CI](https://github.com/mr-wolf-gb/smart-shell-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mr-wolf-gb/smart-shell-mcp/actions/workflows/ci.yml) \n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)\n\nMCP Tool Server – Cross-Platform \u0026 Project-Aware Command Runner.\n\nThis 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.\n\n## Features\n\n- OS-aware command translation (e.g., `ls` → `dir` on Windows). \n- Project-specific overrides stored in `src/project-commands.json` and editable via tools.\n- Execute mapped commands with additional args and return `{ stdout, stderr, exitCode }`.\n- Structured error objects with actionable suggestions when a command fails.\n- Tools: `executeCommand`, `getProjectCommands`, `setProjectCommand`, `removeProjectCommand`, `translateCommand`.\n\n## Requirements\n\n- Node.js 18+ (20+ recommended)\n\n## Install\n\n```bash\n# Dev (inside this repo)\nnpm install\n\n# Production (global CLI)\nnpm install -g smart-shell-mcp\n# or per-project without global install\nnpx smart-shell-mcp\n```\n\n## Run\n\n- Dev (no build):\n\n```bash\nnpx tsx src/server.ts\n```\n\n- Build + run:\n\n```bash\nnpm run build\nnpm start\n```\n\nThis starts an MCP server over stdio. Point your MCP-compatible client at the command above.\n\n## Configuration Files\n\n- `src/command-map.json`: base translation from generic commands → per-OS variants. Example:\n\n```json\n{\n  \"base\": {\n    \"ls\": { \"windows\": \"dir\", \"linux\": \"ls\", \"darwin\": \"ls\" },\n    \"open\": { \"windows\": \"start\", \"linux\": \"xdg-open\", \"darwin\": \"open\" }\n  }\n}\n```\n\n- `src/project-commands.json`: project-specific command overrides. Example:\n\n```json\n{\n  \"default\": {\n    \"install\": \"npm install\",\n    \"run\": \"npm start\"\n  },\n  \"my-bun-project\": {\n    \"install\": \"bun install\",\n    \"run\": \"bun run dev\"\n  },\n  \"python-api\": {\n    \"install\": \"pip install -r requirements.txt\",\n    \"run\": \"uvicorn app:app --reload\"\n  }\n}\n```\n\nFiles 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.\n\n## Tools\n\n- `executeCommand({ projectName, commandKey, args?, options? })`\n  - Resolve project override → fallback to `default` → translate for OS → run.\n  - `options` (all optional):\n    - `shell`: `auto | cmd | powershell | bash`\n    - `activateVenv`: `auto | on | off`\n    - `venvPath`: path to a venv root if not `.venv`/`venv`\n    - `cwd`: working directory for the command\n    - `env`: key/value environment overrides\n  - Returns on success:\n    ```json\n    {\n      \"stdout\": \"...\",\n      \"stderr\": \"\",\n      \"exitCode\": 0,\n      \"resolvedCommand\": \"npm install\"\n    }\n    ```\n  - On failure returns structured error inside the tool result body (not thrown):\n    ```json\n    {\n      \"errorCode\": \"COMMAND_FAILED\",\n      \"message\": \"Command failed with exit code 1\",\n      \"suggestion\": \"poetry install\",\n      \"resolvedCommand\": \"pip install -r requirements.txt\",\n      \"stdout\": \"...\",\n      \"stderr\": \"...\",\n      \"exitCode\": 1\n    }\n    ```\n\n- `getProjectCommands({ projectName })` → merged view `{ ...default, ...project }`.\n- `setProjectCommand({ projectName, key, value })` → upsert and persist.\n- `removeProjectCommand({ projectName, key })` → delete and persist.\n- `translateCommand({ rawCommand })` → `{ os, original, translated }`.\n\n## Error Handling \u0026 Suggestions\n\nWhen a command exits non‑zero the server embeds a structured error with optional suggestions, e.g.:\n\n- 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`).\n- If `pip` fails and `poetry.lock` or `[tool.poetry]` in `pyproject.toml` is present, suggestion: `poetry install`.\n- Also detects Yarn (`yarn.lock`) and pnpm (`pnpm-lock.yaml`).\n\n## MCP JSON-RPC Examples\n\nAll examples assume stdio transport.\n\n- List tools:\n```json\n{ \"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/list\" }\n```\n\n- Call `executeCommand`:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"executeCommand\",\n    \"arguments\": {\n      \"projectName\": \"python-api\",\n      \"commandKey\": \"install\",\n      \"args\": [\"-q\"]\n    }\n  }\n}\n```\n\n- Call `setProjectCommand`:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"setProjectCommand\",\n    \"arguments\": {\n      \"projectName\": \"my-bun-project\",\n      \"key\": \"lint\",\n      \"value\": \"bun run lint\"\n    }\n  }\n}\n```\n\n## IDE Integration (Production)\n\nAfter installing globally (`npm i -g smart-shell-mcp`), configure your IDE to run the `smart-shell` executable over stdio.\n\n- Cursor, Kiro, Windsurf (example)\n```json\n{\n  \"mcpServers\": {\n    \"smart-shell\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"smart-shell-mcp\"\n      ],\n      \"env\": {}\n    }\n  }\n}\n```\nOr\n```json\n{\n  \"mcpServers\": {\n    \"smart-shell\": {\n      \"command\": \"smart-shell\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\n- Claude Desktop (reference)\n```json\n{\n  \"mcpServers\": {\n    \"smart-shell\": { \"command\": \"smart-shell\" }\n  }\n}\n```\n\nNotes\n- If you prefer not to install globally, replace `smart-shell` with `npx smart-shell-mcp` in the examples above.\n- Windows users can switch to PowerShell execution with the tool options (see below) if needed.\n\n## Project Scripts\n\n- `npm run dev` – start in dev (tsx)\n- `npm run build` – build TypeScript to `dist/`\n- `npm start` – run compiled server\n- `npm run typecheck` – TypeScript type checking\n\n**Made with ❤️ by [Mr-Wolf-GB](https://github.com/mr-wolf-gb) for the MCP community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmr-wolf-gb%2Fsmart-shell-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmr-wolf-gb%2Fsmart-shell-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmr-wolf-gb%2Fsmart-shell-mcp/lists"}