An MCP server implementation in Go with file operations, code patching, execution, semantic analysis, and an enhanced agent with self-diagnosis and learning capabilities
Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This server exhibits significant quality gaps across naming, descriptions, schemas, and error handling. While 12 tools are registered with basic schemas, the definitions lack the clarity and structure needed for reliable agent usage. Tool names are somewhat descriptive but inconsistent in convention (some imperative like 'file_read', others nominal like 'agent_process'). Descriptions are present but minimal (10-50 chars for most), far below the 50-200 char baseline for LLM-optimized docs. Input schemas exist but lack parameter descriptions in many cases, violating the baseline that 100% of A+ tools have described parameters. Critical security issues are present: exec_run accepts arbitrary commands with no sanitization or permission gating, file_write and patch_apply can modify any path without clear guard validation visibility, and generate_code has no constraints on output. Error handling is absent, no recovery guidance, no categorization of errors as retryable vs fatal, no actionable error messages. Composition issues exist: agent_process and agent_diagnose appear to operate on shared internal state without clear contracts, and the interaction between semantic_analyze, intent_analyze, and generate_code suggests overlapping concerns. No output schema documentation is provided for any tool, forcing LLMs to guess what fields they'll receive. The server claims guards (FileGuard, DiffGuard, RuleGuard) but their validation logic is not visible in the provided code excerpt, making it impossible to verify that dangerous tools like exec_run and file_write are actually protected.
exec_run tool accepts arbitrary shell commands with no sanitization, validation, or permission checks. No confirmation step, timeout enforcement visibility, or error recovery guidance. This is a critical command injection and privilege escalation vector.
File modification tools (file_write, patch_apply) claim to use guards (FileGuard, DiffGuard) but guard validation logic is not visible in provided code. Cannot verify that paths are actually validated, forbidden paths are rejected, or diff limits are enforced. Risk of unauthorized file writes.
Descriptions are uniformly minimal (10-50 chars), far below the 50-200 char LLM-optimized baseline. Example: file_read = 'Read the contents of a file' (28 chars). LLMs cannot distinguish when to call this vs related file tools, nor understand error cases or prerequisites.
file_readfile_writefile_listfile_search
Recommendations
Expand tool descriptions to 80-150 chars, explaining WHAT the tool does, WHEN to use it (vs similar tools), and any side effects or prerequisites. Example for file_read: 'Reads and returns the complete text content of a file. Use this to examine source code, configs, or logs. Returns file content as plain text. Fails if file does not exist or is unreadable (permission denied, binary format).'
Add descriptions to every parameter. For exec_run.command, specify: 'Shell command to execute (bash/sh syntax). Commands run in the specified directory with a timeout. Note: commands cannot contain pipes, redirects, or interactive input. Provide explicit parameters instead. Example: use file_read() to pass file content, not command='cat file.txt'.'
Document output schemas for all tools. Example for file_list: 'Returns an object with: {files: [{name: string, path: string, size: int, modified: ISO8601}], total: int, truncated: boolean}. If truncated=true, use offset/limit to paginate.'
Add input validation and error recovery to exec_run: (1) Restrict allowed commands via an allowlist or regex pattern; (2) reject commands with pipes, redirects, or shell metacharacters; (3) enforce a configurable timeout (document default); (4) return structured error like '{error: 'timeout', message: 'Command exceeded 30s limit', command: '...', suggestion: 'Command may be slow. Try a faster alternative or increase timeout.'}'
Make guard implementations (FileGuard, DiffGuard, RuleGuard) visible in the code or document their validation rules explicitly. For file_write and patch_apply, document: 'Paths outside allowed directories are rejected. Max file size: [X]. Max patch diff: [Y] lines. Returns error with violation details if rejected.'
No parameter descriptions provided in the code. All 12 tools have parameters but descriptions for the parameters themselves (e.g., 'path' in file_read, 'pattern' in file_search, 'command' in exec_run) are not visible. Violates baseline: 100% of A+ tools have described parameters.
No output schema documentation for any tool. LLMs cannot plan downstream calls or extract the right data from responses. E.g., what fields does file_list return? Is it file paths only, or does it include size, modified date, type? What about file_search, does it return line numbers, context, or just filenames?
No error handling guidance. Tools have no documented error cases, recovery paths, or categorization of errors as retryable vs fatal. Example: what happens if exec_run times out? Should the agent retry? Call a different tool? This is completely undocumented.
generate_code tool has no constraints on language, length, or content. LLMs will hallucinate arbitrary code. Should specify: allowed languages (enum), maximum output size, whether tests/documentation should be included.
agent_process and agent_diagnose appear to operate on shared internal agent state but have no documented contracts: What state do they read/write? Are they idempotent? Can multiple parallel calls corrupt state? This violates tool composition principles.
semantic_analyze, intent_analyze, and generate_code have overlapping concerns. It's unclear when to call each vs others. LLM will waste reasoning cycles choosing between them. Need clearer disambiguation in descriptions.
file_list accepts 'depth' parameter but no max depth constraint is documented. LLMs could pass depth=1000, causing expensive recursive traversals. Should document min/max bounds.
No pagination support visible for file_list or file_search. If directories are large (thousands of files), returning all results will blow the context window. Should add limit and offset/cursor parameters and document result capping.
file_listfile_search
Add idempotency contracts to agent_process and agent_diagnose. Document: 'Calling with the same task multiple times yields the same result. State changes are deterministic and logged. Parallel calls are serialized.'
Disambiguate semantic_analyze, intent_analyze, and generate_code in descriptions. Example: 'semantic_analyze: Parses code structure (functions, classes, imports) for syntax understanding. Use to decompose complex code. / intent_analyze: Infers what code or task is trying to accomplish. Use to understand user intent. / generate_code: Produces new code from description. Use to implement features.'
Add limit and offset parameters to file_list and file_search. Document: 'Returns max 50 results by default. Use limit (1-500) and offset for pagination. Response includes total_count and has_more flag.'
Add max_depth constraint to file_list. Document: 'Default depth=1 (immediate children only). Max depth=10. Deeper traversals are expensive; use file_search for targeted discovery instead.'
Add language enum and output constraints to generate_code. Document: 'language: one of [python, javascript, go, java, rust, sql]. Returns code only, no explanation. Max length: 2000 lines. For larger implementations, split into multiple tools calls.'
Implement per-tool rate limiting and timeout enforcement. Document in tool descriptions: 'This tool has a 30-second timeout. If command exceeds this, try breaking it into smaller operations. Rate limit: 10 calls per minute per agent.'
Add dry-run or confirmation support to write operations (file_write, patch_apply, exec_run). Example: 'Pass dry_run=true to preview changes without executing. Useful before modifying production code.'
For error responses, provide actionable next steps. Instead of returning '{error: "not found"}', return '{error: "File not found", path: "/path/to/file", suggestion: "Did you mean /path/to/file.txt? Or call file_search() to locate files matching a pattern."}'
Document security boundaries. For exec_run, specify: 'Commands execute with the server process permissions. Agents cannot access files outside the allowed_paths. No access to environment variables or secrets. Commands are logged with full parameters and execution time.'
Add composition guidance: Document which tools chain together and in what order. Example: 'To modify code: (1) file_read to examine current code, (2) intent_analyze to understand required changes, (3) generate_code to create replacement, (4) patch_apply to apply changes, (5) exec_run to test.'