Swagger MCP Server

Instructions

Implementation Reference

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

  The core handler function that performs the actual validation of the API response body against the expected schema from Swagger documentation for the specified endpoint (path, method) and status code. It checks endpoint existence, retrieves the response schema, performs basic type checks, and reports validation issues.
  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:226-251 (registration)

  MCP tool registration defining the 'validate_api_response' tool, including its description and input schema for path, method, statusCode, and responseBody.
  { 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 (registration)

  Dispatch handler in the MCP CallToolRequestSchema that handles calls to 'validate_api_response', validates input arguments, parses responseBody if string, invokes the validateApiResponse function, and formats the result.
  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}`); } }
• src/server.js:229-250 (schema)

  Input schema definition for the validate_api_response tool, specifying types and requirements for parameters.
  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"], },