Model Context Protocol server for YApi API documentation platform. Supports reading and writing YApi interface definitions with session-based (email/password) or token-based authentication.
YApi MCP exposes 14 well-structured tools with consistent naming (verb_noun pattern: list_, get_, add_, update_, import_), complete input schemas derived from Go structs with jsonschema tags, and descriptions for all tools and parameters. However, descriptions are often terse (10 - 50 chars), lack WHEN/WHY guidance, and omit dependency hints. Output schemas are not documented. Error handling is minimal, no recovery guidance or actionable error messages visible. Security: credentials appear to be injected server-side (good), but no explicit permission gates or audit trail patterns. Composition is sound: tools chain well (list_groups → list_projects → list_interfaces), and IDs flow correctly between calls. Baseline: avg tool desc ~40 chars (below 194-char production median); avg param desc ~60 chars (below 72-char baseline). No tool lacks a description or schema, but quality is below A-grade threshold.
Create a new interface category (folder) in a project.
Create a new interface in a category.
Get details of a single YApi group by id (session mode only).
Get full details of a single interface by id, including request/response schema.
Get details of a single YApi project by id.
Import API documentation (swagger/har/postman/json) into a project.
Descriptions lack WHEN/WHY guidance and dependency hints. E.g., 'List all YApi groups' does not explain when to call it (before list_projects) or what to do with the result. LLMs cannot infer prerequisites.
Output schemas are not documented. Tools return structured data (groups, projects, interfaces) but the response format is not visible in tool definitions. LLMs cannot plan downstream calls without knowing what fields to expect.
No error handling guidance. Tools do not document what errors can occur, whether they are retryable, or what the LLM should do next. E.g., 'group not found' vs 'permission denied' are not distinguished.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | 2026-07-28+ | v2 |
List interface categories (folders) in a project. Use this before listing or adding interfaces.
List the projects configured in the local projects.json (token mode only). Returns id and name so the LLM can resolve a project name to its id.
List all YApi groups the authenticated user belongs to (session mode only). Use this to discover top-level groupings before listing projects.
List all interfaces in a project (flat list, no grouping).
List interfaces in a specific category (folder) of a project. Use yapi_list_categories first to find the category id.
List projects within a YApi group (session mode only). Use yapi_list_groups first to find the group id.
Upsert an interface by path+method within a category. Creates if absent, updates if present.
Update an existing interface by id. Only provided fields are changed.
Destructive operations (add_interface, update_interface, import_data) lack confirmation or dry-run support. Agents can accidentally overwrite or delete API specs without a safety gate.
Parameter descriptions for complex fields (req_query, req_body_other, res_body) are verbose but lack examples or constraints. E.g., req_query expects an array of Param objects but the structure is not formally defined in the description.