Static source inference · medium confidence · detected: Roots
Deprecated protocol patterns detected
Summary
This server provides 7 tools with basic but incomplete definitions. Naming follows verb-first conventions (read-file, write-file, execute-command), which is correct. However, descriptions are minimal and lack context for when/why to use each tool. Critical gaps: (1) Parameter descriptions are sparse, many lack detail on format, range, or constraints. (2) Output schemas are entirely missing, LLMs cannot see what fields to expect in responses. (3) Error handling guidance is minimal, tools return errors but do not guide recovery. (4) No input validation or constraint documentation, e.g., search-files accepts regex patterns with no length/complexity limits. (5) STDIO transport caps the score at 50; STDIO is not remotely accessible. The server does use the @modelcontextprotocol/sdk and registers tools with proper names and basic schemas, which prevents a lower score, but the lack of output documentation and sparse parameter descriptions are production-blockers.
No output schemas documented. LLMs cannot see what fields responses contain, forcing them to infer from error messages or past behavior. This violates the 'Document the output schema' requirement and breaks chaining between tools.
Parameter descriptions lack detail on constraints, format, and valid ranges. For example, 'search-files' accepts a 'pattern' (regex) with no mention of complexity limits, which could lead to ReDoS attacks or hangs. 'execute-command' timeout defaults to 30000ms but no min/max documented.
Error messages are generic and do not guide recovery. E.g., 'Error executing command' does not tell the LLM whether to retry, ask the user, or abandon the plan. Missing error classification (retryable vs. fatal vs. user-fixable).
Recommendations
Add explicit output schemas to every tool. Document what fields the response contains, their types, and their meaning. For read-file, return { content: string; lineCount: number; encoding?: string }. For search-files, return { matches: [{path: string; lineNumber: number; lineContent: string}]; totalCount: number; nextOffset?: number }.
Expand parameter descriptions to 50 - 100 characters with explicit constraints. For 'pattern' in search-files: 'Regular expression pattern (max 200 chars, no backreferences due to performance limits) to search for in file names and content.' For 'timeout': 'Timeout in milliseconds (min 1000, max 300000; defaults to 30000).'
Add error classification and recovery guidance. For execute-command, return errors like: 'Command timed out after 30s. The command may be hanging, try reducing complexity or increasing timeout. [Retryable]' or 'Permission denied: path /etc/shadow. [Non-retryable, ask user for allowed directory.]'
Implement dry-run/confirmation for destructive tools. Add an optional 'dryRun: boolean' parameter to write-file, write-lines, and append-text. When true, validate the operation and return what would happen without executing. For actual writes, return success confirmation: { success: true; bytesWritten: number; pathWritten: string }.
Document which tools are idempotent and which have side effects. read-file is safe to retry; write-file with overwrite=true is not. Add a note in descriptions: 'Safe to retry on network errors.'
Add path traversal and input validation documentation. For file paths: 'Paths must be absolute or relative to the working directory; .. traversal is allowed only within the allowed root directory (configured by Roots).' For regex patterns: 'Patterns must not exceed 200 characters and must not use catastrophic backtracking constructs (e.g., (a+)+).'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Roots (deprecated) - pass files/dirs via tool parameters, resource URIs, or configuration
File write tools (write-file, write-lines, append-text) lack dry-run or confirmation mechanism. These are irreversible operations, agents can accidentally overwrite important files. No mention of backup or undo steps.
Tool descriptions are 50 - 65 characters, below the 194-char baseline for production tools. They lack context on WHEN to use each tool vs. similar ones (e.g., when to use append-text vs. write-file) and what the return value contains.
No input validation or constraint enforcement documented. The 'path' parameter in file tools accepts arbitrary strings, no mention of path traversal checks or OS path limits. The 'pattern' in search-files is unconstrained regex.
write-lines parameter 'lines' expects 'lineNumber:content' format but lacks detail on escaping, multi-line content, and error handling when line numbers are out of range or overlap.
write-lines
Migrate from STDIO to Streamable HTTP transport to enable remote access. STDIO is suitable only for local development. Update transport configuration to support http+sse or http with streaming.
Add pagination support to search-files. Include optional 'offset' and 'limit' parameters (defaults: offset=0, limit=20) and return 'totalMatches' and 'hasMore' flags. This prevents context bloat when searching large codebases.
Provide separate parameters for user-friendly inputs vs. system IDs. For example, in write-file, accept both 'path' (user-friendly) and 'workingDirAlias' (predefined, scoped root) to reduce path confusion.
Document the format of 'line_numbers_included' output for read-file. Does it prepend '1: ' to each line? Does it affect the content field? Make this explicit: 'If line_numbers_included is true, each line in the response is prefixed with its 1-based line number and a colon, e.g., "1: #!/bin/bash\n2: echo hello"'.
Add example scenarios in tool descriptions to clarify when to use each tool. E.g., read-file: 'Use to view configuration files, source code, or logs. NOT for binary files, returns gibberish.' write-lines: 'Use to update specific line ranges without rewriting the entire file, e.g., editing a config section.'