mcp-openapi-schema-explorer 1.0.0

package/src/rendering/path-item.ts

@@ -0,0 +1,157 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderableSpecObject, RenderContext, RenderResultItem } from './types.js'; // Add .js
+import { getOperationSummary, createErrorResult, generateListHint } from './utils.js'; // Add .js
+
+/**
+ * Wraps an OpenAPIV3.PathItemObject to make it renderable.
+ * Handles rendering the list of methods for a specific path and
+ * the details of specific operations (methods).
+ */
+export class RenderablePathItem implements RenderableSpecObject {
+  constructor(
+    private pathItem: OpenAPIV3.PathItemObject | undefined,
+    private path: string, // The raw, decoded path string e.g., "/users/{userId}"
+    private pathUriSuffix: string // Built using buildPathItemUriSuffix(path) e.g., 'paths/users%7BuserId%7D'
+  ) {}
+
+  /**
+   * Renders a token-efficient list of methods available for this path.
+   * Corresponds to the `openapi://paths/{path}` URI.
+   */
+  renderList(context: RenderContext): RenderResultItem[] {
+    if (!this.pathItem) {
+      return createErrorResult(this.pathUriSuffix, 'Path item not found.');
+    }
+
+    // Correctly check if the lowercase key is one of the enum values
+    const methods = Object.keys(this.pathItem).filter(key =>
+      Object.values(OpenAPIV3.HttpMethods).includes(key.toLowerCase() as OpenAPIV3.HttpMethods)
+    ) as OpenAPIV3.HttpMethods[];
+
+    // Check if methods array is empty *after* filtering
+    if (methods.length === 0) {
+      // Return a specific non-error message indicating no methods were found
+      return [
+        {
+          uriSuffix: this.pathUriSuffix,
+          data: `No standard HTTP methods found for path: ${decodeURIComponent(
+            this.pathUriSuffix.substring('paths/'.length) // Get original path for display
+          )}`,
+          renderAsList: true,
+          // isError is implicitly false here
+        },
+      ];
+    }
+
+    // Generate hint first using the new structure
+    const hint = generateListHint(context, {
+      itemType: 'pathMethod',
+      parentPath: this.path, // Use the stored raw path
+    });
+    // Hint includes leading newline, so start output with it directly
+    let outputLines: string[] = [hint.trim(), '']; // Trim leading newline from hint for first line
+
+    methods.sort().forEach(method => {
+      const operation = this.getOperation(method);
+      // Use summary or operationId (via getOperationSummary)
+      const summaryText = getOperationSummary(operation);
+      // Format as METHOD: Summary or just METHOD if no summary/opId
+      outputLines.push(`${method.toUpperCase()}${summaryText ? `: ${summaryText}` : ''}`);
+    });
+
+    return [
+      {
+        uriSuffix: this.pathUriSuffix,
+        data: outputLines.join('\n'), // Join lines into a single string
+        renderAsList: true,
+      },
+    ];
+  }
+
+  /**
+   * Renders the detail view for one or more specific operations (methods)
+   * Renders the detail view. For a PathItem, this usually means listing
+   * the methods, similar to renderList. The handler should call
+   * `renderOperationDetail` for specific method details.
+   */
+  renderDetail(context: RenderContext): RenderResultItem[] {
+    // Delegate to renderList as the primary view for a path item itself.
+    return this.renderList(context);
+  }
+
+  /**
+   * Renders the detail view for one or more specific operations (methods)
+   * within this path item.
+   * Corresponds to the `openapi://paths/{path}/{method*}` URI.
+   * This is called by the handler after identifying the method(s).
+   *
+   * @param context - The rendering context.
+   * @param methods - Array of method names (e.g., ['get', 'post']).
+   * @returns An array of RenderResultItem representing the operation details.
+   */
+  renderOperationDetail(
+    _context: RenderContext, // Context might be needed later
+    methods: string[]
+  ): RenderResultItem[] {
+    if (!this.pathItem) {
+      // Create error results for all requested methods if path item is missing
+      return methods.map(method => ({
+        uriSuffix: `${this.pathUriSuffix}/${method}`,
+        data: null,
+        isError: true,
+        errorText: 'Path item not found.',
+        renderAsList: true,
+      }));
+    }
+
+    const results: RenderResultItem[] = [];
+
+    for (const method of methods) {
+      const operation = this.getOperation(method);
+      const operationUriSuffix = `${this.pathUriSuffix}/${method}`;
+
+      if (!operation) {
+        results.push({
+          uriSuffix: operationUriSuffix,
+          data: null,
+          isError: true,
+          errorText: `Method "${method.toUpperCase()}" not found for path.`,
+          renderAsList: true,
+        });
+      } else {
+        // Return the raw operation object; handler will format it
+        results.push({
+          uriSuffix: operationUriSuffix,
+          data: operation,
+          // isError: false (default)
+          // renderAsList: false (default)
+        });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Gets the OperationObject for a specific HTTP method within this path item.
+   * Performs case-insensitive lookup.
+   * @param method - The HTTP method string (e.g., 'get', 'POST').
+   * @returns The OperationObject or undefined if not found.
+   */
+  getOperation(method: string): OpenAPIV3.OperationObject | undefined {
+    if (!this.pathItem) {
+      return undefined;
+    }
+    const lowerMethod = method.toLowerCase();
+
+    // Check if the key is a standard HTTP method defined in the enum
+    if (Object.values(OpenAPIV3.HttpMethods).includes(lowerMethod as OpenAPIV3.HttpMethods)) {
+      const operation = this.pathItem[lowerMethod as keyof OpenAPIV3.PathItemObject];
+      // Basic check to ensure it looks like an operation object
+      if (typeof operation === 'object' && operation !== null && 'responses' in operation) {
+        // The check above narrows the type sufficiently, assertion is redundant
+        return operation;
+      }
+    }
+    return undefined; // Not a valid method or not an operation object
+  }
+}

package/src/rendering/paths.ts

@@ -0,0 +1,87 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderableSpecObject, RenderContext, RenderResultItem } from './types.js'; // Add .js
+
+/**
+ * Wraps an OpenAPIV3.PathsObject to make it renderable.
+ * Handles rendering the list of all paths and methods.
+ */
+export class RenderablePaths implements RenderableSpecObject {
+  constructor(private paths: OpenAPIV3.PathsObject | undefined) {}
+
+  /**
+   * Renders a token-efficient list of all paths and their methods.
+   * Corresponds to the `openapi://paths` URI.
+   */
+  renderList(context: RenderContext): RenderResultItem[] {
+    if (!this.paths || Object.keys(this.paths).length === 0) {
+      return [
+        {
+          uriSuffix: 'paths',
+          data: 'No paths found in the specification.',
+          renderAsList: true,
+        },
+      ];
+    }
+
+    // Generate hint first and prepend "Hint: "
+    const hintText = `Use '${context.baseUri}paths/{encoded_path}' to list methods for a specific path, or '${context.baseUri}paths/{encoded_path}/{method}' to view details for a specific operation.`;
+    let outputLines: string[] = [`Hint: ${hintText}`, '']; // Start with hint and a blank line
+
+    const pathEntries = Object.entries(this.paths).sort(([pathA], [pathB]) =>
+      pathA.localeCompare(pathB)
+    );
+
+    for (const [path, pathItem] of pathEntries) {
+      if (!pathItem) continue;
+
+      // Create a list of valid, sorted, uppercase methods for the current path
+      const methods: string[] = [];
+      for (const key in pathItem) {
+        const lowerKey = key.toLowerCase();
+        if (Object.values(OpenAPIV3.HttpMethods).includes(lowerKey as OpenAPIV3.HttpMethods)) {
+          // Check if it's a valid operation object before adding the method
+          const operation = pathItem[key as keyof OpenAPIV3.PathItemObject];
+          if (typeof operation === 'object' && operation !== null && 'responses' in operation) {
+            methods.push(lowerKey.toUpperCase());
+          }
+        }
+      }
+      methods.sort(); // Sort methods alphabetically
+
+      // Format the line: METHODS /path
+      const methodsString = methods.length > 0 ? methods.join(' ') : '(No methods)';
+      outputLines.push(`${methodsString} ${path}`);
+    }
+
+    return [
+      {
+        uriSuffix: 'paths',
+        data: outputLines.join('\n'), // Join lines into a single string
+        renderAsList: true, // This result is always plain text
+      },
+    ];
+  }
+
+  /**
+   * Renders the detail view. For the Paths object level, this isn't
+   * typically used directly. Details are requested per path or operation.
+   */
+  renderDetail(context: RenderContext): RenderResultItem[] {
+    // Delegate to renderList as the primary view for the collection of paths
+    return this.renderList(context);
+  }
+
+  /**
+   * Gets the PathItemObject for a specific path.
+   * @param path - The decoded path string.
+   * @returns The PathItemObject or undefined if not found.
+   */
+  getPathItem(path: string): OpenAPIV3.PathItemObject | undefined {
+    // Use Map for safe access
+    if (!this.paths) {
+      return undefined;
+    }
+    const pathsMap = new Map(Object.entries(this.paths));
+    return pathsMap.get(path); // Map.get returns ValueType | undefined
+  }
+}

package/src/rendering/types.ts

@@ -0,0 +1,63 @@
+import { IFormatter } from '../services/formatters';
+// We don't need ResourceContents/ResourceContent here anymore
+
+/**
+ * Intermediate result structure returned by render methods.
+ * Contains the core data needed to build the final ResourceContent.
+ */
+export interface RenderResultItem {
+  /** The raw data object to be formatted. */
+  data: unknown;
+  /** The suffix to append to the base URI (e.g., 'info', 'paths/users', 'components/schemas/User'). */
+  uriSuffix: string;
+  /** Optional flag indicating an error for this specific item. */
+  isError?: boolean;
+  /** Optional error message if isError is true. */
+  errorText?: string;
+  /** Optional flag to indicate this should be rendered as a list (text/plain). */
+  renderAsList?: boolean;
+}
+
+/**
+ * Context required for rendering OpenAPI specification objects.
+ */
+export interface RenderContext {
+  /** Formatter instance for handling output (JSON/YAML). */
+  formatter: IFormatter;
+  /** Base URI for generating resource links (e.g., "openapi://"). */
+  baseUri: string;
+}
+
+/**
+ * Represents an OpenAPI specification object that can be rendered
+ * in different formats (list or detail).
+ */
+export interface RenderableSpecObject {
+  /**
+   * Generates data for a token-efficient list representation.
+   * @param context - The rendering context.
+   * @returns An array of RenderResultItem.
+   */
+  renderList(context: RenderContext): RenderResultItem[];
+
+  /**
+   * Generates data for a detailed representation.
+   * @param context - The rendering context.
+   * @returns An array of RenderResultItem.
+   */
+  renderDetail(context: RenderContext): RenderResultItem[];
+}
+
+/**
+ * Type guard to check if an object implements RenderableSpecObject.
+ * @param obj - The object to check.
+ * @returns True if the object implements RenderableSpecObject, false otherwise.
+ */
+export function isRenderableSpecObject(obj: unknown): obj is RenderableSpecObject {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof (obj as RenderableSpecObject).renderList === 'function' &&
+    typeof (obj as RenderableSpecObject).renderDetail === 'function'
+  );
+}

package/src/rendering/utils.ts

@@ -0,0 +1,107 @@
+// NOTE: This block replaces the previous import block to ensure types/interfaces are defined correctly.
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderContext, RenderResultItem } from './types.js'; // Add .js
+import {
+  buildComponentDetailUriSuffix,
+  buildComponentMapUriSuffix,
+  buildOperationUriSuffix,
+  // buildPathItemUriSuffix, // Not currently used by generateListHint
+} from '../utils/uri-builder.js'; // Added .js extension
+
+// Define possible types for list items to guide hint generation
+type ListItemType = 'componentType' | 'componentName' | 'pathMethod';
+
+// Define context needed for generating the correct detail URI suffix
+interface HintContext {
+  itemType: ListItemType;
+  // For componentName hints, the parent component type is needed
+  parentComponentType?: string;
+  // For pathMethod hints, the parent path is needed
+  parentPath?: string;
+}
+
+/**
+ * Safely retrieves the summary from an Operation object.
+ * Handles cases where the operation might be undefined or lack a summary.
+ *
+ * @param operation - The Operation object or undefined.
+ * @returns The operation summary or operationId string, truncated if necessary, or null if neither is available.
+ */
+export function getOperationSummary(
+  operation: OpenAPIV3.OperationObject | undefined
+): string | null {
+  // Return summary or operationId without truncation
+  return operation?.summary || operation?.operationId || null;
+}
+
+/**
+ * Helper to generate a standard hint text for list views, using the centralized URI builders.
+ * @param renderContext - The rendering context containing the base URI.
+ * @param hintContext - Context about the type of items being listed and their parent context.
+ * @returns The hint string.
+ */
+export function generateListHint(renderContext: RenderContext, hintContext: HintContext): string {
+  let detailUriSuffixPattern: string;
+  let itemTypeName: string; // User-friendly name for the item type in the hint text
+
+  switch (hintContext.itemType) {
+    case 'componentType':
+      // Listing component types (e.g., schemas, responses) at openapi://components
+      // Hint should point to openapi://components/{type}
+      detailUriSuffixPattern = buildComponentMapUriSuffix('{type}'); // Use placeholder
+      itemTypeName = 'component type';
+      break;
+    case 'componentName':
+      // Listing component names (e.g., MySchema, User) at openapi://components/{type}
+      // Hint should point to openapi://components/{type}/{name}
+      if (!hintContext.parentComponentType) {
+        console.warn('generateListHint called for componentName without parentComponentType');
+        return ''; // Avoid generating a broken hint
+      }
+      // Use the actual parent type and a placeholder for the name
+      detailUriSuffixPattern = buildComponentDetailUriSuffix(
+        hintContext.parentComponentType,
+        '{name}'
+      );
+      itemTypeName = hintContext.parentComponentType.slice(0, -1); // e.g., 'schema' from 'schemas'
+      break;
+    case 'pathMethod':
+      // Listing methods (e.g., get, post) at openapi://paths/{path}
+      // Hint should point to openapi://paths/{path}/{method}
+      if (!hintContext.parentPath) {
+        console.warn('generateListHint called for pathMethod without parentPath');
+        return ''; // Avoid generating a broken hint
+      }
+      // Use the actual parent path and a placeholder for the method
+      detailUriSuffixPattern = buildOperationUriSuffix(hintContext.parentPath, '{method}');
+      itemTypeName = 'operation'; // Or 'method'? 'operation' seems clearer
+      break;
+    default:
+      // Explicitly cast to string to avoid potential 'never' type issue in template literal
+      console.warn(`Unknown itemType in generateListHint: ${String(hintContext.itemType)}`);
+      return ''; // Avoid generating a hint if context is unknown
+  }
+
+  // Construct the full hint URI pattern using the base URI
+  const fullHintPattern = `${renderContext.baseUri}${detailUriSuffixPattern}`;
+
+  return `\nHint: Use '${fullHintPattern}' to view details for a specific ${itemTypeName}.`;
+}
+
+/**
+ * Helper to generate a standard error item for RenderResultItem arrays.
+ * @param uriSuffix - The URI suffix for the error context.
+ * @param message - The error message.
+ * @returns A RenderResultItem array containing the error.
+ */
+export function createErrorResult(uriSuffix: string, message: string): RenderResultItem[] {
+  return [
+    {
+      uriSuffix: uriSuffix,
+      data: null,
+      isError: true,
+      errorText: message,
+      renderAsList: true, // Errors are typically plain text
+    },
+  ];
+}

package/src/services/formatters.ts

@@ -0,0 +1,71 @@
+import { dump as yamlDump } from 'js-yaml';
+
+/**
+ * Supported output formats
+ */
+export type OutputFormat = 'json' | 'yaml' | 'json-minified';
+
+/**
+ * Interface for formatters that handle different output formats
+ */
+export interface IFormatter {
+  format(data: unknown): string;
+  getMimeType(): string;
+}
+
+/**
+ * JSON formatter with pretty printing
+ */
+export class JsonFormatter implements IFormatter {
+  format(data: unknown): string {
+    return JSON.stringify(data, null, 2);
+  }
+
+  getMimeType(): string {
+    return 'application/json';
+  }
+}
+
+/**
+ * Formats data as minified JSON.
+ */
+export class MinifiedJsonFormatter implements IFormatter {
+  format(data: unknown): string {
+    return JSON.stringify(data);
+  }
+
+  getMimeType(): string {
+    return 'application/json';
+  }
+}
+
+/**
+ * YAML formatter using js-yaml library
+ */
+export class YamlFormatter implements IFormatter {
+  format(data: unknown): string {
+    return yamlDump(data, {
+      indent: 2,
+      lineWidth: -1, // Don't wrap long lines
+      noRefs: true, // Don't use references
+    });
+  }
+
+  getMimeType(): string {
+    return 'text/yaml';
+  }
+}
+
+/**
+ * Creates a formatter instance based on format name
+ */
+export function createFormatter(format: OutputFormat): IFormatter {
+  switch (format) {
+    case 'json':
+      return new JsonFormatter();
+    case 'yaml':
+      return new YamlFormatter();
+    case 'json-minified':
+      return new MinifiedJsonFormatter();
+  }
+}

package/src/services/reference-transform.ts

@@ -0,0 +1,105 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { buildComponentDetailUri } from '../utils/uri-builder.js'; // Added .js extension
+
+export interface TransformContext {
+  resourceType: 'endpoint' | 'schema';
+  format: 'openapi' | 'asyncapi' | 'graphql';
+  path?: string;
+  method?: string;
+}
+
+export interface ReferenceObject {
+  $ref: string;
+}
+
+export interface TransformedReference {
+  $ref: string;
+}
+
+export interface ReferenceTransform<T> {
+  transformRefs(document: T, context: TransformContext): T;
+}
+
+export class ReferenceTransformService {
+  private transformers = new Map<string, ReferenceTransform<unknown>>();
+
+  registerTransformer<T>(format: string, transformer: ReferenceTransform<T>): void {
+    this.transformers.set(format, transformer as ReferenceTransform<unknown>);
+  }
+
+  transformDocument<T>(document: T, context: TransformContext): T {
+    const transformer = this.transformers.get(context.format) as ReferenceTransform<T>;
+    if (!transformer) {
+      throw new Error(`No transformer registered for format: ${context.format}`);
+    }
+    return transformer.transformRefs(document, context);
+  }
+}
+
+export class OpenAPITransformer implements ReferenceTransform<OpenAPIV3.Document> {
+  // Handle nested objects recursively
+  private transformObject(obj: unknown, _context: TransformContext): unknown {
+    if (!obj || typeof obj !== 'object') {
+      return obj;
+    }
+
+    // Handle arrays
+    if (Array.isArray(obj)) {
+      return obj.map(item => this.transformObject(item, _context));
+    }
+
+    // Handle references
+    if (this.isReferenceObject(obj)) {
+      return this.transformReference(obj.$ref);
+    }
+
+    // Recursively transform object properties
+    const result: Record<string, unknown> = {};
+    if (typeof obj === 'object') {
+      for (const [key, value] of Object.entries(obj)) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+          Object.defineProperty(result, key, {
+            value: this.transformObject(value, _context),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+          });
+        }
+      }
+    }
+    return result;
+  }
+
+  private isReferenceObject(obj: unknown): obj is ReferenceObject {
+    return typeof obj === 'object' && obj !== null && '$ref' in obj;
+  }
+
+  private transformReference(ref: string): TransformedReference {
+    // Handle only internal references for now
+    if (!ref.startsWith('#/')) {
+      return { $ref: ref }; // Keep external refs as-is
+    }
+
+    // Example ref: #/components/schemas/MySchema
+    const parts = ref.split('/');
+    // Check if it's an internal component reference
+    if (parts[0] === '#' && parts[1] === 'components' && parts.length === 4) {
+      const componentType = parts[2];
+      const componentName = parts[3];
+
+      // Use the centralized builder to create the correct URI
+      const newUri = buildComponentDetailUri(componentType, componentName);
+      return {
+        $ref: newUri,
+      };
+    }
+
+    // Keep other internal references (#/paths/...) and external references as-is
+    return { $ref: ref };
+  }
+
+  transformRefs(document: OpenAPIV3.Document, context: TransformContext): OpenAPIV3.Document {
+    const transformed = this.transformObject(document, context);
+    return transformed as OpenAPIV3.Document;
+  }
+}

package/src/services/spec-loader.ts

@@ -0,0 +1,88 @@
+import * as swagger2openapi from 'swagger2openapi';
+import { OpenAPI } from 'openapi-types';
+import { ReferenceTransformService, TransformContext } from './reference-transform.js';
+
+/**
+ * Service for loading and transforming OpenAPI specifications
+ */
+export class SpecLoaderService {
+  private specData: OpenAPI.Document | null = null;
+
+  constructor(
+    private specPath: string,
+    private referenceTransform: ReferenceTransformService
+  ) {}
+
+  /**
+   * Load, potentially convert (from v2), and parse the OpenAPI specification.
+   */
+  async loadSpec(): Promise<OpenAPI.Document> {
+    const options = {
+      patch: true, // Fix minor errors in the spec
+      warnOnly: true, // Add warnings for non-patchable errors instead of throwing
+      origin: this.specPath, // Helps with resolving relative references if needed
+      source: this.specPath,
+    };
+
+    try {
+      let result;
+      // Check if specPath is a URL
+      if (this.specPath.startsWith('http://') || this.specPath.startsWith('https://')) {
+        result = await swagger2openapi.convertUrl(this.specPath, options);
+      } else {
+        result = await swagger2openapi.convertFile(this.specPath, options);
+      }
+
+      // swagger2openapi returns the result in result.openapi
+      if (!result || !result.openapi) {
+        throw new Error('Conversion or parsing failed to produce an OpenAPI document.');
+      }
+
+      // TODO: Check result.options?.warnings for potential issues?
+
+      this.specData = result.openapi as OpenAPI.Document; // Assuming result.openapi is compatible
+      return this.specData;
+    } catch (error) {
+      // Improve error message clarity
+      let message = `Failed to load/convert OpenAPI spec from ${this.specPath}: `;
+      if (error instanceof Error) {
+        message += error.message;
+        // Include stack trace if available and helpful?
+        // console.error(error.stack);
+      } else {
+        message += String(error);
+      }
+      throw new Error(message);
+    }
+  }
+
+  /**
+   * Get the loaded specification
+   */
+  async getSpec(): Promise<OpenAPI.Document> {
+    if (!this.specData) {
+      await this.loadSpec();
+    }
+    return this.specData!;
+  }
+
+  /**
+   * Get transformed specification with MCP resource references
+   */
+  async getTransformedSpec(context: TransformContext): Promise<OpenAPI.Document> {
+    const spec = await this.getSpec();
+    return this.referenceTransform.transformDocument(spec, context);
+  }
+}
+
+/**
+ * Create and initialize a new SpecLoaderService instance
+ */
+export async function createSpecLoader(
+  specPath: string,
+  referenceTransform: ReferenceTransformService
+): Promise<SpecLoaderService> {
+  const loader = new SpecLoaderService(specPath, referenceTransform);
+  await loader.loadSpec();
+  return loader;
+}