mcp-openapi-schema-explorer 1.0.0

package/test/__tests__/unit/handlers/operation-handler.test.ts

@@ -0,0 +1,202 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { OperationHandler } from '../../../../src/handlers/operation-handler';
+import { SpecLoaderService } from '../../../../src/types';
+import { IFormatter, JsonFormatter } from '../../../../src/services/formatters';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { suppressExpectedConsoleError } from '../../../utils/console-helpers';
+
+// Mocks
+const mockGetTransformedSpec = jest.fn();
+const mockSpecLoader: SpecLoaderService = {
+  getSpec: jest.fn(),
+  getTransformedSpec: mockGetTransformedSpec,
+};
+
+const mockFormatter: IFormatter = new JsonFormatter();
+
+// Sample Data
+const getOperation: OpenAPIV3.OperationObject = {
+  summary: 'Get Item',
+  responses: { '200': { description: 'OK' } },
+};
+const postOperation: OpenAPIV3.OperationObject = {
+  summary: 'Create Item',
+  responses: { '201': { description: 'Created' } },
+};
+const sampleSpec: OpenAPIV3.Document = {
+  openapi: '3.0.3',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: {
+    '/items': {
+      get: getOperation,
+      post: postOperation,
+    },
+    '/items/{id}': {
+      get: { summary: 'Get Single Item', responses: { '200': { description: 'OK' } } },
+    },
+  },
+  components: {},
+};
+
+const encodedPathItems = encodeURIComponent('items');
+const encodedPathNonExistent = encodeURIComponent('nonexistent');
+
+describe('OperationHandler', () => {
+  let handler: OperationHandler;
+
+  beforeEach(() => {
+    handler = new OperationHandler(mockSpecLoader, mockFormatter);
+    mockGetTransformedSpec.mockReset();
+    mockGetTransformedSpec.mockResolvedValue(sampleSpec); // Default mock
+  });
+
+  it('should return the correct template', () => {
+    const template = handler.getTemplate();
+    expect(template).toBeInstanceOf(ResourceTemplate);
+    expect(template.uriTemplate.toString()).toBe('openapi://paths/{path}/{method*}');
+  });
+
+  describe('handleRequest', () => {
+    const mockExtra = { signal: new AbortController().signal };
+
+    it('should return detail for a single valid method', async () => {
+      const variables: Variables = { path: encodedPathItems, method: 'get' }; // Use 'method' key
+      const uri = new URL(`openapi://paths/${encodedPathItems}/get`);
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(mockGetTransformedSpec).toHaveBeenCalledWith({
+        resourceType: 'schema',
+        format: 'openapi',
+      });
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathItems}/get`,
+        mimeType: 'application/json',
+        text: JSON.stringify(getOperation, null, 2),
+        isError: false,
+      });
+    });
+
+    it('should return details for multiple valid methods (array input)', async () => {
+      const variables: Variables = { path: encodedPathItems, method: ['get', 'post'] }; // Use 'method' key with array
+      const uri = new URL(`openapi://paths/${encodedPathItems}/get,post`); // URI might not reflect array input
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(2);
+      expect(result.contents).toContainEqual({
+        uri: `openapi://paths/${encodedPathItems}/get`,
+        mimeType: 'application/json',
+        text: JSON.stringify(getOperation, null, 2),
+        isError: false,
+      });
+      expect(result.contents).toContainEqual({
+        uri: `openapi://paths/${encodedPathItems}/post`,
+        mimeType: 'application/json',
+        text: JSON.stringify(postOperation, null, 2),
+        isError: false,
+      });
+    });
+
+    it('should return error for non-existent path', async () => {
+      const variables: Variables = { path: encodedPathNonExistent, method: 'get' };
+      const uri = new URL(`openapi://paths/${encodedPathNonExistent}/get`);
+      const expectedLogMessage = /Path "\/nonexistent" not found/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      // Expect the specific error message from getValidatedPathItem
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathNonExistent}/get`,
+        mimeType: 'text/plain',
+        text: 'Path "/nonexistent" not found in the specification.',
+        isError: true,
+      });
+    });
+
+    it('should return error for non-existent method', async () => {
+      const variables: Variables = { path: encodedPathItems, method: 'put' };
+      const uri = new URL(`openapi://paths/${encodedPathItems}/put`);
+      const expectedLogMessage = /None of the requested methods \(put\) are valid/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      // Expect the specific error message from getValidatedOperations
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathItems}/put`,
+        mimeType: 'text/plain',
+        text: 'None of the requested methods (put) are valid for path "/items". Available methods: get, post',
+        isError: true,
+      });
+    });
+
+    // Remove test for mix of valid/invalid methods, as getValidatedOperations throws now
+    // it('should handle mix of valid and invalid methods', async () => { ... });
+
+    it('should handle empty method array', async () => {
+      const variables: Variables = { path: encodedPathItems, method: [] };
+      const uri = new URL(`openapi://paths/${encodedPathItems}/`);
+      const expectedLogMessage = /No valid HTTP method specified/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathItems}/`,
+        mimeType: 'text/plain',
+        text: 'No valid HTTP method specified.',
+        isError: true,
+      });
+    });
+
+    it('should handle spec loading errors', async () => {
+      const error = new Error('Spec load failed');
+      mockGetTransformedSpec.mockRejectedValue(error);
+      const variables: Variables = { path: encodedPathItems, method: 'get' };
+      const uri = new URL(`openapi://paths/${encodedPathItems}/get`);
+      const expectedLogMessage = /Spec load failed/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathItems}/get`,
+        mimeType: 'text/plain',
+        text: 'Spec load failed',
+        isError: true,
+      });
+    });
+
+    it('should handle non-OpenAPI v3 spec', async () => {
+      const invalidSpec = { swagger: '2.0', info: {} };
+      mockGetTransformedSpec.mockResolvedValue(invalidSpec as unknown as OpenAPIV3.Document);
+      const variables: Variables = { path: encodedPathItems, method: 'get' };
+      const uri = new URL(`openapi://paths/${encodedPathItems}/get`);
+      const expectedLogMessage = /Only OpenAPI v3 specifications are supported/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathItems}/get`,
+        mimeType: 'text/plain',
+        text: 'Only OpenAPI v3 specifications are supported',
+        isError: true,
+      });
+    });
+  });
+});

package/test/__tests__/unit/handlers/path-item-handler.test.ts

@@ -0,0 +1,153 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { PathItemHandler } from '../../../../src/handlers/path-item-handler';
+import { SpecLoaderService } from '../../../../src/types';
+import { IFormatter, JsonFormatter } from '../../../../src/services/formatters';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { suppressExpectedConsoleError } from '../../../utils/console-helpers';
+
+// Mocks
+const mockGetTransformedSpec = jest.fn();
+const mockSpecLoader: SpecLoaderService = {
+  getSpec: jest.fn(),
+  getTransformedSpec: mockGetTransformedSpec,
+};
+
+const mockFormatter: IFormatter = new JsonFormatter(); // Needed for context
+
+// Sample Data
+const samplePathItem: OpenAPIV3.PathItemObject = {
+  get: { summary: 'Get Item', responses: { '200': { description: 'OK' } } },
+  post: { summary: 'Create Item', responses: { '201': { description: 'Created' } } },
+};
+const sampleSpec: OpenAPIV3.Document = {
+  openapi: '3.0.3',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: {
+    '/items': samplePathItem,
+    '/empty': {}, // Path with no methods
+  },
+  components: {},
+};
+
+const encodedPathItems = encodeURIComponent('items');
+const encodedPathEmpty = encodeURIComponent('empty');
+const encodedPathNonExistent = encodeURIComponent('nonexistent');
+
+describe('PathItemHandler', () => {
+  let handler: PathItemHandler;
+
+  beforeEach(() => {
+    handler = new PathItemHandler(mockSpecLoader, mockFormatter);
+    mockGetTransformedSpec.mockReset();
+    mockGetTransformedSpec.mockResolvedValue(sampleSpec); // Default mock
+  });
+
+  it('should return the correct template', () => {
+    const template = handler.getTemplate();
+    expect(template).toBeInstanceOf(ResourceTemplate);
+    expect(template.uriTemplate.toString()).toBe('openapi://paths/{path}');
+  });
+
+  describe('handleRequest (List Methods)', () => {
+    const mockExtra = { signal: new AbortController().signal };
+
+    it('should list methods for a valid path', async () => {
+      const variables: Variables = { path: encodedPathItems };
+      const uri = new URL(`openapi://paths/${encodedPathItems}`);
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(mockGetTransformedSpec).toHaveBeenCalledWith({
+        resourceType: 'schema',
+        format: 'openapi',
+      });
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toMatchObject({
+        uri: `openapi://paths/${encodedPathItems}`,
+        mimeType: 'text/plain',
+        isError: false,
+      });
+      // Check for hint first, then methods
+      expect(result.contents[0].text).toContain("Hint: Use 'openapi://paths/items/{method}'");
+      expect(result.contents[0].text).toContain('GET: Get Item');
+      expect(result.contents[0].text).toContain('POST: Create Item');
+      // Ensure the old "Methods for..." header is not present if hint is first
+      expect(result.contents[0].text).not.toContain('Methods for items:');
+    });
+
+    it('should handle path with no methods', async () => {
+      const variables: Variables = { path: encodedPathEmpty };
+      const uri = new URL(`openapi://paths/${encodedPathEmpty}`);
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathEmpty}`,
+        mimeType: 'text/plain',
+        text: 'No standard HTTP methods found for path: empty',
+        isError: false, // Not an error, just no methods
+      });
+    });
+
+    it('should return error for non-existent path', async () => {
+      const variables: Variables = { path: encodedPathNonExistent };
+      const uri = new URL(`openapi://paths/${encodedPathNonExistent}`);
+      const expectedLogMessage = /Path "\/nonexistent" not found/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      // Expect the specific error message from getValidatedPathItem
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathNonExistent}`,
+        mimeType: 'text/plain',
+        text: 'Path "/nonexistent" not found in the specification.',
+        isError: true,
+      });
+    });
+
+    it('should handle spec loading errors', async () => {
+      const error = new Error('Spec load failed');
+      mockGetTransformedSpec.mockRejectedValue(error);
+      const variables: Variables = { path: encodedPathItems };
+      const uri = new URL(`openapi://paths/${encodedPathItems}`);
+      const expectedLogMessage = /Spec load failed/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathItems}`,
+        mimeType: 'text/plain',
+        text: 'Spec load failed',
+        isError: true,
+      });
+    });
+
+    it('should handle non-OpenAPI v3 spec', async () => {
+      const invalidSpec = { swagger: '2.0', info: {} };
+      mockGetTransformedSpec.mockResolvedValue(invalidSpec as unknown as OpenAPIV3.Document);
+      const variables: Variables = { path: encodedPathItems };
+      const uri = new URL(`openapi://paths/${encodedPathItems}`);
+      const expectedLogMessage = /Only OpenAPI v3 specifications are supported/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: `openapi://paths/${encodedPathItems}`,
+        mimeType: 'text/plain',
+        text: 'Only OpenAPI v3 specifications are supported',
+        isError: true,
+      });
+    });
+  });
+});

package/test/__tests__/unit/handlers/top-level-field-handler.test.ts

@@ -0,0 +1,182 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { TopLevelFieldHandler } from '../../../../src/handlers/top-level-field-handler';
+import { SpecLoaderService } from '../../../../src/types';
+import { IFormatter, JsonFormatter } from '../../../../src/services/formatters';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { suppressExpectedConsoleError } from '../../../utils/console-helpers';
+
+// Mocks
+const mockGetTransformedSpec = jest.fn();
+const mockSpecLoader: SpecLoaderService = {
+  getSpec: jest.fn(), // Not used by this handler directly
+  getTransformedSpec: mockGetTransformedSpec,
+};
+
+const mockFormatter: IFormatter = new JsonFormatter(); // Use real formatter for structure check
+
+// Sample Data
+const sampleSpec: OpenAPIV3.Document = {
+  openapi: '3.0.3',
+  info: { title: 'Test API', version: '1.1.0' },
+  paths: { '/test': { get: { responses: { '200': { description: 'OK' } } } } },
+  components: { schemas: { Test: { type: 'string' } } },
+  servers: [{ url: 'http://example.com' }],
+};
+
+describe('TopLevelFieldHandler', () => {
+  let handler: TopLevelFieldHandler;
+
+  beforeEach(() => {
+    handler = new TopLevelFieldHandler(mockSpecLoader, mockFormatter);
+    mockGetTransformedSpec.mockReset(); // Reset mock before each test
+  });
+
+  it('should return the correct template', () => {
+    const template = handler.getTemplate();
+    expect(template).toBeInstanceOf(ResourceTemplate);
+    // Compare against the string representation of the UriTemplate object
+    expect(template.uriTemplate.toString()).toBe('openapi://{field}');
+  });
+
+  describe('handleRequest', () => {
+    // Create a mock extra object with the required signal property
+    const mockExtra = {
+      signal: new AbortController().signal,
+    };
+    // Cast to the expected type for the handler call signature if needed,
+    // but the object structure itself is simpler.
+    // Note: We might need to cast this later if strict type checks complain,
+    // but let's try the minimal structure first.
+
+    it('should handle request for "info" field', async () => {
+      mockGetTransformedSpec.mockResolvedValue(sampleSpec);
+      const variables: Variables = { field: 'info' };
+      const uri = new URL('openapi://info');
+
+      // Pass the mock extra object as the third argument
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(mockGetTransformedSpec).toHaveBeenCalledWith({
+        resourceType: 'schema',
+        format: 'openapi',
+      });
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://info',
+        mimeType: 'application/json',
+        text: JSON.stringify(sampleSpec.info, null, 2),
+        isError: false,
+      });
+    });
+
+    it('should handle request for "servers" field', async () => {
+      mockGetTransformedSpec.mockResolvedValue(sampleSpec);
+      const variables: Variables = { field: 'servers' };
+      const uri = new URL('openapi://servers');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://servers',
+        mimeType: 'application/json',
+        text: JSON.stringify(sampleSpec.servers, null, 2),
+        isError: false,
+      });
+    });
+
+    it('should handle request for "paths" field (list view)', async () => {
+      mockGetTransformedSpec.mockResolvedValue(sampleSpec);
+      const variables: Variables = { field: 'paths' };
+      const uri = new URL('openapi://paths');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0].uri).toBe('openapi://paths');
+      expect(result.contents[0].mimeType).toBe('text/plain');
+      expect(result.contents[0].isError).toBe(false);
+      expect(result.contents[0].text).toContain('GET /test'); // Check content format
+      // Check that the hint contains the essential URI patterns
+      expect(result.contents[0].text).toContain('Hint:');
+      expect(result.contents[0].text).toContain('openapi://paths/{encoded_path}');
+      expect(result.contents[0].text).toContain('openapi://paths/{encoded_path}/{method}');
+    });
+
+    it('should handle request for "components" field (list view)', async () => {
+      mockGetTransformedSpec.mockResolvedValue(sampleSpec);
+      const variables: Variables = { field: 'components' };
+      const uri = new URL('openapi://components');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0].uri).toBe('openapi://components');
+      expect(result.contents[0].mimeType).toBe('text/plain');
+      expect(result.contents[0].isError).toBe(false);
+      expect(result.contents[0].text).toContain('- schemas'); // Check content format
+      expect(result.contents[0].text).toContain("Hint: Use 'openapi://components/{type}'");
+    });
+
+    it('should return error for non-existent field', async () => {
+      mockGetTransformedSpec.mockResolvedValue(sampleSpec);
+      const variables: Variables = { field: 'nonexistent' };
+      const uri = new URL('openapi://nonexistent');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://nonexistent',
+        mimeType: 'text/plain',
+        text: 'Error: Field "nonexistent" not found in the OpenAPI document.',
+        isError: true,
+      });
+    });
+
+    it('should handle spec loading errors', async () => {
+      const error = new Error('Failed to load spec');
+      mockGetTransformedSpec.mockRejectedValue(error);
+      const variables: Variables = { field: 'info' };
+      const uri = new URL('openapi://info');
+      // Match the core error message using RegExp
+      const expectedLogMessage = /Failed to load spec/;
+
+      // Use the helper, letting TypeScript infer the return type
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://info',
+        mimeType: 'text/plain',
+        text: 'Failed to load spec',
+        isError: true,
+      });
+    });
+
+    it('should handle non-OpenAPI v3 spec', async () => {
+      const invalidSpec = { swagger: '2.0', info: {} }; // Not OpenAPI v3
+      mockGetTransformedSpec.mockResolvedValue(invalidSpec as unknown as OpenAPIV3.Document);
+      const variables: Variables = { field: 'info' };
+      const uri = new URL('openapi://info');
+      // Match the core error message using RegExp
+      const expectedLogMessage = /Only OpenAPI v3 specifications are supported/;
+
+      // Use the helper, letting TypeScript infer the return type
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://info',
+        mimeType: 'text/plain',
+        text: 'Only OpenAPI v3 specifications are supported',
+        isError: true,
+      });
+    });
+  });
+});