Yuque (语雀) Document MCP Server - Search and fetch documents via Yuque API
Server has 5 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-200 chars, within baseline range) and input schemas with type definitions. However, parameter descriptions are sparse or missing context. Output schemas are not documented. Error handling is minimal, no recovery guidance or actionable error messages. Tool naming follows verb_noun convention (search, get_*, create_*, update_*), which is good. Composition is reasonable: tools chain logically (search → get_doc, get_toc → create_doc). No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels. Missing pagination guidance for search results. No idempotency guarantees documented.
Create a new document in Yuque knowledge base. Creates the document first, then updates the TOC to add it to the directory structure.
Get the full content of a specific document by its ID. Use this when you have the document ID and need to read the complete document content.
Get the table of contents (directory structure) of the Yuque knowledge base. Use this when user wants to browse or navigate the folder structure. Returns a flat list of all folders and documents with uuid and title.
Search documents by keyword in Yuque knowledge base. Use this when user wants to find specific documents or content. Returns matching documents with titles and summaries.
Update an existing document in Yuque knowledge base. Modify title, content, path, or visibility.
Output schemas not documented. LLMs cannot plan downstream calls or extract required fields (e.g., doc_id from search results for get_doc chaining). Baseline: 100% of A+ tools document return types.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels. create_doc and update_doc are WRITE operations; search, get_doc, get_toc are READ_ONLY. Agents need this metadata to reason about side effects and retry safety.
Parameter descriptions lack actionable constraints. 'Search keyword' (search.q) does not specify format, length, or examples. 'Document ID' (get_doc.doc_id) does not clarify if it's numeric or string (schema says number, but update_doc.doc_id is string, inconsistency). Baseline: 100% of A+ tool params have descriptions with constraints.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | 2026-07-28+ | v2 |
No error handling guidance. HttpClient.request() throws generic 'API request failed' errors with no recovery hints. LLMs cannot distinguish retryable (rate limit, timeout) from user-fixable (invalid token, missing config) from fatal errors. Baseline: A+ tools categorize errors and guide recovery.
Inconsistent parameter types: get_doc.doc_id is number, but update_doc.doc_id is string. This forces LLMs to reason about type conversions and risks silent failures. Baseline: Mismatched naming/typing increases agent errors.