Static source inference · medium confidence · detected: stateful session
Deprecated protocol patterns detected
Summary
This server defines 3 tools with basic but incomplete quality. Tool names are action-oriented (execute_, persistent_, session_manager) which is good, but descriptions lack depth and context for LLM selection. Parameter schemas are present with types and descriptions, which is a strength, but descriptions are minimal and lack guidance on constraints, dependencies, or recovery paths. The server provides no documentation of return/output schemas, making it unclear what fields LLMs should expect. Error handling is not visible in the provided source. Risk annotations (DESTRUCTIVE, WRITE) are present in metadata but not exposed to the LLM in schema. Overall, this is a mediocre server that provides the structural minimum but lacks the polish and guidance production tools need.
Tools (3)
execute_commanddestructivesource verified57/100
Execute terminal commands with configurable timeout (non-persistent)
persistent_shelldestructivesource verified52/100
Execute commands in persistent shell sessions - maintains state between commands
Return schemas completely undocumented. LLMs have no visibility into output structure (field names, types, pagination). This blocks downstream tool chaining and forces LLMs to guess at response formats.
Descriptions are too short and lack context. execute_command at 56 chars, persistent_shell at 75 chars, session_manager at 54 chars. Baseline for A+ tools is 194 chars average. Descriptions do not answer WHAT, WHEN, or WHAT IT RETURNS, forcing LLMs to infer.
No error handling documentation. No guidance on what errors are recoverable, what to do if a command times out, what happens if session_id is invalid, or how to interpret exit codes.
execute_commandpersistent_shellsession_manager
Recommendations
Expand tool descriptions to 150-250 chars. Example for execute_command: 'Execute a single terminal command in an isolated, non-persistent shell environment. Returns command output and exit code. Useful for one-off commands. If you need to maintain state across multiple commands (e.g., cd into a directory then run commands), use persistent_shell instead. Timeout defaults to 30s; commands exceeding this timeout are killed.'
Document return schemas explicitly. For execute_command, specify: '{stdout: string, stderr?: string, exit_code: number, timed_out: boolean}'. For persistent_shell, specify same. For session_manager list action, specify: '{sessions: [{id: string, created_at: ISO8601, command_count: number}], count: number}'.
Add error handling guidance to each tool description. Example: 'If the command times out, exit_code will be null and timed_out will be true. If the command is not found, stderr will contain the error message and exit_code will be 127. If the shell fails to start, the response will be an error with code SHELL_INIT_FAILED, try checking the shell parameter.'
Clarify session_manager's action parameter: 'action: enum ["list", "close"], "list" requires no session_id and returns all active sessions; "close" requires session_id and terminates that session. Attempting to close a nonexistent session returns an error.'
Rename session_manager to a verb+noun pattern. Split into two tools if possible: 'list_shell_sessions' and 'close_shell_session' for clarity. If keeping as one, rename to 'manage_shell_sessions' and document the action enum more explicitly.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Stateful initialize / Mcp-Session-Id (removed; protocol is stateless) - make each request self-contained
Tool naming mixes patterns. execute_command and persistent_shell are clear verb+noun, but session_manager is a bare noun. Inconsistency forces LLM reasoning overhead.
Parameter interdependencies undocumented. session_manager's session_id is required only for 'close' action but described as optional. Undocumented dependencies cause silent misuse.
No guidance on tool composition. When should an LLM use execute_command vs persistent_shell? How does session_manager fit into a workflow? Missing dependency hints and selection criteria.
Destructive operations (DESTRUCTIVE, WRITE) not annotated in schema. Risk metadata exists in Makefile comment but is not exposed to LLM as toolAnnotations (readOnlyHint, destructiveHint, idempotentHint).
execute_commandpersistent_shellsession_manager
Add tool annotations to schema. Mark execute_command and persistent_shell with destructiveHint=true (they can modify system state). Mark session_manager's 'close' action as destructive (terminates a session).
Document timeout behavior and constraints. Add to execute_command description: 'timeout parameter: optional, range 1-3600 seconds, defaults to 30s. Timeout is per-command execution, not cumulative.'
Document capture_stderr behavior. Expand description: 'capture_stderr: optional boolean, defaults to false. If true, stderr is returned in a separate stderr field in the response; if false, stderr is mixed with stdout. Use true when you need to distinguish error output from normal output.'
Add guidance on shell parameter. Specify which shells are supported and what the default is on each OS: 'shell: optional, must be "/bin/bash", "/bin/sh", "/bin/zsh", or "/bin/powershell". Defaults to system default shell (bash on Linux, zsh on macOS, powershell on Windows).'
Document session creation and lifecycle. Add to persistent_shell description: 'Session IDs are created implicitly on first use. Sessions persist until explicitly closed via session_manager or until the server restarts. Session state includes working directory, environment variables, and history.'
Add a note on idempotency. clarify: 'execute_command is idempotent (same input → same output). persistent_shell is not idempotent (state changes between calls).' This helps LLMs decide when to retry.
Include example session workflows in tool descriptions. Example: 'Typical workflow: 1) Call persistent_shell with session_id="build-123" and command="cd /project"; 2) Call persistent_shell with same session_id and command="npm install"; 3) Call session_manager with action="close" and session_id="build-123" when done.'
Document parameter constraints in descriptions. For timeout: 'Must be a positive number (1-3600 seconds). Passing 0 returns an error INVALID_TIMEOUT.'
Add input validation error messages. Describe what happens on invalid input: 'If command is empty, returns error EMPTY_COMMAND. If timeout is negative, returns error INVALID_TIMEOUT. If shell is unsupported, returns error UNKNOWN_SHELL.'
Specify output limits and pagination if applicable. If command output can be very large, state: 'stdout and stderr are limited to 1MB each; larger output is truncated with a warning flag truncated=true.'
Document resource requirements and constraints. Example: 'Each persistent session consumes system resources. Maximum 100 concurrent sessions per server. Idle sessions (no commands for 1 hour) are automatically cleaned up.'