Local-only Node.js CLI + MCP server for ingesting Markdown docs and exposing retrieval tools
Single tool 'docs_query' has a clear, verb-driven name and documented input/output schemas via Zod. However, parameter descriptions are minimal, and the output structure lacks depth documentation. The tool serves a focused purpose (semantic search over local docs) but falls short of production-grade LLM-friendliness in several dimensions: parameter descriptions are terse, output schema documentation is inferred from code rather than explicit in tool registration, and error handling guidance is absent. The implementation is sound but the interface is under-documented.
Retrieve context chunks from the local docs index
Parameter 'k' description is minimal ('Number of top chunks to retrieve (optional, default from server config, max 20)'). Does not explain what 'k' represents semantically, when to adjust it, or why max is 20. LLMs cannot infer trade-offs between speed, token cost, and relevance without explicit guidance.
Parameter 'question' description ('The question to search for in the documentation') lacks guidance on format, length, or quality hints. No mention of whether multi-sentence queries work better than single keywords, or how context affects retrieval quality.
Output schema (QueryResultSchema with chunks array) is defined in code but NOT documented in the tool registration description. The tool description says 'Retrieve context chunks' but does not specify: What fields are in each chunk? How is 'score' interpreted (0-1 range? higher=better?)? Are results sorted by relevance? Without this, LLMs cannot reliably extract or reason about results.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 53 | 2025-06-18+ | v2 |
| 2026-03-09 | F | 44 | - | v1 |
No error handling documentation. Tool does not describe: What happens if 'question' is empty or malformed? What if the embedding model fails to load? What if the index is corrupted? Agents have no recovery path if the tool fails.
Output schema lacks per-item success/failure semantics. If retrieval fails for certain documents, the response should indicate which chunks failed and why, not a blanket error. Current design obscures partial failures.