MCP server for multi-repository code documentation and symbol search with extraction, refresh, and staleness detection
livedocs demonstrates solid tool design with clear naming (verb_noun pattern), comprehensive descriptions (avg 180 chars), and well-structured JSON schemas. All 7 tools have input schemas with typed parameters and descriptions. Output structures are documented in code comments. However, parameter descriptions lack actionable constraints (ranges, enums, formats), and error handling guidance is minimal. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles. Missing pagination guidance for list_repos and list_packages despite returning arrays.
Render package documentation for a given repository and import path. Performs lazy staleness check and re-extracts changed files before rendering. Includes semantic sections (Purpose and Usage Patterns), enrichment status, and freshness metadata.
Refresh a document's answer and manifest. Requires doc_id. When the document status is OrphanedStatus, AcknowledgeOrphan must be true to proceed. Performs rate-limiting, executor refresh, state persistence, and post-refresh drift detection.
Check the drift status of documents. When DocID is empty the tool returns status for every document in the store; otherwise it returns status for just the named document.
List import paths (packages) for a given repository. Returns up to 200 import paths matching an optional prefix, with a total count. Includes extracted_at timestamp and warns if data is older than 7 days. When repo roots are configured, includes stale_paths listing packages with changed files on disk.
List all repositories available in the data directory. Returns a JSON array with repo name, symbol count, and claim count for each repository. Includes extracted_at timestamp and warns if data is older than 7 days.
Missing tool annotations (readOnlyHint, destructiveHint, idempotentHint). evergreen_refresh is clearly destructive (WRITE risk), request_extraction is WRITE, but no annotations present in schema to guide agent behavior.
Parameter descriptions lack actionable constraints. 'repo' parameter in list_packages and search_symbols accepts free-form strings with no format guidance (e.g., 'kubernetes' vs 'github.com/org/repo'). No enum, pattern, or length constraints documented.
list_repos and list_packages return arrays but lack pagination parameters (limit, offset, cursor). Description mentions '200 import paths' cap but no limit parameter exposed. Large result sets could exhaust context.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 65 | 2026-07-28+ | v2 |
Request extraction (indexing) for a repository. If the repo has no claims DB, triggers a full shallow-clone extraction in the background. If the repo has a claims DB but it is stale (behind remote HEAD), triggers incremental extraction. If the repo is already up-to-date, returns already_fresh. Returns immediately with status: queued, already_fresh, or in_progress.
Search for symbols across all repositories by name pattern. Uses an in-memory routing index to narrow candidate repos before searching, avoiding full fan-out to all databases. Supports SQL LIKE wildcards: use '%' for multi-character wildcards and '_' for single-character wildcards. Returns up to 50 results with total_count metadata. Each result includes repo, import_path, symbol_name, kind, and visibility.
Error handling lacks recovery guidance. No documented error codes, retryability classification, or actionable next steps. E.g., request_extraction returns 'queued|already_fresh|in_progress' but no guidance on polling strategy or timeout.
search_symbols supports SQL LIKE wildcards but description does not explain escaping rules or performance implications of leading wildcards ('%Handler%'). LLMs may generate inefficient queries.