mcp-yieldshell

# YieldShell MCP A drop-in shell MCP server that auto-yields long-running commands into managed background executions. ## Why Auto-Yielding? Most shell tools present a frustrating choice: either block the LLM agent until the command finishes, or force the agent to decide upfront that a command should run in the background. **YieldShell MCP** solves this by keeping normal foreground semantics for fast commands, then automatically promoting long-running commands into managed background executions after a delay (`yield_ms`, default: 30 seconds). ```mermaid graph TD A[execute] --> B["Wait for yield_ms (default: 30s)"] B --> C{Is execution still running?} C -->|Yes| D["backgrounded<br>Returns execution_id"] C -->|No| E["completed<br>Returns full output"] ``` - **Fast Commands** (e.g., `echo hello`, `ls`): Complete instantly, returning the output immediately. - **Long-Running Commands** (e.g., `npm run dev`, `docker build`, `sleep 60`): Automatically yield control back to the agent with an `execution_id` and a snapshot of initial output, letting the agent decide when to `read`, `wait`, or `stop` the execution. --- ## Installation ### From Registry (Recommended) To run the published package via `uv`: ```bash uv tool install mcp-yieldshell ``` ### Local Development To clone and run locally: ```bash git clone <repo-url> && cd mcp-yieldshell uv sync uv run mcp-yieldshell ``` --- ## MCP Client Configuration ### Claude Desktop To configure the server in Claude Desktop, add the configuration below to your Claude Desktop config file: * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` #### Production (via uvx) ```json { "mcpServers": { "yieldshell": { "command": "uvx", "args": ["mcp-yieldshell"] } } } ``` #### Production with Security Restrictions ```json { "mcpServers": { "yieldshell": { "command": "uvx", …