MCP server for interactive shell sessions
This server has well-structured tool definitions with comprehensive schemas and mostly clear descriptions. All 9 tools are explicitly registered with proper JSON Schema. Tool names use clear verb_noun patterns (start_, send_, read_, get_, search_, list_, resize_, end_). Most parameters have types and descriptions. However, there are gaps: (1) output schemas are not documented anywhere in the code, callers must infer response structure from implementation; (2) some descriptions lack actionable guidance on when/why to use each tool vs. alternatives; (3) error handling patterns are not evident in tool definitions, no guidance on what failures mean or how to recover. The server shows good foundation but falls short of production-grade tooling clarity.
Closes the PTY and cleans up resources
Returns the current cursor position and the text of the line the cursor is on. Lightweight alternative to reading the full screen.
Extracts text from a rectangular region of the terminal screen. Coordinates are 0-based, end values are exclusive.
List all active shell sessions with their metadata.
Returns output from the PTY process. Supports three modes: streaming (default) returns buffered output since last read, snapshot mode returns current terminal state, screen mode returns the parsed virtual terminal screen
Resize the terminal of an active shell session.
Output schemas are not documented. No tool definition includes a 'outputSchema' field or response structure documentation. LLMs cannot predict what fields/types each tool returns, forcing them to infer from examples or guess at chaining parameters.
Error handling not defined in tool descriptions. No guidance on what constitutes failure (e.g., invalid sessionId, shell crash, resource exhaustion) or what the LLM should do next (retry, ask user, try alternative). Callers must infer from implementation.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 68 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 46 | - | v1 |
Search the terminal screen for text or regex pattern. Returns matching positions.
Writes input to the PTY. By default appends a carriage return. Use raw mode for interactive prompts (arrow keys, space to toggle, etc.)
Spawns a new PTY shell with a virtual terminal emulator and returns a unique session ID
Tool descriptions lack differentiation guidance. read_shell_output has three modes (streaming/snapshot/screen) but does not clearly explain when to pick each. Similar tools like get_screen_region and get_screen_cursor both extract terminal content but differ in capability, descriptions don't guide LLMs to the right choice.
Parameter constraints not fully enforced or documented. E.g., cols and rows have max values (500, 200) stated in description but no JSON Schema maxLength/maximum constraints. waitForIdle mentions 'max effective wait is 5000ms' but schema has no maximum. Incomplete formal constraints invite LLM misuse.
Missing response field documentation for chaining. E.g., start_shell_session returns a sessionId, but it's not documented in an outputSchema. Tools like read_shell_output accept sessionId, but there's no explicit guarantee that start_shell_session will return a field matching that name. This invites field-mapping errors.
list_sessions description is sparse ('List all active shell sessions with their metadata') and provides no guidance on response structure, how to use the output, or when to call it. Descriptions should be 50-200 chars optimized for LLM prompting.
No confirmation or dry-run pattern for irreversible operations. end_shell_session destroys a session and its output buffer, but there is no dry-run or confirm-before-execute step. Agents may accidentally terminate sessions during exploration.