基于MCP的Swagger工具服务器,支持解析Swagger、生成类型定义和API客户端
The Swagger MCP Server exhibits significant definition quality gaps across all dimensions. While 12 tools are registered with basic descriptions and input schemas, the quality falls well below production standards. Tool names lack clear action verbs (e.g., 'parse-swagger' instead of 'fetch-swagger-spec'), descriptions are generic (average ~60 chars, well below the 194-char baseline), and parameter documentation is minimal. Critically, error handling guidance is completely absent, output schemas are not documented, and no tool annotations (readOnlyHint/destructiveHint) are present despite several WRITE and DESTRUCTIVE tools. The server mixes 3 similar parsing tools (parse-swagger, parse-swagger-optimized, parse-swagger-lite) without clear differentiation, violating the single-responsibility and composition patterns. Parameter descriptions are terse and often lack constraints (e.g., 'Request headers' with no format guidance). No evidence of idempotency guarantees, retry logic documentation, or user-friendly identifier handling. The file_writer tool exposes dangerous capabilities (overwrite, append, auto-mkdir) with minimal safety guidance.
Write content to the specified file path, with support for automatic directory creation
Generate API client code from Swagger/OpenAPI document.
Generate API client code from Swagger/OpenAPI document (optimized version with caching and large document support).
Generate TypeScript type definitions from Swagger/OpenAPI document.
Generate TypeScript type definitions from Swagger/OpenAPI document with optimized options for caching and large document support.
Parse Swagger/OpenAPI document and return API operation information.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite clear risk classifications (READ_ONLY, WRITE, DESTRUCTIVE). Tools like file_writer (WRITE) and template-delete (DESTRUCTIVE) lack safety declarations that guide LLM caution.
Three nearly identical parse tools (parse-swagger, parse-swagger-optimized, parse-swagger-lite) with unclear differentiation. Descriptions do not explain when to use which tool, violating composition and single-responsibility patterns. LLMs will not know which to select.
Output schemas are completely undocumented. No tool declares what fields it returns, data types, or structure. LLMs cannot plan downstream tool calls or extract required fields without trial-and-error.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 39 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 40 | - | v1 |
Lightweight parsing of Swagger/OpenAPI document, faster but returns only basic information (suitable for large documents).
Parse Swagger/OpenAPI document using optimized parser with caching and large document support.
Delete custom template
Get specific template content
Get available code generation template list
Save or update template
No error handling guidance. Tools provide no recovery instructions ('try search_users()', retry advisories, or categorization of errors as retryable vs fatal). Raw errors or missing error documentation will cause agent failures.
Parameter descriptions are minimal and lack constraints. E.g., 'Request headers' (object type) has no guidance on format, encoding, or required fields. 'Cache TTL in minutes' lacks min/max bounds. Validators (pattern, enum, min/max) are not visible in source.
File writer tool (file_writer) has dangerous defaults with minimal safety guidance. Parameters 'overwrite' and 'createDirs' default unspecified; no confirmation step for destructive overwrites. Description does not warn about path traversal risks or file system limits.
Tool names lack action verbs. 'parse-swagger', 'generate-typescript-types', 'file_writer' are weak, prefer 'fetch-swagger-spec', 'create-typescript-types', 'write-file'. Names should make intent obvious without reading descriptions.
Duplicate tool variants (optimized versions) add confusion without documented tradeoffs. 'parse-swagger' vs 'parse-swagger-optimized' vs 'parse-swagger-lite', no description clarifies performance/accuracy tradeoffs, caching strategy, or when to use each.
No pagination or result limiting documented. Tools like 'template-list' may return unbounded arrays; no description mentions max results, pagination support, or next_cursor. Large result sets waste tokens and risk context explosion.
No tool composition guidance. Tools like 'generate-typescript-types' and 'generate-api-client' likely depend on parsing first, but no description states prerequisites or chaining order. Agents cannot infer multi-step workflows.