https://github.com/mr-wolf-gb/smart-shell-mcp
MCP Tool Server – Cross-Platform & Project-Aware Command Runner.
https://github.com/mr-wolf-gb/smart-shell-mcp
agentic-ai ai bash cmd linux mcp-server python shell tool windows
Last synced: 5 months ago
JSON representation
MCP Tool Server – Cross-Platform & Project-Aware Command Runner.
- Host: GitHub
- URL: https://github.com/mr-wolf-gb/smart-shell-mcp
- Owner: mr-wolf-gb
- License: gpl-3.0
- Created: 2025-09-05T12:33:53.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-06T07:18:24.000Z (10 months ago)
- Last Synced: 2025-10-22T01:52:39.497Z (8 months ago)
- Topics: agentic-ai, ai, bash, cmd, linux, mcp-server, python, shell, tool, windows
- Language: JavaScript
- Homepage:
- Size: 77.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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**