Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server has 7 tools with visible definitions in McpService.ts. All tools have descriptions and most have Zod schemas. However, there are significant quality gaps: (1) parameter descriptions are minimal or absent, search-api-operations and search-api-schemas accept 'query' with description 'Search query string' but no guidance on syntax, format, or examples; (2) output schemas are undocumented, all tools stringify YAML responses, but the structure and fields of the returned objects are not documented; (3) tool naming follows verb_noun pattern ('search-', 'load-', 'get-', 'refresh-') which is positive, but descriptions lack WHEN/WHY guidance (pattern:tool-description); (4) no error handling guidance, exceptions are caught and logged but error responses lack actionable recovery instructions (pattern:recovery-guide); (5) no pagination support despite catalog and search tools that could return large result sets; (6) parameter constraints are minimal, 'specId' and 'operationId' have no format/pattern guidance; (7) composition is reasonable (each tool has one responsibility) but tool chaining is unclear, there's no documentation of which outputs feed into which inputs. The codebase shows good logging practices and Zod schema use, but the tool definitions themselves are incomplete by production standards.
Tools (7)
get-api-catalogread onlysource verified50/100
Get the API catalog, the catalog contains metadata about all openapi specifications, their operations and schemas
Output schemas completely undocumented. All tools return YAML-stringified responses, but the structure, field names, and types of the returned objects are not documented. LLMs cannot plan downstream tool calls or extract specific fields.
Parameter descriptions are minimal and lack guidance on format, constraints, or valid values. For example, 'query' in search-api-operations is described as 'Search query string' with no explanation of syntax, wildcards, or search fields supported. 'specId' has no format guidance (is it a UUID, slug, path?).
Document the output schema for every tool. For example, document that get-api-catalog returns {catalog: {specs: {[specId]: {name, version, operationCount, schemaCount, operations: {[opId]: {...}}, schemas: {[schemaName]: {...}}}}}}} or whatever the actual structure is. Use a comment block or JSDoc to make this visible in the code.
Enhance parameter descriptions with format and constraint guidance. Change 'specId' to 'specId: string, ID or slug of the specification (e.g., "petstore", "github-api"). Must exist in the catalog.' Change 'query' to 'query: string, Search query using fuse.js syntax. Supports partial matching. Special chars: * (wildcard), ^ (start), $ (end). Example: "create* user"'.
Add pagination parameters (limit: 1-100, offset: 0+) to search-api-operations, search-api-schemas, and get-api-catalog. Return a total count and next_offset in the response. Document the default limit (e.g., 20) in the description.
Implement error recovery guidance. For example, if load-api-operation-by-operationId('spec-x', 'unknown-op') fails, return: 'Operation "unknown-op" not found in spec "spec-x". Try search-api-operations("operationId pattern") to find similar operations.' Use the logger.warn() call in the code to identify where to add this.
Enhance tool descriptions with WHEN/WHY context. For refresh-api-catalog: 'Refresh the API catalog from disk. Call this after adding or updating .openapi.json/.openapi.yaml files in the basePath directory. Rebuilds the in-memory catalog and invalidates the cache. Non-blocking; can be called concurrently with read operations.' For get-api-catalog: 'Retrieve metadata about all loaded specifications. Returns a summary of each spec (name, version, operation/schema counts) and detailed indexes of operations and schemas. Use this first to explore what specs and operations are available before drilling down with load-* tools.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No error handling guidance. Exception handlers catch errors and log them, but tool responses do not tell the LLM what to do next (e.g., 'Operation not found. Try searching with search-api-operations first'). Error responses lack recovery instructions.
No pagination support. Tools like get-api-catalog and search-* could return large result sets (the catalog contains 'all openapi specifications, their operations and schemas'), but there are no limit, offset, or pagination parameters. Large responses risk exhausting the context window.
Tool descriptions lack WHEN/WHY context. For example, 'Refresh the API catalog' does not explain when to call it (at startup? periodically? after adding new specs?), what happens, or whether it blocks other operations. Users and LLMs need to know when and why each tool exists.
Tool naming uses hyphens (refresh-api-catalog, search-api-operations) which deviates from the common snake_case convention (refresh_api_catalog, search_api_operations). This is a minor style issue but MCP tooling typically normalizes to snake_case.
Define a JSDoc-style schema annotation for tool outputs. For example: '@returns {object} {catalog: {specs: {[specId]: {name: string, version: string, operationCount: number, operations: {[operationId]: {path: string, method: string, summary: string}}, schemas: {[schemaName]: {type: string, description: string, required: string[], properties: {}}}}}}}', visible in code and machine-parseable.
Consider adding a discover_specs tool (or rename get-api-catalog to discover_specs) to reduce ambiguity: LLMs will understand immediately that this is a discovery tool, not a detailed getter.
Add constraints to Zod schemas where missing. For example, z.string().min(1).max(255) for query to prevent empty or pathologically long searches.
Document tool composition/chaining in comments. For example: 'Common workflow: (1) get-api-catalog to see available specs, (2) search-api-operations to find a specific operation, (3) load-api-operation-by-operationId to get full details.' This helps LLMs understand the intended usage flow.