Swagger MCP Server

Instructions

Implementation Reference

• src/server.js:889-955 (handler)

  The core handler function that validates the API response body against the expected schema from Swagger documentation for the specified endpoint and status code.
  function validateApiResponse(path, method, statusCode, responseBody) { if (!path) { throw new Error('Path is required for API response validation'); } if (!method) { throw new Error('Method is required for API response validation'); } if (statusCode === undefined || statusCode === null) { throw new Error('Status code is required for API response validation'); } if (responseBody === undefined) { throw new Error('Response body is required for API response validation'); } if (!swaggerDoc) { throw new Error('Swagger documentation not loaded. Call fetch_swagger_info first.'); } try { const endpoints = swaggerDoc.paths || {}; method = method.toLowerCase(); if (!endpoints[path] || !endpoints[path][method]) { throw new Error(`Endpoint ${method.toUpperCase()} ${path} not found in the Swagger documentation`); } const endpoint = endpoints[path][method]; const responses = endpoint.responses || {}; const responseSpec = responses[statusCode] || responses['default']; if (!responseSpec) { return { valid: false, errors: [`No schema defined for status code ${statusCode} in Swagger documentation`] }; } const issues = []; if (responseSpec.schema) { try { if (responseSpec.schema.type === 'object' && typeof responseBody !== 'object') { issues.push(`Expected response to be an object, but got ${typeof responseBody}`); } else if (responseSpec.schema.type === 'array' && !Array.isArray(responseBody)) { issues.push(`Expected response to be an array, but got ${typeof responseBody}`); } issues.push('Note: Full schema validation requires a JSON Schema validator library'); } catch (schemaError) { issues.push(`Schema validation error: ${schemaError.message}`); } } return { valid: issues.length === 0, errors: issues, schema: responseSpec.schema || null, expectedStatusCodes: Object.keys(responses), actualStatusCode: statusCode, responseSpec: responseSpec }; } catch (error) { log.error(`Error validating API response: ${error.message}`); throw new Error(`Response validation failed: ${error.message}`); } }
• src/server.js:229-250 (schema)

  Input schema defining the parameters for the validate_api_response tool: path, method, statusCode, and responseBody.
  inputSchema: { type: "object", properties: { path: { type: "string", description: "The endpoint path" }, method: { type: "string", description: "The HTTP method" }, statusCode: { type: "number", description: "The HTTP status code" }, responseBody: { type: "object", description: "The response body to validate" } }, required: ["path", "method", "statusCode", "responseBody"], },
• src/server.js:226-251 (registration)

  Registration of the validate_api_response tool in the tools array used by the MCP server capabilities.
  { name: "validate_api_response", description: "Validate an API response against the schema from Swagger documentation", inputSchema: { type: "object", properties: { path: { type: "string", description: "The endpoint path" }, method: { type: "string", description: "The HTTP method" }, statusCode: { type: "number", description: "The HTTP status code" }, responseBody: { type: "object", description: "The response body to validate" } }, required: ["path", "method", "statusCode", "responseBody"], }, }
• src/server.js:1056-1106 (handler)

  The switch case in the CallToolRequestSchema handler that processes calls to validate_api_response and invokes the validateApiResponse function.
  case "validate_api_response": { const path = request.params.arguments?.path; const method = request.params.arguments?.method; const statusCode = request.params.arguments?.statusCode; const responseBody = request.params.arguments?.responseBody; const missingParams = []; if (!path) missingParams.push('path'); if (!method) missingParams.push('method'); if (statusCode === undefined) missingParams.push('statusCode'); if (responseBody === undefined) missingParams.push('responseBody'); if (missingParams.length > 0) { const errorMessage = `Missing required parameters for API response validation: ${missingParams.join(', ')}`; log.error(errorMessage); throw new Error(errorMessage); } try { log.info(`Validating response for ${method.toUpperCase()} ${path} with status ${statusCode}`); let parsedBody = responseBody; if (typeof responseBody === 'string') { try { parsedBody = JSON.parse(responseBody); log.info('Successfully parsed response body string as JSON'); } catch (parseError) { log.warning(`Response body is a string but not valid JSON: ${parseError.message}`); } } const result = validateApiResponse(path, method, statusCode, parsedBody); if (result.valid) { log.success('Response validation passed'); } else { log.warning(`Response validation found ${result.errors.length} issues`); result.errors.forEach(error => log.debug(`Validation issue: ${error}`)); } return { content: [{ type: "text", text: JSON.stringify(result) }], isError: false, }; } catch (error) { log.error(`Failed to validate API response: ${error.message}`); throw new Error(`Failed to validate API response: ${error.message}`); } }