fetch_swagger_info

Instructions

Implementation Reference

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

  The handler function for the 'fetch_swagger_info' tool within the CallToolRequestSchema handler's switch statement. It calls fetchSwaggerDoc with the provided or configured URL and returns a JSON summary of the API documentation including title, version, paths count, etc.

  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:311-474 (helper)

  The core helper function that implements the logic to fetch Swagger/OpenAPI documentation. Supports explicit URL, configured API_DOCS_URL, or auto-discovery from common paths on API_BASE_URL. Handles authentication and sets global swaggerDoc.

  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}`);
    }
  }

• src/server.js:155-168 (registration)

  Registration of the 'fetch_swagger_info' tool in the tools array, which is used to build the server capabilities object passed to the MCP Server constructor.

  {
    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:158-167 (schema)

  Input schema for the 'fetch_swagger_info' tool, defining an optional 'url' parameter.

  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: [],
  },