Loading ToolBench
A Model Context Protocol server for managing background shells
mcp-shell-yeah has 11 tools with generally clear naming and purposes, but significant gaps in schema completeness, parameter descriptions, and output documentation. All tools have descriptions (good baseline), but most descriptions lack detail about WHEN to use them, what they return, and error handling guidance. Schemas are visible in src/toolDefinitions.ts via Zod imports, but parameter descriptions are often sparse or missing actionable constraints. Output schemas are not explicitly documented. Error handling guidance is minimal. The server follows verb_noun naming well (start_shell, check_shell, stop_shell, etc.), which is a strength. However, many parameters lack type information visible in the provided code, and schema validation rules are not stated in descriptions.
Checks the status and recent logs of a managed shell. If any URLs are found in logs, extract and return them as markdown links for the user.
Retrieves the complete log/output history for a specific managed shell. Useful for debugging or reviewing all shell output.
Provides a health status summary of the MCP Shell Manager itself.
Lists all managed shells and their statuses, including recent output lines for each shell.
Restarts a specific managed shell by stopping and then starting it again. Useful for refreshing dev servers or test shells.
Sends input to a specific managed shell, simulating user interaction (e.g., responding to prompts in the shell).
Output schemas not documented. None of the 11 tools document what they return. LLMs cannot plan downstream tool calls or extract return values without knowing the response schema. This violates pattern:tool and pattern:response-shaper.
Parameter descriptions are generic and lack constraints. Examples: 'Arguments to pass to the command' (args), 'Number of log lines to return' (log_lines - no min/max), 'Timeout in milliseconds' (no range), 'The target status to wait for' (no enum of valid values like running|stopped|error). This forces LLMs to guess valid inputs.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 52 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 50 | - | v1 |
Starts a shell (e.g. dev server, test runner) in a managed environment. If any URLs are found in logs, extract and return them as markdown links for the user. Immediately run the tail_command using your run_terminal_cmd tool to monitor this shell's output.
Starts a shell with verification (pattern, timeout, retries). Returns monitoring commands and all shell output. IMPORTANT: This tool is rarely used. Prefer 'start_shell' unless explicitly requested by the user to verify successful startup.
Attempts to gracefully stop all active managed shells.
Stops a specific managed shell. Can forcefully terminate or gracefully stop the shell.
Waits for a specific managed shell to reach a target status (e.g., running). Use this to synchronize with shell readiness.
Error handling and recovery guidance missing. No tool description explains what errors are retryable, what partial failures look like, or how to recover. For example: stop_all_shells says 'Attempts to gracefully stop' but does not explain what happens if some shells fail to stop (does it error? return partial success?).
Idempotency not stated. Tools like send_input and restart_shell do not document whether they are idempotent. If an agent retries on transient failure, will send_input send the same input twice? This is a critical concern for agent design.
No pagination documented for list_shells, despite returning 'all managed shells'. Lists without pagination can blow context windows. No mention of limit, offset, or total count returned.
Tool composition clarity mixed. start_shell and start_shell_with_verification overlap in purpose. Description of start_shell_with_verification says 'This tool is rarely used. Prefer start_shell unless explicitly requested', but this guidance should be in start_shell too, explaining when verification is NOT needed. No clear handoff between tools.
Destructive operations (stop_shell, stop_all_shells, restart_shell) lack confirmation or dry-run pattern. An LLM could accidentally halt all shells without warning. No description mentions confirmation, and tool is immediately destructive on call.