A cite-or-die retrieval & navigation service for a code monorepo and its docs, exposing code search, symbol lookup, file reading, and diagnostic tools via MCP protocol
Code-KB MCP server has 18 tools with basic schemas and descriptions, but significant quality gaps limit production readiness. Tool names follow verb_noun convention (kb_ask, codekb_search_code, codekb_read_file_range), which is good. However, descriptions are inconsistent in depth, some are 50-100 chars (adequate), others exceed 200 chars (verbose). Most tools lack output schema documentation; input schemas are present but sparse on parameter constraints. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all tools being READ_ONLY. Error handling is not visible in the provided code. Parameter descriptions exist but lack format/range constraints (e.g., top_k has no min/max bounds). The server exposes diagnostic and webhook tools (codekb_diagnose, codekb_diagnose_webhook_validate) that accept user_token and payload parameters, potential security concern if tokens are logged. Overall, the server is functional but lacks the polish and defensive design of production-grade tools.
Perform hybrid retrieval on code and documentation knowledge base. Expands natural language or non-English concepts to possible English identifiers. Returns repo/file:line hits and snippets.
Run a diagnostic analysis on a code location or knowledge base query with detailed results and optional user confirmation
Normalize and preview a diagnostic webhook payload according to the configured mapping
Validate a diagnostic webhook payload against the configured mapping schema
Get the structural outline of a file showing its top-level definitions and sections
Find files in the indexed repository by path pattern matching. Useful for locating modules by name when concept retrieval returns generic results.
No output schema documentation. Tools return results (hits, files, matches, segments) but response structure is not formally documented. LLMs cannot plan downstream calls or extract fields reliably.
Missing parameter constraints. top_k parameter appears in 5+ tools with no min/max bounds. LLMs may pass absurd values (0, 999999) causing API failures or timeouts.
No tool annotations despite all tools being READ_ONLY. Missing readOnlyHint annotation prevents agents from understanding which tools are safe to call speculatively vs. which require confirmation.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | 2026-07-28+ | v2 |
Find definitions or occurrences of a specific symbol (function, class, method, constant) in the code
List direct subdirectories and files under a repository path prefix. Useful for browsing the directory tree.
Read indexed code from a specific file and line range. Falls back to KB snapshot when local repository is unavailable.
Request confirmation from the user with a custom message and payload
Perform hybrid retrieval on code and documentation knowledge base. Returns repo/file:line hits and snippets.
Find files in indexed repository by path pattern. Useful for locating modules by name when concept retrieval returns generic results (e.g., 'login' or 'auth account').
Find definitions or occurrences of a specific symbol (function, class, method, constant) in the code
Ask the knowledge base a question and get a generative answer with citations
Locate code implementing a specific feature or concept
Plan code changes by analyzing the codebase structure and dependencies
List direct subdirectories and files under a repository path prefix. Useful for browsing the directory tree.
Read indexed code from a specific file and line range. Falls back to KB snapshot when local repository is unavailable.
Potential security issue: codekb_diagnose and webhook tools accept user_token and payload parameters. If these are logged or echoed in error responses, tokens leak into traces. Recommend server-side secret injection.
No error handling guidance visible. Tools lack recovery hints (e.g., 'If symbol not found, try code_search() with a partial name'). LLMs cannot self-correct on failures.