Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
mcp-shell provides 30 tools with good naming (verb-first convention followed consistently) and complete parameter schemas. However, descriptions are terse and lack LLM-optimized guidance. Most tool descriptions are under 100 characters and fail to explain WHEN to use each tool vs alternatives, or what the return structure contains. Parameter descriptions exist but are brief (avg ~40 chars vs baseline 72). Error handling is minimal, no recovery guidance, no actionable error messages shown. Output schemas are not documented in visible code. Security concerns present: shell_exec and run_script pose injection risks despite sandboxing claims. No tool annotations (readOnlyHint/destructiveHint) despite 13 destructive/reversible operations. Overall: functional but falls short of LLM-optimized quality.
Tools (30)
deletedestructivesource verified75/100
Delete a file or directory
diff_filesread onlysource verified79/100
Show a unified diff between two files
edit_filewritesource verified79/100
Replace an exact string in a file
git_addwritesource verified80/100
Stage files
git_blameread onlysource verified79/100
Show what revision and author last modified each line of a file
git_branchesread onlysource verified77/100
List branches
git_commitwritesource verified81/100
Create a commit
git_diffread onlysource verified79/100
Show changes between commits, the working tree, or the index
Output schemas not documented. No visible return type definitions for any tool in provided source. LLMs cannot plan downstream tool calls or extract result fields without this information.
Add documented output schemas for all 30 tools. Include field names, types, and sample structure. Reference these in tool descriptions so LLMs know what to extract. Example: 'Returns: {content: string, line_count: number, is_binary: boolean}'
Add tool annotations: use readOnlyHint for all git_* read operations (git_status, git_log, git_show, git_blame, git_branches, git_tags, git_rev_parse, git_ls_files, git_stash_list, git_remotes); use destructiveHint for delete, git_add, git_commit, write_file, edit_file, shell_exec, run_script; use idempotentHint for read operations and mkdir (if idempotent directory creation is guaranteed).
Expand tool descriptions to 150 - 250 characters. Add WHEN guidance: e.g., 'git_diff: Show file changes between commits. Call this AFTER git_log to review what changed in a specific commit. Returns: unified diff format showing added/removed lines.' vs current 'Show changes between commits, the working tree, or the index.'
Add min/max constraints to numeric parameters. Examples: offset>=1, limit>=0 and <=5000, max_count>=1 and <=1000, depth>=0 and <=10, line_start>=1, line_end>=1. Document these in parameter descriptions.
Restrict shell_exec and run_script or add explicit safety warnings. Consider: (1) requiring an allow-list of commands (e.g., MCP_SHELL_ALLOWED_CMDS env var); (2) enforcing per-call timeouts and output size limits documented in parameter descriptions; (3) adding a 'dry_run' parameter to preview execution; (4) returning per-line structured results instead of raw text to enable parsing by LLMs.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 65 points across a rubric change (v1 → v2)
65/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
C
65
<=2025-11-25
v2
2026-03-09
F
0
-
v1
git_logread onlysource verified81/100
Show commit logs
git_ls_filesread onlysource verified77/100
List tracked (or untracked) files
git_remotesread onlysource verified76/100
List remotes and their URLs
git_restorereversiblesource verified77/100
Restore working tree or staged files
git_rev_parseread onlysource verified72/100
Resolve a ref to a commit hash
git_showread onlysource verified77/100
Show a commit or a file at a given ref
git_stashreversiblesource verified77/100
Stash, pop, or drop local changes
git_stash_listread onlysource verified74/100
List the stash entries
git_statusread onlysource verified78/100
Show the working tree status
git_switchwritesource verified77/100
Switch to a branch
git_tagsread onlysource verified76/100
List tags
globread onlysource verified77/100
Find files matching a glob pattern
grepread onlysource verified82/100
Search file contents with a regular expression
list_dirread onlysource verified82/100
List directory entries up to a given depth
mkdirwritesource verified78/100
Create a directory, including parent directories
movewritesource verified76/100
Move or rename a file or directory
read_fileread onlysource verified85/100
Read a text file, optionally by line offset/limit or tail
run_scriptwritesource verified65/100
Run an operator-defined script by name. Available scripts are listed in the description
shell_execdestructivesource verified65/100
UNRESTRICTED: runs the command through bash -c with no validation. Only available with MCP_SHELL_ALLOW_UNSAFE=1.
statread onlysource verified73/100
Show metadata for a file or directory
system_inforead onlysource verified73/100
Show information about the host and workspace
write_filewritesource verified82/100
Write content to a file, creating parent directories as needed
Descriptions lack LLM-optimized guidance. Average description ~75 chars (baseline 194 chars). Most descriptions state WHAT the tool does but not WHEN to use it vs alternatives, what prerequisites exist, or what the return structure contains. Examples: 'Show information about the host and workspace' (50 chars), 'Show a commit or a file at a given ref' (41 chars).
shell_exec and run_script enable arbitrary code execution. 'UNRESTRICTED: runs the command through bash -c with no validation' is dangerous even with MCP_SHELL_ALLOW_UNSAFE=1 guard. Requires defense against prompt injection and LLM hallucination of shell commands. No per-call rate limiting, timeout enforcement, or sandboxing visible in provided code.
No documented recovery guidance for errors. Provided code does not show error response handling with actionable next steps. LLMs given raw failures cannot determine whether to retry, query the user, or abandon the operation.
run_script description is vague. 'Run an operator-defined script by name. Available scripts are listed in the description' assumes scripts are auto-discovered in description, but provides no information about where/how to define them, format, or expected return structure.
No parameter constraints for numeric inputs. 'offset', 'limit', 'tail' (read_file), 'max_count' (git_log), 'line_start', 'line_end' (git_blame), 'max_results' (glob, grep), 'depth' (list_dir) lack min/max bounds. Unbounded numbers let LLMs pass absurd values (negative offsets, 1M line limits) that cause failures or timeouts.
read_filelist_dirglobgrepgit_loggit_blame
Add error response guidance. Document recovery paths in tool descriptions: e.g., 'If file not found, call glob() or list_dir() to discover available files.' 'If git command fails, call git_status() to check repository state.'
Clarify run_script: document the format/location of operator-defined scripts, expected parameter passing mechanism (name only? arguments?), and return structure. Add a helper tool to list available scripts if this is dynamic.
Add per-parameter dependencies in descriptions. Example for git_diff: 'ref and ref_to are mutually exclusive with staged. If staged=true, ref parameters are ignored.' Current descriptions don't clarify these relationships.
Document pagination/result limits. Tools like list_dir, glob, grep already have max_results. Add 'Returns up to X results' to descriptions and explain how to iterate for larger datasets (e.g., using glob patterns or grep with line offsets).
Add batch operation variants where agents commonly loop. Consider: write_files (array of {path, content}), delete_files (array), git_add (array already present). Reduces LLM token use and latency.