MCP OpenAPI Server

Instructions

Implementation Reference

• src/McpService.ts:141-172 (registration)

  Registration of the MCP tool 'load-api-operation-by-operationId', including inline input schema (specId: string, operationId: string) and handler function that delegates to specExplorer.findOperationById, logs, handles errors, and returns the operation as YAML string.
  server.tool( "load-api-operation-by-operationId", "Load an operation by operationId", { specId: z.string(), operationId: z.string(), }, async (args, extra) => { try { this.logger.debug('Loading API operation by ID', { specId: args.specId, operationId: args.operationId }); const operation = await this.specExplorer.findOperationById( args.specId, args.operationId ); if (!operation) { this.logger.warn('Operation not found', { specId: args.specId, operationId: args.operationId }); } return { content: [ { type: "text", text: stringify(operation, { indent: 2 }) }, ], }; } catch (error) { this.logger.error('Failed to load API operation by ID', { error, specId: args.specId, operationId: args.operationId }); throw error; } } );
• src/McpService.ts:144-147 (schema)

  Zod input schema for the tool: specId (string), operationId (string).
  { specId: z.string(), operationId: z.string(), },
• src/McpService.ts:148-171 (handler)

  MCP tool handler: validates inputs implicitly via schema, calls ISpecExplorer.findOperationById, stringifies result to YAML if found, handles not found and errors.
  async (args, extra) => { try { this.logger.debug('Loading API operation by ID', { specId: args.specId, operationId: args.operationId }); const operation = await this.specExplorer.findOperationById( args.specId, args.operationId ); if (!operation) { this.logger.warn('Operation not found', { specId: args.specId, operationId: args.operationId }); } return { content: [ { type: "text", text: stringify(operation, { indent: 2 }) }, ], }; } catch (error) { this.logger.error('Failed to load API operation by ID', { error, specId: args.specId, operationId: args.operationId }); throw error; } }
• src/core/SpecService.ts:439-463 (helper)

  Core implementation: Iterates over paths and methods in the spec's paths object to find the operation matching the given operationId, returns LoadOperationResult with path, method, operation object, specId, and constructed URI, or null if not found.
  async findOperationById( specId: string, operationId: string ): Promise<LoadOperationResult | null> { const spec = this.specs[specId]; if (!spec) { return null; } for (const path in spec.paths) { const pathItem = spec.paths[path]; for (const method in pathItem) { if (pathItem[method]["operationId"] === operationId) { return { path, method, operation: pathItem[method], specId, uri: `apis://${specId}/operations/${operationId}`, }; } } } return null; }
• src/core/interfaces/ISpecService.ts:94-104 (schema)

  TypeScript interface defining the structure of the loaded operation result (output type), used by the helper method.
  export interface LoadOperationResult { /** Path of the operation */ path: string; /** HTTP method */ method: string; /** The operation object */ operation: OpenAPIV3.OperationObject; /** ID of the specification containing the operation */ specId: string; /** URI identifying the operation */ uri: string;