mcp-openapi-schema-explorer 1.0.0

package/src/index.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'; // Import ResourceTemplate
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { OpenAPI } from 'openapi-types'; // Import OpenAPIV3 as well
+import { loadConfig } from './config.js';
+
+// Import new handlers
+import { TopLevelFieldHandler } from './handlers/top-level-field-handler.js';
+import { PathItemHandler } from './handlers/path-item-handler.js';
+import { OperationHandler } from './handlers/operation-handler.js';
+import { ComponentMapHandler } from './handlers/component-map-handler.js';
+import { ComponentDetailHandler } from './handlers/component-detail-handler.js';
+import { OpenAPITransformer, ReferenceTransformService } from './services/reference-transform.js';
+import { SpecLoaderService } from './services/spec-loader.js';
+import { createFormatter } from './services/formatters.js';
+import { encodeUriPathComponent } from './utils/uri-builder.js'; // Import specific function
+import { isOpenAPIV3, getValidatedComponentMap } from './handlers/handler-utils.js'; // Import type guard and helper
+import { VERSION } from './version.js'; // Import the generated version
+
+async function main(): Promise<void> {
+  try {
+    // Get spec path and options from command line arguments
+    const [, , specPath, ...args] = process.argv;
+    const options = {
+      outputFormat: args.includes('--output-format')
+        ? args[args.indexOf('--output-format') + 1]
+        : undefined,
+    };
+
+    // Load configuration
+    const config = loadConfig(specPath, options);
+
+    // Initialize services
+    const referenceTransform = new ReferenceTransformService();
+    referenceTransform.registerTransformer('openapi', new OpenAPITransformer());
+
+    const specLoader = new SpecLoaderService(config.specPath, referenceTransform);
+    await specLoader.loadSpec();
+
+    // Get the loaded spec to extract the title
+    const spec: OpenAPI.Document = await specLoader.getSpec(); // Rename back to spec
+    // Get the transformed spec for use in completions
+    const transformedSpec: OpenAPI.Document = await specLoader.getTransformedSpec({
+      resourceType: 'schema', // Use a default context
+      format: 'openapi',
+    });
+    const defaultServerName = 'OpenAPI Schema Explorer';
+    // Use original spec for title
+    const serverName = spec.info?.title
+      ? `Schema Explorer for ${spec.info.title}`
+      : defaultServerName;
+
+    // Create MCP server with dynamic name
+    const server = new McpServer({
+      name: serverName,
+      version: VERSION, // Use the imported version
+    });
+
+    // Set up formatter and new handlers
+    const formatter = createFormatter(config.outputFormat);
+    const topLevelFieldHandler = new TopLevelFieldHandler(specLoader, formatter);
+    const pathItemHandler = new PathItemHandler(specLoader, formatter);
+    const operationHandler = new OperationHandler(specLoader, formatter);
+    const componentMapHandler = new ComponentMapHandler(specLoader, formatter);
+    const componentDetailHandler = new ComponentDetailHandler(specLoader, formatter);
+
+    // Register new resources
+    // 1. openapi://{field}
+    const fieldTemplate = new ResourceTemplate('openapi://{field}', {
+      list: undefined, // List is handled by the handler logic based on field value
+      complete: {
+        field: (): string[] => Object.keys(transformedSpec), // Use transformedSpec
+      },
+    });
+    server.resource(
+      'openapi-field', // Unique ID for the resource registration
+      fieldTemplate,
+      {
+        // MimeType varies (text/plain for lists, JSON/YAML for details) - SDK might handle this? Or maybe set a default? Let's omit for now.
+        description:
+          'Access top-level fields (info, servers, tags), list paths, or list component types.',
+        name: 'OpenAPI Field/List', // Generic name
+      },
+      topLevelFieldHandler.handleRequest
+    );
+
+    // 2. openapi://paths/{path}
+    const pathTemplate = new ResourceTemplate('openapi://paths/{path}', {
+      list: undefined, // List is handled by the handler
+      complete: {
+        path: (): string[] => Object.keys(transformedSpec.paths ?? {}).map(encodeUriPathComponent), // Use imported function directly
+      },
+    });
+    server.resource(
+      'openapi-path-methods',
+      pathTemplate,
+      {
+        mimeType: 'text/plain', // This always returns a list
+        description:
+          'List available HTTP methods for a specific path. (Note: {path} must be URL-encoded, e.g., /users/{id} becomes users%2F%7Bid%7D)',
+        name: 'Path Methods List',
+      },
+      pathItemHandler.handleRequest
+    );
+
+    // 3. openapi://paths/{path}/{method*}
+    const operationTemplate = new ResourceTemplate('openapi://paths/{path}/{method*}', {
+      list: undefined, // Detail view handled by handler
+      complete: {
+        path: (): string[] => Object.keys(transformedSpec.paths ?? {}).map(encodeUriPathComponent), // Use imported function directly
+        method: (): string[] => [
+          // Provide static list of common methods
+          'GET',
+          'POST',
+          'PUT',
+          'DELETE',
+          'PATCH',
+          'OPTIONS',
+          'HEAD',
+          'TRACE',
+        ],
+      },
+    });
+    server.resource(
+      'openapi-operation-detail',
+      operationTemplate,
+      {
+        mimeType: formatter.getMimeType(), // Detail view uses formatter
+        description:
+          'Get details for one or more specific API operations (methods). (Note: {path} must be URL-encoded, e.g., /users/{id} becomes users%2F%7Bid%7D)',
+        name: 'Operation Detail',
+      },
+      operationHandler.handleRequest
+    );
+
+    // 4. openapi://components/{type}
+    const componentMapTemplate = new ResourceTemplate('openapi://components/{type}', {
+      list: undefined, // List is handled by the handler
+      complete: {
+        type: (): string[] => {
+          // Use type guard to ensure spec is V3 before accessing components
+          if (isOpenAPIV3(transformedSpec)) {
+            return Object.keys(transformedSpec.components ?? {});
+          }
+          return []; // Return empty array if not V3 (shouldn't happen ideally)
+        },
+      },
+    });
+    server.resource(
+      'openapi-component-list',
+      componentMapTemplate,
+      {
+        mimeType: 'text/plain', // This always returns a list
+        description: 'List available components of a specific type (e.g., schemas, parameters).',
+        name: 'Component List',
+      },
+      componentMapHandler.handleRequest
+    );
+
+    // 5. openapi://components/{type}/{name*}
+    const componentDetailTemplate = new ResourceTemplate('openapi://components/{type}/{name*}', {
+      list: undefined, // Detail view handled by handler
+      complete: {
+        type: (): string[] => {
+          // Use type guard to ensure spec is V3 before accessing components
+          if (isOpenAPIV3(transformedSpec)) {
+            return Object.keys(transformedSpec.components ?? {});
+          }
+          return []; // Return empty array if not V3
+        }, // <<< Added missing closing brace
+        name: (): string[] => {
+          // Provide names only if there's exactly one component type defined
+          if (
+            isOpenAPIV3(transformedSpec) &&
+            transformedSpec.components &&
+            Object.keys(transformedSpec.components).length === 1
+          ) {
+            // Get the single component type key (e.g., 'schemas')
+            const componentTypeKey = Object.keys(transformedSpec.components)[0];
+            // Use the helper to safely get the map
+            try {
+              const componentTypeMap = getValidatedComponentMap(transformedSpec, componentTypeKey);
+              return Object.keys(componentTypeMap);
+            } catch (error) {
+              // Should not happen if key came from Object.keys, but handle defensively
+              console.error(`Error getting component map for key ${componentTypeKey}:`, error);
+              return [];
+            }
+          }
+          // Otherwise, return no completions for name
+          return [];
+        },
+      },
+    });
+    server.resource(
+      'openapi-component-detail',
+      componentDetailTemplate,
+      {
+        mimeType: formatter.getMimeType(), // Detail view uses formatter
+        description: 'Get details for one or more specific components (e.g., schemas, parameters).',
+        name: 'Component Detail',
+      },
+      componentDetailHandler.handleRequest
+    );
+
+    // Start server
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  } catch (error) {
+    console.error(
+      'Failed to start server:',
+      error instanceof Error ? error.message : String(error)
+    );
+    process.exit(1);
+  }
+}
+
+// Run the server
+main().catch(error => {
+  console.error('Unhandled error:', error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/rendering/components.ts

@@ -0,0 +1,228 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderableSpecObject, RenderContext, RenderResultItem } from './types.js'; // Add .js
+import { createErrorResult, generateListHint } from './utils.js'; // Add .js
+
+// Define valid component types based on OpenAPIV3.ComponentsObject keys
+export type ComponentType = keyof OpenAPIV3.ComponentsObject;
+export const VALID_COMPONENT_TYPES: ComponentType[] = [
+  'schemas',
+  'responses',
+  'parameters',
+  'examples',
+  'requestBodies',
+  'headers',
+  'securitySchemes',
+  'links',
+  'callbacks',
+  // 'pathItems' is technically allowed but we handle paths separately
+];
+
+/**
+ * Wraps an OpenAPIV3.ComponentsObject to make it renderable.
+ * Handles listing the available component types.
+ */
+export class RenderableComponents implements RenderableSpecObject {
+  constructor(private components: OpenAPIV3.ComponentsObject | undefined) {}
+
+  /**
+   * Renders a list of available component types found in the spec.
+   * Corresponds to the `openapi://components` URI.
+   */
+  renderList(context: RenderContext): RenderResultItem[] {
+    if (!this.components || Object.keys(this.components).length === 0) {
+      return createErrorResult('components', 'No components found in the specification.');
+    }
+
+    const availableTypes = Object.keys(this.components).filter((key): key is ComponentType =>
+      VALID_COMPONENT_TYPES.includes(key as ComponentType)
+    );
+
+    if (availableTypes.length === 0) {
+      return createErrorResult('components', 'No valid component types found.');
+    }
+
+    let listText = 'Available Component Types:\n\n';
+    availableTypes.sort().forEach(type => {
+      listText += `- ${type}\n`;
+    });
+
+    // Use the new hint generator structure
+    listText += generateListHint(context, { itemType: 'componentType' });
+
+    return [
+      {
+        uriSuffix: 'components',
+        data: listText,
+        renderAsList: true,
+      },
+    ];
+  }
+
+  /**
+   * Detail view for the main 'components' object isn't meaningful.
+   */
+  renderDetail(context: RenderContext): RenderResultItem[] {
+    return this.renderList(context);
+  }
+
+  /**
+   * Gets the map object for a specific component type.
+   * @param type - The component type (e.g., 'schemas').
+   * @returns The map (e.g., ComponentsObject['schemas']) or undefined.
+   */
+  getComponentMap(type: ComponentType):
+    | Record<
+        string,
+        | OpenAPIV3.SchemaObject
+        | OpenAPIV3.ResponseObject
+        | OpenAPIV3.ParameterObject
+        | OpenAPIV3.ExampleObject
+        | OpenAPIV3.RequestBodyObject
+        | OpenAPIV3.HeaderObject
+        | OpenAPIV3.SecuritySchemeObject
+        | OpenAPIV3.LinkObject
+        | OpenAPIV3.CallbackObject
+        | OpenAPIV3.ReferenceObject // Include ReferenceObject
+      >
+    | undefined {
+    // Use Map for safe access
+    if (!this.components) {
+      return undefined;
+    }
+    const componentsMap = new Map(Object.entries(this.components));
+    // Cast needed as Map.get returns the value type or undefined
+    return componentsMap.get(type) as ReturnType<RenderableComponents['getComponentMap']>;
+  }
+}
+
+// =====================================================================
+
+/**
+ * Wraps a map of components of a specific type (e.g., all schemas).
+ * Handles listing component names and rendering component details.
+ */
+export class RenderableComponentMap implements RenderableSpecObject {
+  constructor(
+    private componentMap: ReturnType<RenderableComponents['getComponentMap']>,
+    private componentType: ComponentType, // e.g., 'schemas'
+    private mapUriSuffix: string // e.g., 'components/schemas'
+  ) {}
+
+  /**
+   * Renders a list of component names for the specific type.
+   * Corresponds to the `openapi://components/{type}` URI.
+   */
+  renderList(context: RenderContext): RenderResultItem[] {
+    if (!this.componentMap || Object.keys(this.componentMap).length === 0) {
+      return createErrorResult(
+        this.mapUriSuffix,
+        `No components of type "${this.componentType}" found.`
+      );
+    }
+
+    const names = Object.keys(this.componentMap).sort();
+    let listText = `Available ${this.componentType}:\n\n`;
+    names.forEach(name => {
+      listText += `- ${name}\n`;
+    });
+
+    // Use the new hint generator structure, providing parent type
+    listText += generateListHint(context, {
+      itemType: 'componentName',
+      parentComponentType: this.componentType,
+    });
+
+    return [
+      {
+        uriSuffix: this.mapUriSuffix,
+        data: listText,
+        renderAsList: true,
+      },
+    ];
+  }
+
+  /**
+   * Renders the detail view for one or more specific named components
+   * Renders the detail view. For a component map, this usually means listing
+   * the component names, similar to renderList. The handler should call
+   * `renderComponentDetail` for specific component details.
+   */
+  renderDetail(context: RenderContext): RenderResultItem[] {
+    // Delegate to renderList as the primary view for a component map itself.
+    return this.renderList(context);
+  }
+
+  /**
+   * Renders the detail view for one or more specific named components
+   * within this map.
+   * Corresponds to the `openapi://components/{type}/{name*}` URI.
+   * This is called by the handler after identifying the name(s).
+   *
+   * @param _context - The rendering context (might be needed later).
+   * @param names - Array of component names.
+   * @returns An array of RenderResultItem representing the component details.
+   */
+  renderComponentDetail(_context: RenderContext, names: string[]): RenderResultItem[] {
+    if (!this.componentMap) {
+      // Create error results for all requested names if map is missing
+      return names.map(name => ({
+        uriSuffix: `${this.mapUriSuffix}/${name}`,
+        data: null,
+        isError: true,
+        errorText: `Component map for type "${this.componentType}" not found.`,
+        renderAsList: true,
+      }));
+    }
+
+    const results: RenderResultItem[] = [];
+    for (const name of names) {
+      const component = this.getComponent(name);
+      const componentUriSuffix = `${this.mapUriSuffix}/${name}`;
+
+      if (!component) {
+        results.push({
+          uriSuffix: componentUriSuffix,
+          data: null,
+          isError: true,
+          errorText: `Component "${name}" of type "${this.componentType}" not found.`,
+          renderAsList: true,
+        });
+      } else {
+        // Return the raw component object; handler will format it
+        results.push({
+          uriSuffix: componentUriSuffix,
+          data: component,
+        });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Gets a specific component object by name.
+   * @param name - The name of the component.
+   * @returns The component object (or ReferenceObject) or undefined.
+   */
+  getComponent(
+    name: string
+  ):
+    | OpenAPIV3.SchemaObject
+    | OpenAPIV3.ResponseObject
+    | OpenAPIV3.ParameterObject
+    | OpenAPIV3.ExampleObject
+    | OpenAPIV3.RequestBodyObject
+    | OpenAPIV3.HeaderObject
+    | OpenAPIV3.SecuritySchemeObject
+    | OpenAPIV3.LinkObject
+    | OpenAPIV3.CallbackObject
+    | OpenAPIV3.ReferenceObject
+    | undefined {
+    // Use Map for safe access
+    if (!this.componentMap) {
+      return undefined;
+    }
+    const detailsMap = new Map(Object.entries(this.componentMap));
+    // No cast needed, Map.get returns the correct type (ValueType | undefined)
+    return detailsMap.get(name);
+  }
+}

package/src/rendering/document.ts

@@ -0,0 +1,167 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderableSpecObject, RenderContext, RenderResultItem } from './types.js'; // Add .js
+// No longer need ResourceContents here
+
+// Placeholder for other renderable objects we'll create
+// import { RenderablePaths } from './paths.js'; // Add .js
+// import { RenderableComponents } from './components.js'; // Add .js
+
+/**
+ * Wraps an OpenAPIV3.Document to make it renderable.
+ * Handles rendering for top-level fields like 'info', 'servers', etc.
+ * Delegates list rendering for 'paths' and 'components' to respective objects.
+ */
+export class RenderableDocument implements RenderableSpecObject {
+  // TODO: Add RenderablePaths and RenderableComponents instances
+  // private renderablePaths: RenderablePaths;
+  // private renderableComponents: RenderableComponents;
+
+  constructor(private document: OpenAPIV3.Document) {
+    // Initialize renderable wrappers for paths and components here
+    // this.renderablePaths = new RenderablePaths(document.paths);
+    // this.renderableComponents = new RenderableComponents(document.components);
+  }
+
+  /**
+   * Renders a list view. For the document level, this is intended
+   * to be called only when the requested field is 'paths' or 'components'.
+   * The actual routing/delegation will happen in the handler based on the field.
+   */
+  renderList(_context: RenderContext): RenderResultItem[] {
+    // Prefix context with _
+    // This method should ideally not be called directly on the document
+    // without specifying 'paths' or 'components' as the field.
+    // The handler for openapi://{field} will delegate to the appropriate
+    // sub-object's renderList.
+    // Returning an error result item.
+    return [
+      {
+        uriSuffix: 'error',
+        data: null, // No specific data for this error
+        isError: true,
+        errorText:
+          'Error: List rendering is only supported for specific fields like "paths" or "components" at the top level.',
+        renderAsList: true, // Errors often shown as plain text
+      },
+    ];
+  }
+
+  /**
+   * Renders the detail view. For the document level, this should not be called
+   * directly without specifying a field. The handler should call
+   * `renderTopLevelFieldDetail` instead.
+   */
+  renderDetail(_context: RenderContext): RenderResultItem[] {
+    // Prefix context with _
+    // This method implementation fulfills the interface requirement,
+    // but direct detail rendering of the whole document isn't meaningful here.
+    return [
+      {
+        uriSuffix: 'error',
+        data: null,
+        isError: true,
+        errorText:
+          'Error: Detail rendering requires specifying a top-level field (e.g., "info", "servers").',
+        renderAsList: true, // Errors often shown as plain text
+      },
+    ];
+  }
+
+  /**
+   * Renders the detail view for a *specific* top-level field (e.g., 'info', 'servers').
+   * This is called by the handler after identifying the field.
+   *
+   * @param context - The rendering context.
+   * @param fieldObject - The actual top-level field object to render (e.g., document.info).
+   * @param fieldName - The name of the field being rendered (e.g., 'info').
+   * @returns An array of RenderResultItem representing the detail view.
+   */
+  renderTopLevelFieldDetail(
+    context: RenderContext,
+    fieldObject: unknown,
+    fieldName: string
+  ): RenderResultItem[] {
+    // Ensure fieldObject is provided (handler should validate fieldName exists)
+    if (fieldObject === undefined || fieldObject === null) {
+      return [
+        {
+          uriSuffix: fieldName,
+          data: null,
+          isError: true,
+          errorText: `Error: Field "${fieldName}" not found in the OpenAPI document.`,
+          renderAsList: true,
+        },
+      ];
+    }
+
+    // Avoid rendering structural fields that have dedicated list views
+    if (fieldName === 'paths' || fieldName === 'components') {
+      return [
+        {
+          uriSuffix: fieldName,
+          data: null,
+          isError: true,
+          errorText: `Error: Field "${fieldName}" should be accessed via its list view (${context.baseUri}${fieldName}). Use the list view first.`,
+          renderAsList: true,
+        },
+      ];
+    }
+
+    try {
+      // For successful detail rendering, return the data object itself.
+      // The handler will format it using the context.formatter.
+      return [
+        {
+          uriSuffix: fieldName,
+          data: fieldObject, // Pass the raw data
+          // isError defaults to false
+          // renderAsList defaults to false (meaning use detail formatter)
+        },
+      ];
+    } catch (error: unknown) {
+      // Handle potential errors during data access or initial checks
+      // Formatting errors will be caught by the handler later
+      return [
+        {
+          uriSuffix: fieldName,
+          data: null,
+          isError: true,
+          errorText: `Error preparing field "${fieldName}" for rendering: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          renderAsList: true,
+        },
+      ];
+    }
+  } // End of renderTopLevelFieldDetail
+
+  // --- Helper methods to access specific parts ---
+
+  getPathsObject(): OpenAPIV3.PathsObject | undefined {
+    return this.document.paths;
+  }
+
+  getComponentsObject(): OpenAPIV3.ComponentsObject | undefined {
+    return this.document.components;
+  }
+
+  getTopLevelField(fieldName: string): unknown {
+    // Define allowed top-level OpenAPI document properties
+    const allowedFields: Array<keyof OpenAPIV3.Document> = [
+      'openapi',
+      'info',
+      'servers',
+      'paths',
+      'components',
+      'security',
+      'tags',
+      'externalDocs',
+    ];
+
+    // Only allow access to documented OpenAPI properties
+    if (allowedFields.includes(fieldName as keyof OpenAPIV3.Document)) {
+      return this.document[fieldName as keyof OpenAPIV3.Document];
+    }
+    return undefined;
+  }
+} // End of RenderableDocument class