Swagger MCP Server

Instructions

Implementation Reference

• src/server.js:964-988 (handler)

  Handler for the fetch_swagger_info tool call. Extracts URL from arguments, fetches Swagger doc using fetchSwaggerDoc, and returns structured info.
  case "fetch_swagger_info": { const url = request.params.arguments?.url; try { const result = await fetchSwaggerDoc(API_DOCS_URL || url); return { content: [{ type: "text", text: JSON.stringify({ title: result.info?.title || 'API Documentation', version: result.info?.version || 'Unknown', description: result.info?.description || 'No description available', swaggerVersion: result.swagger || result.openapi || 'Unknown', servers: result.servers || [{ url: API_BASE_URL }], pathCount: Object.keys(result.paths || {}).length, tagCount: (result.tags || []).length, docsUrl: swaggerUrl }) }], isError: false, }; } catch (error) { throw new Error(`Failed to fetch Swagger info: ${error.message}`); } }
• src/server.js:155-168 (schema)

  Input schema definition for the fetch_swagger_info tool, defining optional 'url' parameter.
  { name: "fetch_swagger_info", description: "Fetch Swagger/OpenAPI documentation to discover available API endpoints", inputSchema: { type: "object", properties: { url: { type: "string", description: "URL to the swagger.json or swagger.yaml file. If not provided, will try to use the base URL with common Swagger paths." } }, required: [], }, },
• src/server.js:260-262 (registration)

  Registration of all tools (including fetch_swagger_info) in the MCP server capabilities via tools.reduce.
  capabilities: { tools: tools.reduce((acc, tool) => ({ ...acc, [tool.name]: tool }), {}), },
• src/server.js:311-474 (helper)

  Core helper function fetchSwaggerDoc that handles fetching Swagger documentation from provided URL, configured API_DOCS_URL, or auto-discovery on common paths.
  async function fetchSwaggerDoc(url = null) { try { if (url) { const isFullUrl = url.startsWith('http://') || url.startsWith('https://'); let effectiveUrl = url; if (!isFullUrl && API_BASE_URL) { log.info(`Path-only URL provided, appending to API_BASE_URL`); effectiveUrl = buildUrl(url); log.api('GET', effectiveUrl); } else { log.api('GET', url); try { const parsedUrl = new URL(url); const urlBase = `${parsedUrl.protocol}//${parsedUrl.host}`; if (API_BASE_URL && urlBase !== API_BASE_URL) { log.warning(`URL base ${urlBase} differs from configured API_BASE_URL ${API_BASE_URL}`); log.warning('This URL will be used for Swagger docs only, other operations will still use configured API_BASE_URL'); } } catch (e) { log.warning(`Invalid URL format: ${url}`); } } const response = await fetch(effectiveUrl, { method: 'GET', headers: { 'Accept': 'application/json', ...getAuthHeader(true) } }); if (!response.ok) { const errorText = await response.text(); throw new Error(`Failed to fetch Swagger doc: ${response.status} ${errorText}`); } const doc = await response.json(); swaggerDoc = doc; swaggerUrl = effectiveUrl; log.success(`Successfully fetched Swagger documentation from ${effectiveUrl}`); return doc; } if (API_DOCS_URL) { log.info(`Trying configured docs URL: ${API_DOCS_URL}`); try { const response = await fetch(API_DOCS_URL, { method: 'GET', headers: { 'Accept': 'application/json', ...getAuthHeader() } }); if (response.ok) { const doc = await response.json(); swaggerDoc = doc; swaggerUrl = API_DOCS_URL; log.success(`Successfully fetched Swagger documentation from ${API_DOCS_URL}`); return doc; } else { log.debug(`Failed to fetch from configured docs URL: ${response.status} ${response.statusText}`); if (!API_DOCS_URL.endsWith('.json')) { const jsonUrl = `${API_DOCS_URL}.json`; log.debug(`Trying with .json extension: ${jsonUrl}`); const jsonResponse = await fetch(jsonUrl, { method: 'GET', headers: { 'Accept': 'application/json', ...getAuthHeader() } }); if (jsonResponse.ok) { const doc = await jsonResponse.json(); swaggerDoc = doc; swaggerUrl = jsonUrl; log.success(`Successfully fetched Swagger documentation from ${jsonUrl}`); return doc; } } } } catch (error) { log.debug(`Error fetching from configured docs URL: ${error.message}`); } } if (!API_BASE_URL) { throw new Error('No API_BASE_URL configured and no explicit Swagger URL provided'); } const commonPaths = [ '/api-docs', '/api-docs.json', '/api-docs/swagger.json', '/api-docs/v1/swagger.json', '/swagger', '/swagger.json', '/swagger/v1/swagger.json', '/swagger-ui', '/swagger-ui.json', '/swagger-ui/swagger.json', '/openapi', '/openapi.json', '/docs', '/docs.json', '/docs/swagger.json' ]; log.info(`Auto-discovering Swagger docs from ${commonPaths.length} common paths...`); let attemptCount = 0; for (const path of commonPaths) { const testUrl = buildUrl(path); attemptCount++; try { const response = await fetch(testUrl, { method: 'GET', headers: { 'Accept': 'application/json', ...getAuthHeader() } }); if (response.ok) { const contentType = response.headers.get('content-type'); if (contentType && contentType.includes('application/json')) { const doc = await response.json(); swaggerDoc = doc; swaggerUrl = testUrl; log.success(`Successfully fetched Swagger documentation from ${testUrl}`); return doc; } else { log.debug(`Found path ${testUrl} but content type is not JSON: ${contentType}`); } } } catch (e) { if (attemptCount <= 3) { log.debug(`Failed to fetch from ${testUrl}: ${e.message}`); } } } log.debug(`Attempted ${attemptCount} common paths for Swagger documentation`); throw new Error('Could not find Swagger documentation at any common paths. Please provide explicit URL.'); } catch (error) { log.error(`Error fetching Swagger documentation: ${error.message}`); throw new Error(`Failed to fetch Swagger documentation: ${error.message}`); } }