mcp-openapi-schema-explorer 1.0.0

package/src/types.ts

@@ -0,0 +1,17 @@
+import { OpenAPI } from 'openapi-types';
+import type { TransformContext } from './services/reference-transform.js';
+
+/** Common HTTP methods used in OpenAPI specs */
+export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'patch';
+
+/** Interface for spec loader */
+export interface SpecLoaderService {
+  getSpec(): Promise<OpenAPI.Document>;
+  getTransformedSpec(context: TransformContext): Promise<OpenAPI.Document>;
+}
+
+// Re-export transform types
+export type { TransformContext };
+
+// Re-export OpenAPI types
+export type { OpenAPI };

package/src/utils/uri-builder.ts

@@ -0,0 +1,134 @@
+/**
+ * Utility functions for building standardized MCP URIs for this server.
+ */
+
+const BASE_URI_SCHEME = 'openapi://';
+
+/**
+ * Encodes a string component for safe inclusion in a URI path segment.
+ * Uses standard encodeURIComponent.
+ * Encodes a path string for safe inclusion in a URI.
+ * This specifically targets path strings which might contain characters
+ * like '{', '}', etc., that need encoding when forming the URI path part.
+ * Uses standard encodeURIComponent.
+ * Encodes a path string for safe inclusion in a URI path segment.
+ * This is necessary because the path segment comes from the user potentially
+ * containing characters that need encoding (like '{', '}').
+ * Uses standard encodeURIComponent.
+ * @param path The path string to encode.
+ * @returns The encoded path string, with leading slashes removed before encoding.
+ */
+export function encodeUriPathComponent(path: string): string {
+  // Added export
+  // Remove leading slashes before encoding
+  const pathWithoutLeadingSlash = path.replace(/^\/+/, '');
+  return encodeURIComponent(pathWithoutLeadingSlash);
+}
+
+// --- Full URI Builders ---
+
+/**
+ * Builds the URI for accessing a specific component's details.
+ * Example: openapi://components/schemas/MySchema
+ * @param type The component type (e.g., 'schemas', 'responses').
+ * @param name The component name.
+ * @returns The full component detail URI.
+ */
+export function buildComponentDetailUri(type: string, name: string): string {
+  // Per user instruction, do not encode type or name here.
+  return `${BASE_URI_SCHEME}components/${type}/${name}`;
+}
+
+/**
+ * Builds the URI for listing components of a specific type.
+ * Example: openapi://components/schemas
+ * @param type The component type (e.g., 'schemas', 'responses').
+ * @returns The full component map URI.
+ */
+export function buildComponentMapUri(type: string): string {
+  // Per user instruction, do not encode type here.
+  return `${BASE_URI_SCHEME}components/${type}`;
+}
+
+/**
+ * Builds the URI for accessing a specific operation's details.
+ * Example: openapi://paths/users/{userId}/GET
+ * @param path The API path (e.g., '/users/{userId}').
+ * @param method The HTTP method (e.g., 'GET', 'POST').
+ * @returns The full operation detail URI.
+ */
+export function buildOperationUri(path: string, method: string): string {
+  // Encode only the path component. Assume 'path' is raw/decoded.
+  // Method is assumed to be safe or handled by SDK/client.
+  return `${BASE_URI_SCHEME}paths/${encodeUriPathComponent(path)}/${method.toLowerCase()}`; // Standardize method to lowercase
+}
+
+/**
+ * Builds the URI for listing methods available at a specific path.
+ * Example: openapi://paths/users/{userId}
+ * @param path The API path (e.g., '/users/{userId}').
+ * @returns The full path item URI.
+ */
+export function buildPathItemUri(path: string): string {
+  // Encode only the path component. Assume 'path' is raw/decoded.
+  return `${BASE_URI_SCHEME}paths/${encodeUriPathComponent(path)}`;
+}
+
+/**
+ * Builds the URI for accessing a top-level field (like 'info' or 'servers')
+ * or triggering a list view ('paths', 'components').
+ * Example: openapi://info, openapi://paths
+ * @param field The top-level field name.
+ * @returns The full top-level field URI.
+ */
+export function buildTopLevelFieldUri(field: string): string {
+  // Per user instruction, do not encode field here.
+  return `${BASE_URI_SCHEME}${field}`;
+}
+
+// --- URI Suffix Builders (for RenderResultItem) ---
+
+/**
+ * Builds the URI suffix for a specific component's details.
+ * Example: components/schemas/MySchema
+ */
+export function buildComponentDetailUriSuffix(type: string, name: string): string {
+  // Per user instruction, do not encode type or name here.
+  return `components/${type}/${name}`;
+}
+
+/**
+ * Builds the URI suffix for listing components of a specific type.
+ * Example: components/schemas
+ */
+export function buildComponentMapUriSuffix(type: string): string {
+  // Per user instruction, do not encode type here.
+  return `components/${type}`;
+}
+
+/**
+ * Builds the URI suffix for a specific operation's details.
+ * Example: paths/users/{userId}/get
+ */
+export function buildOperationUriSuffix(path: string, method: string): string {
+  // Encode only the path component for the suffix. Assume 'path' is raw/decoded.
+  return `paths/${encodeUriPathComponent(path)}/${method.toLowerCase()}`;
+}
+
+/**
+ * Builds the URI suffix for listing methods available at a specific path.
+ * Example: paths/users/{userId}
+ */
+export function buildPathItemUriSuffix(path: string): string {
+  // Encode only the path component for the suffix. Assume 'path' is raw/decoded.
+  return `paths/${encodeUriPathComponent(path)}`;
+}
+
+/**
+ * Builds the URI suffix for a top-level field.
+ * Example: info, paths
+ */
+export function buildTopLevelFieldUriSuffix(field: string): string {
+  // Per user instruction, do not encode field here.
+  return field;
+}

package/src/version.ts

@@ -0,0 +1,4 @@
+// Auto-generated by scripts/generate-version.js during semantic-release prepare step
+// Do not edit this file manually.
+
+export const VERSION = '1.0.0';

package/test/__tests__/e2e/format.test.ts

@@ -0,0 +1,224 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { startMcpServer, McpTestContext } from '../../utils/mcp-test-helpers.js'; // Import McpTestContext
+import { load as yamlLoad } from 'js-yaml';
+// Remove old test types/guards if not needed, or adapt them
+// import { isEndpointErrorResponse } from '../../utils/test-types.js';
+// import type { EndpointResponse, ResourceResponse } from '../../utils/test-types.js';
+// Import specific SDK types needed
+import { ReadResourceResult, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
+// Generic type guard for simple object check
+function isObject(obj: unknown): obj is Record<string, unknown> {
+  return typeof obj === 'object' && obj !== null;
+}
+
+// Type guard to check if content is TextResourceContents
+function hasTextContent(
+  content: ReadResourceResult['contents'][0]
+): content is TextResourceContents {
+  // Check for the 'text' property specifically and ensure it's not undefined
+  return content && typeof (content as TextResourceContents).text === 'string';
+}
+
+function parseJson(text: string | undefined): unknown {
+  if (text === undefined) throw new Error('Cannot parse undefined text');
+  return JSON.parse(text);
+}
+
+function parseYaml(text: string | undefined): unknown {
+  if (text === undefined) throw new Error('Cannot parse undefined text');
+  const result = yamlLoad(text);
+  if (result === undefined) {
+    throw new Error('Invalid YAML: parsing resulted in undefined');
+  }
+  return result;
+}
+
+function safeParse(text: string | undefined, format: 'json' | 'yaml'): unknown {
+  try {
+    return format === 'json' ? parseJson(text) : parseYaml(text);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse ${format} content: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+// Removed old parseEndpointResponse
+
+describe('Output Format E2E', () => {
+  let testContext: McpTestContext;
+  let client: Client;
+
+  afterEach(async () => {
+    await testContext?.cleanup();
+  });
+
+  describe('JSON format (default)', () => {
+    beforeEach(async () => {
+      testContext = await startMcpServer('test/fixtures/complex-endpoint.json', {
+        outputFormat: 'json',
+      });
+      client = testContext.client;
+    });
+
+    it('should return JSON for openapi://info', async () => {
+      const result = await client.readResource({ uri: 'openapi://info' });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('application/json');
+      if (!hasTextContent(content)) throw new Error('Expected text content'); // Add guard
+      expect(() => safeParse(content.text, 'json')).not.toThrow();
+      const data = safeParse(content.text, 'json');
+      expect(isObject(data) && data['title']).toBe('Complex Endpoint Test API'); // Use bracket notation after guard
+    });
+
+    it('should return JSON for operation detail', async () => {
+      const path = encodeURIComponent('api/v1/organizations/{orgId}/projects/{projectId}/tasks');
+      const result = await client.readResource({ uri: `openapi://paths/${path}/get` });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('application/json');
+      if (!hasTextContent(content)) throw new Error('Expected text content'); // Add guard
+      expect(() => safeParse(content.text, 'json')).not.toThrow();
+      const data = safeParse(content.text, 'json');
+      expect(isObject(data) && data['operationId']).toBe('getProjectTasks'); // Use bracket notation after guard
+    });
+
+    it('should return JSON for component detail', async () => {
+      const result = await client.readResource({ uri: 'openapi://components/schemas/Task' });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('application/json');
+      if (!hasTextContent(content)) throw new Error('Expected text content'); // Add guard
+      expect(() => safeParse(content.text, 'json')).not.toThrow();
+      const data = safeParse(content.text, 'json');
+      expect(isObject(data) && data['type']).toBe('object'); // Use bracket notation after guard
+      expect(
+        isObject(data) &&
+          isObject(data['properties']) &&
+          isObject(data['properties']['id']) &&
+          data['properties']['id']['type']
+      ).toBe('string'); // Use bracket notation with type checking
+    });
+  });
+
+  describe('YAML format', () => {
+    beforeEach(async () => {
+      testContext = await startMcpServer('test/fixtures/complex-endpoint.json', {
+        outputFormat: 'yaml',
+      });
+      client = testContext.client;
+    });
+
+    it('should return YAML for openapi://info', async () => {
+      const result = await client.readResource({ uri: 'openapi://info' });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('text/yaml');
+      if (!hasTextContent(content)) throw new Error('Expected text content'); // Add guard
+      expect(() => safeParse(content.text, 'yaml')).not.toThrow();
+      expect(content.text).toContain('title: Complex Endpoint Test API');
+      expect(content.text).toMatch(/\n$/);
+    });
+
+    it('should return YAML for operation detail', async () => {
+      const path = encodeURIComponent('api/v1/organizations/{orgId}/projects/{projectId}/tasks');
+      const result = await client.readResource({ uri: `openapi://paths/${path}/get` });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('text/yaml');
+      if (!hasTextContent(content)) throw new Error('Expected text content'); // Add guard
+      expect(() => safeParse(content.text, 'yaml')).not.toThrow();
+      expect(content.text).toContain('operationId: getProjectTasks');
+      expect(content.text).toMatch(/\n$/);
+    });
+
+    it('should return YAML for component detail', async () => {
+      const result = await client.readResource({ uri: 'openapi://components/schemas/Task' });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('text/yaml');
+      if (!hasTextContent(content)) throw new Error('Expected text content'); // Add guard
+      expect(() => safeParse(content.text, 'yaml')).not.toThrow();
+      expect(content.text).toContain('type: object');
+      expect(content.text).toContain('properties:');
+      expect(content.text).toContain('id:');
+      expect(content.text).toMatch(/\n$/);
+    });
+
+    // Note: The test for listResourceTemplates is removed as it tested old template structure.
+    // We could add a new test here if needed, but the mimeType for templates isn't explicitly set anymore.
+
+    it('should handle errors in YAML format (e.g., invalid component name)', async () => {
+      const result = await client.readResource({ uri: 'openapi://components/schemas/InvalidName' });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      // Errors are always text/plain, regardless of configured output format
+      expect(content.mimeType).toBe('text/plain');
+      expect(content.isError).toBe(true);
+      if (!hasTextContent(content)) throw new Error('Expected text');
+      // Updated error message from getValidatedComponentDetails with sorted names
+      expect(content.text).toContain(
+        'None of the requested names (InvalidName) are valid for component type "schemas". Available names: CreateTaskRequest, Task, TaskList'
+      );
+    });
+  });
+
+  describe('Minified JSON format', () => {
+    beforeEach(async () => {
+      testContext = await startMcpServer('test/fixtures/complex-endpoint.json', {
+        outputFormat: 'json-minified',
+      });
+      client = testContext.client;
+    });
+
+    it('should return minified JSON for openapi://info', async () => {
+      const result = await client.readResource({ uri: 'openapi://info' });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('application/json');
+      if (!hasTextContent(content)) throw new Error('Expected text content');
+      expect(() => safeParse(content.text, 'json')).not.toThrow();
+      const data = safeParse(content.text, 'json');
+      expect(isObject(data) && data['title']).toBe('Complex Endpoint Test API');
+      // Check for lack of pretty-printing whitespace
+      expect(content.text).not.toContain('\n ');
+      expect(content.text).not.toContain('  '); // Double check no indentation
+    });
+
+    it('should return minified JSON for operation detail', async () => {
+      const path = encodeURIComponent('api/v1/organizations/{orgId}/projects/{projectId}/tasks');
+      const result = await client.readResource({ uri: `openapi://paths/${path}/get` });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('application/json');
+      if (!hasTextContent(content)) throw new Error('Expected text content');
+      expect(() => safeParse(content.text, 'json')).not.toThrow();
+      const data = safeParse(content.text, 'json');
+      expect(isObject(data) && data['operationId']).toBe('getProjectTasks');
+      // Check for lack of pretty-printing whitespace
+      expect(content.text).not.toContain('\n ');
+      expect(content.text).not.toContain('  ');
+    });
+
+    it('should return minified JSON for component detail', async () => {
+      const result = await client.readResource({ uri: 'openapi://components/schemas/Task' });
+      expect(result.contents).toHaveLength(1);
+      const content = result.contents[0];
+      expect(content.mimeType).toBe('application/json');
+      if (!hasTextContent(content)) throw new Error('Expected text content');
+      expect(() => safeParse(content.text, 'json')).not.toThrow();
+      const data = safeParse(content.text, 'json');
+      expect(isObject(data) && data['type']).toBe('object');
+      expect(
+        isObject(data) &&
+          isObject(data['properties']) &&
+          isObject(data['properties']['id']) &&
+          data['properties']['id']['type']
+      ).toBe('string');
+      // Check for lack of pretty-printing whitespace
+      expect(content.text).not.toContain('\n ');
+      expect(content.text).not.toContain('  ');
+    });
+  });
+});