mcp-openapi-schema-explorer 1.0.0

package/memory-bank/techContext.md

@@ -0,0 +1,131 @@
+# Technical Context
+
+## Development Stack
+
+- TypeScript for implementation
+- MCP SDK for server functionality
+- Jest for testing
+- npm for package distribution
+
+## Key Dependencies
+
+- `@modelcontextprotocol/sdk`: Core MCP functionality
+- `swagger2openapi`: OpenAPI/Swagger spec loading, parsing, and v2->v3 conversion (Runtime dependency)
+- `js-yaml`: YAML parsing (Runtime dependency)
+- `zod`: Schema validation (Runtime dependency)
+- `openapi-types`: OpenAPI type definitions (devDependency)
+- `typescript`: TypeScript compiler (devDependency)
+- `@types/*`: Various type definitions (devDependencies)
+- `jest`: Testing framework (devDependency)
+- `eslint`: Code linting (devDependency)
+- `prettier`: Code formatting (devDependency)
+- `semantic-release` & plugins (`@semantic-release/*`): Automated releases (devDependencies)
+- `just`: Task runner (Used locally, installed via action in CI)
+
+## Technical Requirements
+
+1. Must follow MCP protocol specifications.
+2. Must handle large OpenAPI/Swagger specs efficiently.
+3. Must provide type-safe reference handling (transforming internal refs to MCP URIs).
+4. Must support loading specs from local file paths and remote HTTP/HTTPS URLs.
+5. Must support OpenAPI v3.0 and Swagger v2.0 formats (with v2.0 being converted to v3.0).
+6. Must be easily testable and maintainable.
+
+## Development Environment
+
+- TypeScript setup with strict type checking
+- Jest testing framework with coverage
+- ESLint for code quality
+- Prettier for code formatting
+- `just` task runner (`justfile`) for common development tasks (build, test, lint, etc.)
+- Conventional Commits standard for commit messages (required for `semantic-release`)
+- Test fixtures and helpers
+
+## Code Organization
+
+- Services layer:
+  - `SpecLoaderService`: Uses `swagger2openapi` to load specs from files/URLs and handle v2->v3 conversion.
+  - `ReferenceTransformService`: Transforms internal `#/components/...` refs to MCP URIs.
+  - `Formatters`: Handle JSON/YAML output.
+- Handlers layer for resource endpoints.
+- Rendering layer for generating resource content.
+- Utilities (e.g., URI builder).
+- Strong typing with generics.
+- Comprehensive test coverage.
+
+## Testing Infrastructure
+
+- Unit tests:
+  - `SpecLoaderService` (mocking `swagger2openapi`).
+  - `ReferenceTransformService`.
+  - Rendering classes.
+  - Handlers (mocking services).
+- End-to-end tests:
+  - Verify resource access for local v3, local v2, and remote v3 specs.
+  - Test multi-value parameters.
+  - Cover success and error scenarios.
+  - Verify resource completion logic using `client.complete()`.
+- Type-safe test utilities (`mcp-test-helpers`).
+- Test fixtures (including v2.0 and v3.0 examples).
+- Coverage reporting via Jest and upload to Codecov via GitHub Actions.
+- CI Integration (`.github/workflows/ci.yml`):
+  - Runs checks (`just all`, `just security`, CodeQL) on pushes/PRs to `main`.
+  - Uses Node 22 environment.
+
+## Response Formats
+
+1. Base Formats
+
+   - JSON format (default format)
+   - YAML format support
+   - URI-based reference links
+   - Token-efficient structure
+   - OpenAPI v3 type compliance
+
+2. Format Service
+
+   - Pluggable formatter architecture
+   - Format-specific MIME types (`application/json`, `text/yaml`)
+   - Type-safe formatter interface (`IFormatter`)
+   - Consistent error formatting (`text/plain`)
+   - CLI-configurable output format (`--output-format`)
+
+3. Implementation
+   - Format-specific serialization
+   - Shared type system
+   - Error response handling
+   - Multiple operation support
+   - Reference transformation
+
+## Deployment / Release Process
+
+- Automated publishing to npm via `semantic-release` triggered by pushes to `main` branch in GitHub Actions.
+- Relies on Conventional Commits to determine version bumps.
+- Creates version tags (e.g., `v1.2.3`) and GitHub Releases automatically.
+- Requires `NPM_TOKEN` secret configured in GitHub repository for publishing.
+- `CHANGELOG.md` is automatically generated and updated.
+- Server version is dynamically set at runtime based on the release version.
+
+## Configuration
+
+- Command-line argument based configuration (`src/config.ts`).
+- Single required argument: `<path-or-url-to-spec>`.
+- Optional argument: `--output-format <json|yaml|json-minified>`.
+- Required argument validation.
+- TypeScript type safety (`ServerConfig` interface).
+- Error handling for missing/invalid arguments.
+
+## Error Handling
+
+- Descriptive error messages
+- Type-safe error handling
+- Consistent error format
+- Proper error propagation
+
+## Future Extensions
+
+- AsyncAPI format support
+- GraphQL schema support
+- External reference resolution
+- Enhanced schema resources
+- Reference validation

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "mcp-openapi-schema-explorer",
+  "version": "1.0.0",
+  "description": "MCP OpenAPI schema explorer",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "mcp-openapi-schema-explorer": "dist/src/index.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && mkdir -p dist && npx tsc && chmod +x dist/src/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "type-check": "tsc --noEmit",
+    "prepare": "husky",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kadykov/mcp-openapi-schema-explorer.git"
+  },
+  "keywords": [
+    "mcp",
+    "openapi"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/kadykov/mcp-openapi-schema-explorer/issues"
+  },
+  "homepage": "https://github.com/kadykov/mcp-openapi-schema-explorer#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "js-yaml": "^4.1.0",
+    "swagger2openapi": "7.0.8",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.14.1",
+    "@types/node-fetch": "^2.6.12",
+    "@types/swagger2openapi": "^7.0.4",
+    "@typescript-eslint/eslint-plugin": "^8.29.0",
+    "@typescript-eslint/parser": "^8.29.0",
+    "axios": "^1.8.4",
+    "eslint": "^9.24.0",
+    "eslint-plugin-security": "^3.0.1",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jest-silent-reporter": "^0.6.0",
+    "license-checker": "^25.0.1",
+    "msw": "^2.7.4",
+    "openapi-types": "^12.1.3",
+    "openapi-typescript": "^7.6.1",
+    "prettier": "^3.5.3",
+    "semantic-release": "^24.2.3",
+    "ts-jest": "^29.3.1",
+    "typescript": "^5.8.3"
+  }
+}

package/scripts/generate-version.js

@@ -0,0 +1,49 @@
+// scripts/generate-version.js
+// Purpose: Writes the release version provided by semantic-release to src/version.ts
+// Called by: @semantic-release/exec during the 'prepare' step
+
+import fs from 'fs'; // Use import
+import path from 'path'; // Use import
+import { fileURLToPath } from 'url'; // Needed to convert import.meta.url
+
+// Get version from the command line argument passed by semantic-release exec
+// process is globally available in ESM
+const version = process.argv[2];
+
+if (!version) {
+  console.error('Error: No version argument provided to generate-version.js!');
+  process.exit(1);
+}
+
+// Basic check for semantic version format (adjust regex if needed)
+if (!/^\d+\.\d+\.\d+(-[\w.-]+)?(\+[\w.-]+)?$/.test(version)) {
+  console.error(`Error: Invalid version format received: "${version}"`);
+  process.exit(1);
+}
+
+const content = `// Auto-generated by scripts/generate-version.js during semantic-release prepare step
+// Do not edit this file manually.
+
+export const VERSION = '${version}';
+`;
+
+// Derive the directory path in ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Construct the absolute path to src/version.ts
+const filePath = path.join(__dirname, '..', 'src', 'version.ts');
+const fileDir = path.dirname(filePath);
+
+try {
+  // Ensure the src directory exists (though it should)
+  if (!fs.existsSync(fileDir)) {
+    fs.mkdirSync(fileDir, { recursive: true });
+  }
+  // Write the version file
+  fs.writeFileSync(filePath, content, { encoding: 'utf-8' });
+  console.log(`Successfully wrote version ${version} to ${filePath}`);
+} catch (error) {
+  console.error(`Error writing version file to ${filePath}:`, error);
+  process.exit(1);
+}

package/src/config.ts

@@ -0,0 +1,33 @@
+/**
+ * Configuration management for the OpenAPI Explorer MCP server
+ */
+
+import { OutputFormat } from './services/formatters.js';
+
+/** Server configuration */
+export interface ServerConfig {
+  /** Path to OpenAPI specification file */
+  specPath: string;
+  /** Output format for responses */
+  outputFormat: OutputFormat;
+}
+
+/** Load server configuration from command line arguments */
+export function loadConfig(specPath?: string, options?: { outputFormat?: string }): ServerConfig {
+  if (!specPath) {
+    throw new Error(
+      'OpenAPI spec path is required. Usage: npx mcp-openapi-schema-explorer <path-to-spec> [--output-format json|yaml]'
+    );
+  }
+
+  const format = options?.outputFormat || 'json';
+  if (format !== 'json' && format !== 'yaml' && format !== 'json-minified') {
+    throw new Error('Invalid output format. Supported formats: json, yaml, json-minified');
+  }
+
+  return {
+    specPath,
+    // Cast is safe here due to the validation above
+    outputFormat: format as OutputFormat,
+  };
+}

package/src/handlers/component-detail-handler.ts

@@ -0,0 +1,121 @@
+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 {
+  RenderableComponentMap,
+  ComponentType,
+  VALID_COMPONENT_TYPES,
+} 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,
+  getValidatedComponentMap, // Import helper
+  getValidatedComponentDetails, // Import 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 component details.
+ * Corresponds to the `openapi://components/{type}/{name*}` template.
+ */
+export class ComponentDetailHandler {
+  constructor(
+    private specLoader: SpecLoaderService,
+    private formatter: IFormatter
+  ) {}
+
+  getTemplate(): ResourceTemplate {
+    // TODO: Add completion logic if needed
+    return new ResourceTemplate(`${BASE_URI}components/{type}/{name*}`, {
+      list: undefined,
+      complete: undefined,
+    });
+  }
+
+  handleRequest: ReadResourceTemplateCallback = async (
+    uri: URL,
+    variables: Variables
+  ): Promise<{ contents: FormattedResultItem[] }> => {
+    const type = variables.type as string;
+    // Correct variable access key: 'name', not 'name*'
+    const nameVar = variables['name']; // Can be string or string[]
+    const mapUriSuffix = `components/${type}`;
+    const context: RenderContext = { formatter: this.formatter, baseUri: BASE_URI };
+    let resultItems: RenderResultItem[];
+
+    try {
+      if (!VALID_COMPONENT_TYPES.includes(type as ComponentType)) {
+        throw new Error(`Invalid component type: ${type}`);
+      }
+      const componentType = type as ComponentType;
+
+      // Normalize names: Handle string for single value, array for multiple.
+      let names: string[] = [];
+      if (Array.isArray(nameVar)) {
+        names = nameVar.map(n => String(n).trim()); // Ensure elements are strings
+      } else if (typeof nameVar === 'string') {
+        names = [nameVar.trim()]; // Treat as single item array
+      }
+      names = names.filter(n => n.length > 0); // Remove empty strings
+
+      if (names.length === 0) {
+        throw new Error('No valid component name 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 component map ---
+      const componentMapObj = getValidatedComponentMap(spec, componentType);
+
+      // --- Create Map and use helper to get validated component names/details ---
+      // Create the Map from the validated object
+      const detailsMap = new Map(Object.entries(componentMapObj));
+      // Pass the Map to the helper
+      const validDetails = getValidatedComponentDetails(detailsMap, names, componentType);
+      const validNames = validDetails.map(detail => detail.name); // Extract names
+
+      // Instantiate RenderableComponentMap with the validated map object
+      const renderableMap = new RenderableComponentMap(
+        componentMapObj, // componentMapObj retrieved safely via helper
+        componentType,
+        mapUriSuffix
+      );
+      // Pass the validated names to the rendering function
+      resultItems = renderableMap.renderComponentDetail(context, validNames);
+    } catch (error: unknown) {
+      // Catch errors from helpers (e.g., type/name 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/component-map-handler.ts

@@ -0,0 +1,92 @@
+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 {
+  RenderableComponentMap,
+  ComponentType,
+  VALID_COMPONENT_TYPES,
+} 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,
+  getValidatedComponentMap, // 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 component names of a specific type.
+ * Corresponds to the `openapi://components/{type}` template.
+ */
+export class ComponentMapHandler {
+  constructor(
+    private specLoader: SpecLoaderService,
+    private formatter: IFormatter // Needed for context
+  ) {}
+
+  getTemplate(): ResourceTemplate {
+    // TODO: Add completion logic if needed
+    return new ResourceTemplate(`${BASE_URI}components/{type}`, {
+      list: undefined,
+      complete: undefined,
+    });
+  }
+
+  handleRequest: ReadResourceTemplateCallback = async (
+    uri: URL,
+    variables: Variables
+  ): Promise<{ contents: FormattedResultItem[] }> => {
+    const type = variables.type as string;
+    const mapUriSuffix = `components/${type}`;
+    const context: RenderContext = { formatter: this.formatter, baseUri: BASE_URI };
+    let resultItems: RenderResultItem[];
+
+    try {
+      if (!VALID_COMPONENT_TYPES.includes(type as ComponentType)) {
+        throw new Error(`Invalid component type: ${type}`);
+      }
+      const componentType = type as ComponentType;
+
+      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 component map ---
+      const componentMapObj = getValidatedComponentMap(spec, componentType);
+
+      // Instantiate RenderableComponentMap with the validated map
+      const renderableMap = new RenderableComponentMap(
+        componentMapObj, // componentMapObj retrieved safely via helper
+        componentType,
+        mapUriSuffix
+      );
+      resultItems = renderableMap.renderList(context);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error handling request ${uri.href}: ${message}`);
+      resultItems = createErrorResult(mapUriSuffix, message);
+    }
+
+    // Use imported formatResults
+    const contents = formatResults(context, resultItems);
+    return { contents };
+  };
+}