mcp-openapi-schema-explorer 1.0.0

package/src/handlers/handler-utils.ts

@@ -0,0 +1,230 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { RenderContext, RenderResultItem } from '../rendering/types.js'; // Already has .js
+// Remove McpError/ErrorCode import - use standard Error
+
+// Define the structure expected for each item in the contents array
+export type FormattedResultItem = {
+  uri: string;
+  mimeType?: string;
+  text: string;
+  isError?: boolean;
+};
+
+/**
+ * Formats RenderResultItem array into an array compatible with the 'contents'
+ * property of ReadResourceResultSchema (specifically TextResourceContents).
+ */
+export function formatResults(
+  context: RenderContext,
+  items: RenderResultItem[]
+): FormattedResultItem[] {
+  // Add type check for formatter existence in context
+  if (!context.formatter) {
+    throw new Error('Formatter is missing in RenderContext for formatResults');
+  }
+  return items.map(item => {
+    const uri = `${context.baseUri}${item.uriSuffix}`;
+    let text: string;
+    let mimeType: string;
+
+    if (item.isError) {
+      text = item.errorText || 'An unknown error occurred.';
+      mimeType = 'text/plain';
+    } else if (item.renderAsList) {
+      text = typeof item.data === 'string' ? item.data : 'Invalid list data';
+      mimeType = 'text/plain';
+    } else {
+      // Detail view: format using the provided formatter
+      try {
+        text = context.formatter.format(item.data);
+        mimeType = context.formatter.getMimeType();
+      } catch (formatError: unknown) {
+        text = `Error formatting data for ${uri}: ${
+          formatError instanceof Error ? formatError.message : String(formatError)
+        }`;
+        mimeType = 'text/plain';
+        // Ensure isError is true if formatting fails
+        item.isError = true;
+        item.errorText = text; // Store the formatting error message
+      }
+    }
+
+    // Construct the final object, prioritizing item.isError
+    const finalItem: FormattedResultItem = {
+      uri: uri,
+      mimeType: mimeType,
+      text: item.isError ? item.errorText || 'An unknown error occurred.' : text,
+      isError: item.isError ?? false, // Default to false if not explicitly set
+    };
+    // Ensure mimeType is text/plain for errors
+    if (finalItem.isError) {
+      finalItem.mimeType = 'text/plain';
+    }
+
+    return finalItem;
+  });
+}
+
+/**
+ * Type guard to check if an object is an OpenAPIV3.Document.
+ */
+export function isOpenAPIV3(spec: unknown): spec is OpenAPIV3.Document {
+  return (
+    typeof spec === 'object' &&
+    spec !== null &&
+    'openapi' in spec &&
+    typeof (spec as { openapi: unknown }).openapi === 'string' &&
+    (spec as { openapi: string }).openapi.startsWith('3.')
+  );
+}
+
+/**
+ * Safely retrieves a PathItemObject from the specification using a Map.
+ * Throws an McpError if the path is not found.
+ *
+ * @param spec The OpenAPIV3 Document.
+ * @param path The decoded path string (e.g., '/users/{id}').
+ * @returns The validated PathItemObject.
+ * @throws {McpError} If the path is not found in spec.paths.
+ */
+export function getValidatedPathItem(
+  spec: OpenAPIV3.Document,
+  path: string
+): OpenAPIV3.PathItemObject {
+  if (!spec.paths) {
+    // Use standard Error
+    throw new Error('Specification does not contain any paths.');
+  }
+  const pathsMap = new Map(Object.entries(spec.paths));
+  const pathItem = pathsMap.get(path);
+
+  if (!pathItem) {
+    const errorMessage = `Path "${path}" not found in the specification.`;
+    // Use standard Error
+    throw new Error(errorMessage);
+  }
+  // We assume the spec structure is valid if the key exists
+  return pathItem as OpenAPIV3.PathItemObject;
+}
+
+/**
+ * Validates requested HTTP methods against a PathItemObject using a Map.
+ * Returns the list of valid requested methods.
+ * Throws an McpError if none of the requested methods are valid for the path item.
+ *
+ * @param pathItem The PathItemObject to check against.
+ * @param requestedMethods An array of lowercase HTTP methods requested by the user.
+ * @param pathForError The path string, used for creating informative error messages.
+ * @returns An array of the requested methods that are valid for this path item.
+ * @throws {McpError} If none of the requested methods are valid.
+ */
+export function getValidatedOperations(
+  pathItem: OpenAPIV3.PathItemObject,
+  requestedMethods: string[],
+  pathForError: string
+): string[] {
+  const operationsMap = new Map<string, OpenAPIV3.OperationObject>();
+  Object.entries(pathItem).forEach(([method, operation]) => {
+    // Check if the key is a standard HTTP method before adding
+    if (
+      ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'].includes(
+        method.toLowerCase()
+      )
+    ) {
+      operationsMap.set(method.toLowerCase(), operation as OpenAPIV3.OperationObject);
+    }
+  });
+
+  // Validate using lowercase versions, but preserve original case for return
+  const requestedMethodsLower = requestedMethods.map(m => m.toLowerCase());
+  const validLowerMethods = requestedMethodsLower.filter(m => operationsMap.has(m));
+
+  if (validLowerMethods.length === 0) {
+    const availableMethods = Array.from(operationsMap.keys()).join(', ');
+    // Show original case in error message for clarity
+    const errorMessage = `None of the requested methods (${requestedMethods.join(', ')}) are valid for path "${pathForError}". Available methods: ${availableMethods}`;
+    // Use standard Error
+    throw new Error(errorMessage);
+  }
+
+  // Return the methods from the *original* requestedMethods array
+  // that correspond to the valid lowercase methods found.
+  return requestedMethods.filter(m => validLowerMethods.includes(m.toLowerCase()));
+}
+
+/**
+ * Safely retrieves the component map for a specific type (e.g., schemas, responses)
+ * from the specification using a Map.
+ * Throws an McpError if spec.components or the specific type map is not found.
+ *
+ * @param spec The OpenAPIV3 Document.
+ * @param type The ComponentType string (e.g., 'schemas', 'responses').
+ * @returns The validated component map object (e.g., spec.components.schemas).
+ * @throws {McpError} If spec.components or the type map is not found.
+ */
+export function getValidatedComponentMap(
+  spec: OpenAPIV3.Document,
+  type: string // Keep as string for validation flexibility
+): NonNullable<OpenAPIV3.ComponentsObject[keyof OpenAPIV3.ComponentsObject]> {
+  if (!spec.components) {
+    // Use standard Error
+    throw new Error('Specification does not contain a components section.');
+  }
+  // Validate the requested type against the actual keys in spec.components
+  const componentsMap = new Map(Object.entries(spec.components));
+  // Add type assertion for clarity, although the check below handles undefined
+  const componentMapObj = componentsMap.get(type) as
+    | OpenAPIV3.ComponentsObject[keyof OpenAPIV3.ComponentsObject]
+    | undefined;
+
+  if (!componentMapObj) {
+    const availableTypes = Array.from(componentsMap.keys()).join(', ');
+    const errorMessage = `Component type "${type}" not found in the specification. Available types: ${availableTypes}`;
+    // Use standard Error
+    throw new Error(errorMessage);
+  }
+  // We assume the spec structure is valid if the key exists
+  return componentMapObj as NonNullable<
+    OpenAPIV3.ComponentsObject[keyof OpenAPIV3.ComponentsObject]
+  >;
+}
+
+/**
+ * Validates requested component names against a specific component map (e.g., schemas).
+ * Returns an array of objects containing the valid name and its corresponding detail object.
+ * Throws an McpError if none of the requested names are valid for the component map.
+ *
+ * @param componentMap The specific component map object (e.g., spec.components.schemas).
+ * @param requestedNames An array of component names requested by the user.
+ * @param componentTypeForError The component type string, used for creating informative error messages.
+ * @param detailsMap A Map created from the specific component map object (e.g., new Map(Object.entries(spec.components.schemas))).
+ * @param requestedNames An array of component names requested by the user.
+ * @param componentTypeForError The component type string, used for creating informative error messages.
+ * @returns An array of { name: string, detail: V } for valid requested names, where V is the value type of the Map.
+ * @throws {McpError} If none of the requested names are valid.
+ */
+// Modify to accept a Map directly
+export function getValidatedComponentDetails<V extends OpenAPIV3.ReferenceObject | object>(
+  detailsMap: Map<string, V>, // Accept Map<string, V>
+  requestedNames: string[],
+  componentTypeForError: string
+): { name: string; detail: V }[] {
+  // No longer need to create the map inside the function
+  const validDetails = requestedNames
+    .map(name => {
+      const detail = detailsMap.get(name); // detail will be V | undefined
+      return detail ? { name, detail } : null;
+    })
+    // Type predicate ensures we filter out nulls and have the correct type
+    .filter((item): item is { name: string; detail: V } => item !== null);
+
+  if (validDetails.length === 0) {
+    // Sort available names for deterministic error messages
+    const availableNames = Array.from(detailsMap.keys()).sort().join(', ');
+    const errorMessage = `None of the requested names (${requestedNames.join(', ')}) are valid for component type "${componentTypeForError}". Available names: ${availableNames}`;
+    // Use standard Error
+    throw new Error(errorMessage);
+  }
+
+  return validDetails;
+}

package/src/handlers/operation-handler.ts

@@ -0,0 +1,114 @@
+import {
+  ReadResourceTemplateCallback,
+  ResourceTemplate,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { SpecLoaderService } from '../types.js';
+import { IFormatter } from '../services/formatters.js';
+import { RenderablePathItem } from '../rendering/path-item.js';
+import { RenderContext, RenderResultItem } from '../rendering/types.js';
+import { createErrorResult } from '../rendering/utils.js';
+import { buildPathItemUriSuffix } from '../utils/uri-builder.js'; // Added .js extension
+// Import shared handler utils
+import {
+  formatResults,
+  isOpenAPIV3,
+  FormattedResultItem,
+  getValidatedPathItem, // Import new helper
+  getValidatedOperations, // Import new helper
+} from './handler-utils.js'; // Already has .js
+
+const BASE_URI = 'openapi://';
+
+// Removed duplicated FormattedResultItem type - now imported from handler-utils
+// Removed duplicated formatResults function - now imported from handler-utils
+// Removed duplicated isOpenAPIV3 function - now imported from handler-utils
+
+/**
+ * Handles requests for specific operation details within a path.
+ * Corresponds to the `openapi://paths/{path}/{method*}` template.
+ */
+export class OperationHandler {
+  constructor(
+    private specLoader: SpecLoaderService,
+    private formatter: IFormatter
+  ) {}
+
+  getTemplate(): ResourceTemplate {
+    // TODO: Add completion logic if needed
+    return new ResourceTemplate(`${BASE_URI}paths/{path}/{method*}`, {
+      list: undefined,
+      complete: undefined,
+    });
+  }
+
+  handleRequest: ReadResourceTemplateCallback = async (
+    uri: URL,
+    variables: Variables
+  ): Promise<{ contents: FormattedResultItem[] }> => {
+    const encodedPath = variables.path as string;
+    // Correct variable access key: 'method', not 'method*'
+    const methodVar = variables['method']; // Can be string or string[]
+    // Decode the path received from the URI variable
+    const decodedPath = decodeURIComponent(encodedPath || '');
+    // Use the builder to create the suffix, which will re-encode the path correctly
+    const pathUriSuffix = buildPathItemUriSuffix(decodedPath);
+    const context: RenderContext = { formatter: this.formatter, baseUri: BASE_URI };
+    let resultItems: RenderResultItem[];
+
+    try {
+      // Normalize methods: Handle string for single value, array for multiple.
+      let methods: string[] = [];
+      if (Array.isArray(methodVar)) {
+        methods = methodVar.map(m => String(m).trim().toLowerCase()); // Ensure elements are strings
+      } else if (typeof methodVar === 'string') {
+        methods = [methodVar.trim().toLowerCase()]; // Treat as single item array
+      }
+      methods = methods.filter(m => m.length > 0); // Remove empty strings
+
+      if (methods.length === 0) {
+        throw new Error('No valid HTTP method specified.');
+      }
+
+      const spec = await this.specLoader.getTransformedSpec({
+        resourceType: 'schema', // Use 'schema' for now
+        format: 'openapi',
+      });
+
+      // Use imported type guard
+      if (!isOpenAPIV3(spec)) {
+        throw new Error('Only OpenAPI v3 specifications are supported');
+      }
+
+      // --- Use helper to get validated path item ---
+      const lookupPath = decodedPath.startsWith('/') ? decodedPath : `/${decodedPath}`;
+      const pathItemObj = getValidatedPathItem(spec, lookupPath);
+
+      // --- Use helper to get validated requested methods ---
+      const validMethods = getValidatedOperations(pathItemObj, methods, lookupPath);
+
+      // Instantiate RenderablePathItem with the validated pathItemObj
+      const renderablePathItem = new RenderablePathItem(
+        pathItemObj, // pathItemObj retrieved safely via helper
+        lookupPath, // Pass the raw, decoded path
+        pathUriSuffix // Pass the correctly built suffix
+      );
+
+      // Use the validated methods returned by the helper
+      resultItems = renderablePathItem.renderOperationDetail(context, validMethods);
+    } catch (error: unknown) {
+      // Catch errors from helpers (e.g., path/method not found) or rendering
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error handling request ${uri.href}: ${message}`);
+      // Create a single error item representing the overall request failure
+      resultItems = createErrorResult(
+        uri.href.substring(BASE_URI.length), // Use request URI suffix
+        message
+      );
+    }
+
+    // Use imported formatResults
+    const contents = formatResults(context, resultItems);
+    return { contents };
+  };
+}

package/src/handlers/path-item-handler.ts

@@ -0,0 +1,88 @@
+import {
+  ReadResourceTemplateCallback,
+  ResourceTemplate,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { SpecLoaderService } from '../types.js';
+import { IFormatter } from '../services/formatters.js';
+import { RenderablePathItem } from '../rendering/path-item.js';
+import { RenderContext, RenderResultItem } from '../rendering/types.js';
+import { createErrorResult } from '../rendering/utils.js';
+import { buildPathItemUriSuffix } from '../utils/uri-builder.js'; // Added .js extension
+// Import shared handler utils
+import {
+  formatResults,
+  isOpenAPIV3,
+  FormattedResultItem,
+  getValidatedPathItem, // Import the helper
+} from './handler-utils.js'; // Already has .js
+
+const BASE_URI = 'openapi://';
+
+// Removed duplicated FormattedResultItem type - now imported from handler-utils
+// Removed duplicated formatResults function - now imported from handler-utils
+// Removed duplicated isOpenAPIV3 function - now imported from handler-utils
+
+/**
+ * Handles requests for listing methods for a specific path.
+ * Corresponds to the `openapi://paths/{path}` template.
+ */
+export class PathItemHandler {
+  constructor(
+    private specLoader: SpecLoaderService,
+    private formatter: IFormatter // Although unused in list view, needed for context
+  ) {}
+
+  getTemplate(): ResourceTemplate {
+    // TODO: Add completion logic if needed
+    return new ResourceTemplate(`${BASE_URI}paths/{path}`, {
+      list: undefined,
+      complete: undefined,
+    });
+  }
+
+  handleRequest: ReadResourceTemplateCallback = async (
+    uri: URL,
+    variables: Variables
+  ): Promise<{ contents: FormattedResultItem[] }> => {
+    const encodedPath = variables.path as string;
+    // Decode the path received from the URI variable
+    const decodedPath = decodeURIComponent(encodedPath || '');
+    // Use the builder to create the suffix, which will re-encode the path correctly
+    const pathUriSuffix = buildPathItemUriSuffix(decodedPath);
+    const context: RenderContext = { formatter: this.formatter, baseUri: BASE_URI };
+    let resultItems: RenderResultItem[];
+
+    try {
+      const spec = await this.specLoader.getTransformedSpec({
+        resourceType: 'schema', // Use 'schema' for now
+        format: 'openapi',
+      });
+
+      // Use imported type guard
+      if (!isOpenAPIV3(spec)) {
+        throw new Error('Only OpenAPI v3 specifications are supported');
+      }
+
+      // --- Use helper to get validated path item ---
+      const lookupPath = decodedPath.startsWith('/') ? decodedPath : `/${decodedPath}`;
+      const pathItemObj = getValidatedPathItem(spec, lookupPath);
+
+      // Instantiate RenderablePathItem with the validated pathItemObj
+      const renderablePathItem = new RenderablePathItem(
+        pathItemObj, // pathItemObj retrieved safely via helper
+        lookupPath, // Pass the raw, decoded path
+        pathUriSuffix // Pass the correctly built suffix
+      );
+      resultItems = renderablePathItem.renderList(context);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error handling request ${uri.href}: ${message}`);
+      resultItems = createErrorResult(pathUriSuffix, message);
+    }
+
+    // Use imported formatResults
+    const contents = formatResults(context, resultItems);
+    return { contents };
+  };
+}

package/src/handlers/top-level-field-handler.ts

@@ -0,0 +1,92 @@
+import {
+  ReadResourceTemplateCallback,
+  ResourceTemplate,
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+// ResourceContents is the base type for a single item, not the array type needed here.
+// We'll define the array structure inline based on TextResourceContentsSchema.
+
+import { SpecLoaderService } from '../types.js';
+import { IFormatter } from '../services/formatters.js';
+import { RenderableDocument } from '../rendering/document.js';
+import { RenderablePaths } from '../rendering/paths.js';
+import { RenderableComponents } from '../rendering/components.js';
+import { RenderContext, RenderResultItem } from '../rendering/types.js';
+import { createErrorResult } from '../rendering/utils.js';
+// Import shared handler utils
+import { formatResults, isOpenAPIV3, FormattedResultItem } from './handler-utils.js'; // Already has .js
+
+const BASE_URI = 'openapi://';
+
+// Removed duplicated FormattedResultItem type - now imported from handler-utils
+// Removed duplicated formatResults function - now imported from handler-utils
+
+/**
+ * Handles requests for top-level OpenAPI fields (info, servers, paths list, components list).
+ * Corresponds to the `openapi://{field}` template.
+ */
+export class TopLevelFieldHandler {
+  constructor(
+    private specLoader: SpecLoaderService,
+    private formatter: IFormatter
+  ) {}
+
+  getTemplate(): ResourceTemplate {
+    // TODO: Add completion logic if needed
+    return new ResourceTemplate(`${BASE_URI}{field}`, {
+      list: undefined,
+      complete: undefined,
+    });
+  }
+
+  handleRequest: ReadResourceTemplateCallback = async (
+    uri: URL,
+    variables: Variables
+    // matchedTemplate is not needed if we only handle one template
+  ): Promise<{ contents: FormattedResultItem[] }> => {
+    // Return type uses the defined array structure
+    const field = variables.field as string;
+    const context: RenderContext = { formatter: this.formatter, baseUri: BASE_URI };
+    let resultItems: RenderResultItem[];
+
+    try {
+      const spec = await this.specLoader.getTransformedSpec({
+        // Use 'schema' as placeholder resourceType for transformation context
+        resourceType: 'schema',
+        format: 'openapi',
+      });
+
+      // Use imported type guard
+      if (!isOpenAPIV3(spec)) {
+        throw new Error('Only OpenAPI v3 specifications are supported');
+      }
+
+      const renderableDoc = new RenderableDocument(spec);
+
+      // Route based on the field name
+      if (field === 'paths') {
+        const pathsObj = renderableDoc.getPathsObject();
+        resultItems = new RenderablePaths(pathsObj).renderList(context);
+      } else if (field === 'components') {
+        const componentsObj = renderableDoc.getComponentsObject();
+        resultItems = new RenderableComponents(componentsObj).renderList(context);
+      } else {
+        // Handle other top-level fields (info, servers, tags, etc.)
+        const fieldObject = renderableDoc.getTopLevelField(field);
+        resultItems = renderableDoc.renderTopLevelFieldDetail(context, fieldObject, field);
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error handling request ${uri.href}: ${message}`);
+      resultItems = createErrorResult(field, message); // Use field as uriSuffix for error
+    }
+
+    // Format results into the final structure
+    const contents: FormattedResultItem[] = formatResults(context, resultItems);
+    // Return the object with the correctly typed contents array
+    // Use imported formatResults
+    return { contents };
+  };
+
+  // Removed duplicated isOpenAPIV3 type guard - now imported from handler-utils
+} // Ensure class closing brace is present