ShellBridge presents a well-structured, security-conscious MCP server with 13 tools focused on shell execution, document management, and Git operations. Tool naming follows verb-first conventions (runShellCommand, gitStage, writeTextDocument). Descriptions are present and moderately detailed (100-200 chars typical), explaining what each tool does and key constraints. However, several critical gaps reduce overall quality: (1) Many input parameters lack descriptions entirely, parameters like those in inspectConfig, runProjectTask, getGitStatus, gitStage, gitUnstage, prepareGitCommit, prepareExistingScriptRun, and executeShellApproval are not visible or fully specified in the source excerpt. (2) Output schemas are not documented in the provided code, only request schemas appear in the OpenAPI spec. (3) Error handling and recovery guidance are not evident from the source. (4) Some tools combine multiple concerns (e.g., gitStage + gitUnstage could be unified into a more flexible git operation tool). The tools that ARE fully specified (runShellCommand, runShellBatch) demonstrate good constraint design (timeouts, output limits, read_scope isolation), but the incomplete tool definitions (7 of 13 lack visible parameter schemas or descriptions) drag the average down. Baseline: production tools average 194 chars for descriptions and 72 chars per param description; ShellBridge achieves this for shell tools but falls short for Git and document tools.
Output schemas not documented. The OpenAPI spec shows request schemas for runShellCommand and runShellBatch, but no response schemas are visible for any tool. LLMs need to know what fields to expect in responses to plan downstream tool calls.
Complete the OpenAPI spec: add request/response schemas for all 11 undocumented tools (inspectConfig, runProjectTask, writeTextDocument, patchTextDocument, moveTextDocument, getGitStatus, gitStage, gitUnstage, prepareGitCommit, prepareExistingScriptRun, executeShellApproval). Include parameter descriptions (type, constraints, defaults) and response field definitions.
Enhance descriptions for Git tools. Current 'Stage explicit local Git changes' (50 chars) lacks actionable detail. Expand to: 'Stage specific files or all changes in the working directory. Accepts an array of file paths; if empty, stages all modified files. Returns staged file list and total count.' (~180 chars, matches baseline).
Document the proposal workflow. Explain in prepareGitCommit and executeShellApproval descriptions that prepareGitCommit returns a proposal_id that must be passed to executeShellApproval. Include example: 'Call prepareGitCommit with message and files, receive proposal_id, then call executeShellApproval with that ID to execute.'
Add error recovery guidance to write tools. 'Atomically write a Markdown or text document' does not explain what happens if the file exists, permissions fail, or the document is locked. Expand: 'Atomically write UTF-8 text to an absolute path. Fails if: (1) path escapes configured root (404 forbidden), (2) insufficient permissions (403), (3) file locked by another process (conflict). Retry with a different path or request user confirmation.'
Add constraints to document tools. Specify max file size, allowed extensions, encoding, and line ending handling. E.g., 'writeTextDocument accepts .md, .txt, .json, .yaml files up to 10 MB. Paths must be absolute and within the configured root directory.'
Git operations (gitStage, gitUnstage) lack clear parameter descriptions and could be unified. Two separate tools for staging/unstaging suggest the agent must know Git workflow details. Consider a single gitUpdateStaging tool with a 'mode' enum (stage|unstage) and files array.
No error handling documentation visible. Descriptions like 'Run an existing project task in a disposable writable copy' do not explain what errors can occur, whether they're retryable, or how to recover.
Proposal-based flow (prepareGitCommit → executeShellApproval) introduces multi-step coupling. Tools require the LLM to first prepare, then execute. Output of prepareGitCommit must include a proposal ID that executeShellApproval accepts. This chaining is not documented in visible schemas.
prepareGitCommitexecuteShellApproval
Consider unifying gitStage and gitUnstage into a single gitUpdateStaging(files: string[], mode: 'stage'|'unstage') tool. Reduces cognitive load for the LLM and clarifies that both are aspects of the same staging operation.
Document runShellCommand and runShellBatch output structure. Show that responses include stdout, stderr, exit_code, and execution_time_ms. Specify max output truncation behavior ('output truncated at 10240 bytes; see max_output_bytes to retrieve more').
Add per-parameter validation examples. For runShellCommand: 'timeout_ms must be 1 - 60000 (typical: 5000 for fast diagnostics, 30000 for slow builds); cwd must be an absolute path within read_scope if set; read_scope must be a directory accessible by the runner user.'
Clarify the read_scope / cwd security model in descriptions. 'When read_scope is set, only that directory is mounted in the sandbox. cwd must lie inside read_scope. This prevents the LLM from escaping the project directory. Omit read_scope to use the configured full root.' Current language is defensive but lacks clarity on why this matters.
Add 'see also' hints between related tools. E.g., in getGitStatus: 'Call this first to inspect changes. Then use gitStage/gitUnstage to prepare a commit, prepareGitCommit to freeze it, and executeShellApproval to apply it.' This guides multi-step planning without forcing lookup calls.