mcp-openapi-schema-explorer 1.0.0

package/.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+  "name": "MCP OpenAPI Schema Explorer",
+  "dockerFile": "../Dockerfile",
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "username": "vscode"
+    },
+    "ghcr.io/guiyomh/features/just:0": {}
+  },
+  "remoteUser": "vscode",
+  "postCreateCommand": "just install",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-azuretools.vscode-docker",
+        "GitHub.vscode-github-actions",
+        "saoudrizwan.claude-dev",
+        "dbaeumer.vscode-eslint",
+        "rvest.vs-code-prettier-eslint",
+        "ms-vscode.vscode-typescript-next"
+      ]
+    }
+  }
+}

package/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 10

package/.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI
+
+permissions: # Add default permissions, release job will override if needed
+  contents: read
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22 # Match Dockerfile
+          cache: 'npm'
+
+      - name: Setup Just
+        uses: extractions/setup-just@v3
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run all checks (format, lint, build, test)
+        run: just all # Uses justfile for consistency
+
+      - name: Upload coverage reports artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report-${{ github.run_id }} # Unique name per run
+          path: coverage/
+        if: always() # Upload even if previous steps fail
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+        # fail_ci_if_error: true # Optional: fail CI if upload fails
+
+  security:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # Needed for checkout and CodeQL
+      security-events: write # Needed for CodeQL alert uploads
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22 # Match Dockerfile and test job
+          cache: 'npm'
+
+      - name: Setup Just
+        uses: extractions/setup-just@v3
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Security Checks (Audit, Licenses)
+        run: just security # Uses justfile, includes npm audit and license-checker
+        continue-on-error: true # Allow workflow to continue even if npm audit finds vulnerabilities
+
+      # Static code analysis with CodeQL (Keep separate as it's not in justfile)
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        # Auto-detect languages: javascript, typescript
+        # queries: +security-extended # Optional: run more queries
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [test, security] # Run after test and security checks pass
+    # Run only on pushes to main, not on tags (semantic-release creates tags)
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    permissions:
+      contents: write # Allow tagging, committing package.json/changelog/version.ts
+      issues: write # Allow commenting on issues/PRs
+      pull-requests: write # Allow commenting on issues/PRs
+      id-token: write # Needed for provenance publishing to npm (alternative to NPM_TOKEN)
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22 # Match Dockerfile and other jobs
+          cache: 'npm'
+
+      - name: Install all dependencies
+        run: npm ci --include=dev
+
+      - name: Semantic Release
+        uses: cycjimmy/semantic-release-action@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Format all staged files
+prettier $(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g') --write --ignore-unknown
+git update-index --again

package/.prettierignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+local-docs/

package/.prettierrc.json

@@ -0,0 +1,12 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}

package/.releaserc.json

@@ -0,0 +1,23 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "node ./scripts/generate-version.js ${nextRelease.version}"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json", "package-lock.json", "CHANGELOG.md", "src/version.ts"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# 1.0.0 (2025-04-12)
+
+### Bug Fixes
+
+- add codecov badge to README for improved visibility of test coverage ([ed7bf93](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/ed7bf93de6c6efbf3a890551b67321b0d003c3cf))
+
+### Features
+
+- add CI workflow and dependabot configuration for automated updates ([2d0b22e](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/2d0b22ea20afd58297b2169d3761db32b4c92606))
+- Add configuration management for OpenAPI Explorer ([b9f4771](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/b9f47712e754983d292bd6d53c82fa7e344b45a6))
+- add CONTRIBUTING.md and enhance README with detailed project information ([1f4b2d5](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/1f4b2d59d7a19e54556cf8933fc4e4952d8f438c))
+- Add end-to-end tests for OpenAPI resource handling ([d1ba7ab](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/d1ba7ab5db84717ed6c326d0c7d625906572be2c))
+- Add pre-commit hook to format staged files with Prettier ([af58250](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/af582509fadbffd52afcd36d6113a1965a2bfcef))
+- Add SchemaListHandler and implement schema listing resource with error handling ([873bbee](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/873bbee9cee5233e97202458a6b261e6ac58b651))
+- Add support for minified JSON output format and related enhancements ([f0cb5b8](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/f0cb5b80eeb73d2656b1d8fb37ab8fe21dacf12a))
+- Enhance endpoint features and add endpoint list handler with improved error handling ([32082ac](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/32082acd3f187bb0611a2adbbfb107f0c153aae2))
+- Enhance OpenAPI resource handling with new templates and completion tests ([45e4938](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/45e4938b226dc6e1baeb506b8c23c615fef78065))
+- Enhance output formatting with JSON and YAML support, including formatter implementations and configuration updates ([e63fafe](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/e63fafe82abb36a56bbb976ff3098f2d4d6a7d6c))
+- Implement dynamic server name based on OpenAPI spec title ([aaa691f](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/aaa691fa2c545a433e09fb3f1faa0d31d4e8624d))
+- Implement EndpointListHandler and add endpoint list resource to server ([b81a606](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/b81a60645eeec9b2e9bd7eb46914cdf3178f9457))
+- Implement Map-based validation helpers to enhance security and error handling ([a4394c9](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/a4394c9846482d53436019a0498ca5d91fddefdf))
+- Implement resource completion logic and add related tests ([de8f297](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/de8f29785882a6bd68d4fcaf38de971de4bad222))
+- Implement SchemaHandler and add schema resource support with error handling ([2fae461](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/2fae461e5de51b7610135922b4a4c9a55cd5b126))
+- initialize MCP OpenAPI schema explorer project ([fd64242](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/fd642421274172e5ca330c9b85015f597f4a96c1))
+- Introduce suppressExpectedConsoleError utility to manage console.error during tests ([ef088c2](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/ef088c2f98bacd0dd7ae3f4aa75e44ba52a41712))
+- Update dependencies to include swagger2openapi and @types/js-yaml ([8acb951](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/8acb951eb88843c72f8eb7d6d7feff681b56ff84))
+- update descriptions in API methods to include URL-encoding notes ([b71dbdf](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/b71dbdfd8c5f0c02d9a47f99143416787f76bf50))
+- Update endpoint URI template to support wildcard parameters ([ce1281f](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/ce1281f16f81a0fd7a74b20fe6bb92e7ed19e158))
+- Update EndpointHandler to return detailed operation responses for GET and POST methods ([af55400](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/af554008c35c9be5bdbf53e51b791e90d135e283))
+- Update license compliance check to include Python-2.0 ([e00c5e2](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/e00c5e23cca6070d6833017b567d7c5402276f45))
+- Update MCP inspector command to support YAML output format ([f7fb551](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/f7fb551cc3a9d7e84fb47100cf8e0430c2634070))
+- update release job to match Node.js version and include dev dependencies ([f3aeb87](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/f3aeb87dcd8bed9920fe2eccdcd8f253b310f761))

package/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to MCP OpenAPI Schema Explorer
+
+Thank you for considering contributing to this project! We welcome improvements and bug fixes.
+
+## Getting Started
+
+- **Devcontainer:** The easiest way to get a consistent development environment is to use the provided [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) configuration (`.devcontainer/`). If you have Docker and the VS Code Dev Containers extension installed, simply reopen the project folder in a container.
+- **Manual Setup:** If you prefer not to use the devcontainer, ensure you have Node.js (v22 or later recommended) and npm installed. Clone the repository and run `npm install` to install dependencies.
+
+## Development Workflow
+
+This project uses [`just`](https://github.com/casey/just) as a command runner for common development tasks. See the `justfile` for all available commands. Key commands include:
+
+- `just install`: Install dependencies (`npm install`).
+- `just format`: Format code using Prettier.
+- `just lint`: Check code for linting errors using ESLint.
+- `just build`: Compile TypeScript code (`npx tsc`).
+- `just test`: Run unit and end-to-end tests using Jest.
+- `just test-coverage`: Run tests and generate a coverage report.
+- `just security`: Run security checks (npm audit, license check).
+- `just all`: Run format, lint, build, test-coverage, and security checks sequentially.
+
+Please ensure `just all` passes before submitting a pull request.
+
+## Code Style
+
+- **Formatting:** We use [Prettier](https://prettier.io/) for automatic code formatting. Please run `just format` before committing.
+- **Linting:** We use [ESLint](https://eslint.org/) for code analysis. Please run `just lint` to check for issues.
+
+## Commit Messages
+
+This project uses [`semantic-release`](https://github.com/semantic-release/semantic-release) to automate versioning and releases. Therefore, commit messages **must** follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. This allows the release process to automatically determine the version bump (patch, minor, major) and generate changelogs.
+
+Common commit types include:
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `perf`: A code change that improves performance
+- `test`: Adding missing tests or correcting existing tests
+- `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+- `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+- `chore`: Other changes that don't modify src or test files
+
+Example: `feat: add support for YAML output format`
+Example: `fix: correct handling of remote URL loading errors`
+Example: `docs: update README with client configuration examples`
+
+## Cline & Memory Bank
+
+This project utilizes [Cline](https://github.com/cline/cline) for AI-assisted development. The `memory-bank/` directory contains documentation specifically for Cline's context. Maintaining this memory bank helps ensure Cline can effectively assist with development tasks.
+
+If you make significant changes to the project's architecture, features, or development process, please consider updating the relevant files in `memory-bank/`. You can learn more about the Cline Memory Bank [here](https://docs.cline.bot/improving-your-prompting-skills/cline-memory-bank).
+
+## Submitting Changes
+
+1.  Fork the repository.
+2.  Create a new branch for your feature or fix (`git checkout -b feat/my-new-feature` or `git checkout -b fix/my-bug-fix`).
+3.  Make your changes.
+4.  Ensure all checks pass (`just all`).
+5.  Commit your changes using the Conventional Commits format.
+6.  Push your branch to your fork (`git push origin feat/my-new-feature`).
+7.  Open a pull request against the `main` branch of the original repository.
+
+Thank you for your contribution!

package/Dockerfile

@@ -0,0 +1,3 @@
+FROM node:22-alpine3.21
+
+WORKDIR /workspaces/mcp-openapi-schema-explorer

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aleksandr Kadykov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# MCP OpenAPI Schema Explorer
+
+[![npm version](https://badge.fury.io/js/mcp-openapi-schema-explorer.svg)](https://badge.fury.io/js/mcp-openapi-schema-explorer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/kadykov/mcp-openapi-schema-explorer/graph/badge.svg?token=LFDOMJ6W4W)](https://codecov.io/gh/kadykov/mcp-openapi-schema-explorer)
+
+An MCP (Model Context Protocol) server that provides token-efficient access to OpenAPI (v3.0) and Swagger (v2.0) specifications via **MCP Resources**.
+
+## Project Goal
+
+The primary goal of this project is to allow MCP clients (like Cline or Claude Desktop) to explore the structure and details of large OpenAPI specifications without needing to load the entire file into an LLM's context window. It achieves this by exposing parts of the specification through MCP Resources, which are well-suited for read-only data exploration.
+
+This server supports loading specifications from both local file paths and remote HTTP/HTTPS URLs. Swagger v2.0 specifications are automatically converted to OpenAPI v3.0 upon loading.
+
+## Why MCP Resources?
+
+The Model Context Protocol defines both **Resources** and **Tools**.
+
+- **Resources:** Represent data sources (like files, API responses). They are ideal for read-only access and exploration by MCP clients (e.g., browsing API paths in Claude Desktop).
+- **Tools:** Represent executable actions or functions, often used by LLMs to perform tasks or interact with external systems.
+
+While other MCP servers exist that provide access to OpenAPI specs via _Tools_, this project specifically focuses on providing access via _Resources_. This makes it particularly useful for direct exploration within MCP client applications.
+
+For more details on MCP clients and their capabilities, see the [MCP Client Documentation](https://modelcontextprotocol.io/clients).
+
+## Usage with MCP Clients (Recommended)
+
+This server is designed to be run by MCP clients. The recommended way to configure it is using `npx`, which downloads and runs the package without requiring a global installation.
+
+**Example Configuration (Claude Desktop - `claude_desktop_config.json`):**
+
+```json
+{
+  "mcpServers": {
+    "My API Spec": {
+      // Choose a descriptive name for this server instance
+      "command": "npx",
+      "args": [
+        "-y", // Auto-confirm npx installation if needed the first time
+        "mcp-openapi-schema-explorer",
+        "/path/to/your/local/openapi.json" // Or "https://remote/url/spec.json"
+        // Optional: Specify output format for detail views (defaults to 'json')
+        // "--output-format", "yaml" // Other options: "json", "json-minified"
+      ],
+      "env": {} // No environment variables needed currently
+    }
+  }
+}
+```
+
+**Notes:**
+
+- Replace `/path/to/your/local/openapi.json` with the actual **absolute path** to your local spec file or the full URL to a remote spec.
+- The server name (`"My API Spec"` in the example) is how you'll identify this specific server instance within your MCP client.
+- This server handles one specification per instance. To explore multiple specifications simultaneously, configure multiple entries under `mcpServers` in your client's configuration file, each pointing to a different spec file or URL.
+
+## Alternative: Global Installation
+
+If you prefer, you can install the server globally:
+
+```bash
+npm install -g mcp-openapi-schema-explorer
+```
+
+If installed globally, your MCP client configuration would change:
+
+- `command`: Likely `mcp-openapi-schema-explorer` (or the full path if needed).
+- `args`: Would only contain the `<path-or-url-to-spec>` and optional `--output-format` flag (omit `npx` and `-y`).
+
+## Features
+
+- **MCP Resource Access:** Explore OpenAPI specs via intuitive URIs (`openapi://info`, `openapi://paths/...`, `openapi://components/...`).
+- **OpenAPI v3.0 & Swagger v2.0 Support:** Loads both formats, automatically converting v2.0 to v3.0.
+- **Local & Remote Files:** Load specs from local file paths or HTTP/HTTPS URLs.
+- **Token-Efficient:** Designed to minimize token usage for LLMs by providing structured access.
+- **Multiple Output Formats:** Get detailed views in JSON (default), YAML, or minified JSON (`--output-format`).
+- **Dynamic Server Name:** Server name in MCP clients reflects the `info.title` from the loaded spec.
+- **Reference Transformation:** Internal `$ref`s (`#/components/...`) are transformed into clickable MCP URIs.
+
+## Available MCP Resources
+
+This server exposes the following MCP resource templates for exploring the OpenAPI specification:
+
+- **`openapi://{field}`**
+
+  - **Description:** Accesses top-level fields of the OpenAPI document (`info`, `servers`, `tags`, etc.) or lists the contents of `paths` or `components`.
+  - **Parameter:** `{field}` - The name of the top-level field (e.g., `info`, `paths`, `components`).
+  - **Output:** `text/plain` list for `paths` and `components`; configured format (JSON/YAML/minified JSON) for other fields.
+
+- **`openapi://paths/{path}`**
+
+  - **Description:** Lists the available HTTP methods (operations) for a specific API path.
+  - **Parameter:** `{path}` - The API path string. **Must be URL-encoded** (e.g., `/users/{id}` becomes `users%2F%7Bid%7D`).
+  - **Output:** `text/plain` list of methods.
+
+- **`openapi://paths/{path}/{method*}`**
+
+  - **Description:** Gets the detailed specification for one or more operations (HTTP methods) on a specific API path.
+  - **Parameters:**
+    - `{path}` - The API path string. **Must be URL-encoded**.
+    - `{method*}` - One or more HTTP methods (e.g., `GET`, `POST`). Can be a single method or multiple separated by a comma (e.g., `GET,POST`).
+  - **Output:** Configured format (JSON/YAML/minified JSON).
+
+- **`openapi://components/{type}`**
+
+  - **Description:** Lists the names of all defined components of a specific type.
+  - **Parameter:** `{type}` - The component type (e.g., `schemas`, `responses`, `parameters`, `examples`, `requestBodies`, `headers`, `securitySchemes`, `links`, `callbacks`).
+  - **Output:** `text/plain` list of component names.
+
+- **`openapi://components/{type}/{name*}`**
+  - **Description:** Gets the detailed specification for one or more named components of a specific type.
+  - **Parameters:**
+    - `{type}` - The component type.
+    - `{name*}` - One or more component names. Can be a single name or multiple separated by a comma (e.g., `SchemaA,SchemaB`).
+  - **Output:** Configured format (JSON/YAML/minified JSON).
+
+## Contributing
+
+Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines on setting up the development environment, running tests, and submitting changes.
+
+## Releases
+
+This project uses [`semantic-release`](https://github.com/semantic-release/semantic-release) for automated version management and package publishing based on [Conventional Commits](https://www.conventionalcommits.org/).
+
+## Future Plans
+
+- Docker container support for easier deployment.

package/dist/src/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function loadConfig(specPath?: string, options?: {
+    outputFormat?: string;
+}): ServerConfig;

package/dist/src/config.js

@@ -0,0 +1,19 @@
+/**
+ * Configuration management for the OpenAPI Explorer MCP server
+ */
+/** Load server configuration from command line arguments */
+export function loadConfig(specPath, options) {
+    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,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,4DAA4D;AAC5D,MAAM,UAAU,UAAU,CAAC,QAAiB,EAAE,OAAmC;IAC/E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,kHAAkH,CACnH,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,EAAE,YAAY,IAAI,MAAM,CAAC;IAC/C,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,eAAe,EAAE,CAAC;QACzE,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IAED,OAAO;QACL,QAAQ;QACR,gDAAgD;QAChD,YAAY,EAAE,MAAsB;KACrC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,14 @@
+import { ReadResourceTemplateCallback, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SpecLoaderService } from '../types.js';
+import { IFormatter } from '../services/formatters.js';
+/**
+ * Handles requests for specific component details.
+ * Corresponds to the `openapi://components/{type}/{name*}` template.
+ */
+export declare class ComponentDetailHandler {
+    private specLoader;
+    private formatter;
+    constructor(specLoader: SpecLoaderService, formatter: IFormatter);
+    getTemplate(): ResourceTemplate;
+    handleRequest: ReadResourceTemplateCallback;
+}

package/dist/src/handlers/component-detail-handler.js

@@ -0,0 +1,87 @@
+import { ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RenderableComponentMap, VALID_COMPONENT_TYPES, } from '../rendering/components.js';
+import { createErrorResult } from '../rendering/utils.js';
+// Import shared handler utils
+import { formatResults, isOpenAPIV3, 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(specLoader, formatter) {
+        this.specLoader = specLoader;
+        this.formatter = formatter;
+        this.handleRequest = async (uri, variables) => {
+            const type = variables.type;
+            // Correct variable access key: 'name', not 'name*'
+            const nameVar = variables['name']; // Can be string or string[]
+            const mapUriSuffix = `components/${type}`;
+            const context = { formatter: this.formatter, baseUri: BASE_URI };
+            let resultItems;
+            try {
+                if (!VALID_COMPONENT_TYPES.includes(type)) {
+                    throw new Error(`Invalid component type: ${type}`);
+                }
+                const componentType = type;
+                // Normalize names: Handle string for single value, array for multiple.
+                let names = [];
+                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) {
+                // 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 };
+        };
+    }
+    getTemplate() {
+        // TODO: Add completion logic if needed
+        return new ResourceTemplate(`${BASE_URI}components/{type}/{name*}`, {
+            list: undefined,
+            complete: undefined,
+        });
+    }
+}
+//# sourceMappingURL=component-detail-handler.js.map

package/dist/src/handlers/component-detail-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-detail-handler.js","sourceRoot":"","sources":["../../../src/handlers/component-detail-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,GACjB,MAAM,yCAAyC,CAAC;AAIjD,OAAO,EACL,sBAAsB,EAEtB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,8BAA8B;AAC9B,OAAO,EACL,aAAa,EACb,WAAW,EAEX,wBAAwB,EAAE,gBAAgB;AAC1C,4BAA4B,EAAE,gBAAgB;EAC/C,MAAM,oBAAoB,CAAC,CAAC,kBAAkB;AAE/C,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B,gFAAgF;AAChF,8EAA8E;AAC9E,4EAA4E;AAE5E;;;GAGG;AACH,MAAM,OAAO,sBAAsB;IACjC,YACU,UAA6B,EAC7B,SAAqB;QADrB,eAAU,GAAV,UAAU,CAAmB;QAC7B,cAAS,GAAT,SAAS,CAAY;QAW/B,kBAAa,GAAiC,KAAK,EACjD,GAAQ,EACR,SAAoB,EAC0B,EAAE;YAChD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAc,CAAC;YACtC,mDAAmD;YACnD,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,4BAA4B;YAC/D,MAAM,YAAY,GAAG,cAAc,IAAI,EAAE,CAAC;YAC1C,MAAM,OAAO,GAAkB,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;YAChF,IAAI,WAA+B,CAAC;YAEpC,IAAI,CAAC;gBACH,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,IAAqB,CAAC,EAAE,CAAC;oBAC3D,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;gBACrD,CAAC;gBACD,MAAM,aAAa,GAAG,IAAqB,CAAC;gBAE5C,uEAAuE;gBACvE,IAAI,KAAK,GAAa,EAAE,CAAC;gBACzB,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC3B,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,8BAA8B;gBAC5E,CAAC;qBAAM,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;oBACvC,KAAK,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,6BAA6B;gBACzD,CAAC;gBACD,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,uBAAuB;gBAEhE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;gBACxD,CAAC;gBAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC;oBACpD,YAAY,EAAE,QAAQ,EAAE,uBAAuB;oBAC/C,MAAM,EAAE,SAAS;iBAClB,CAAC,CAAC;gBAEH,0BAA0B;gBAC1B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;oBACvB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;gBAClE,CAAC;gBAED,oDAAoD;gBACpD,MAAM,eAAe,GAAG,wBAAwB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;gBAEtE,6EAA6E;gBAC7E,2CAA2C;gBAC3C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;gBAC5D,6BAA6B;gBAC7B,MAAM,YAAY,GAAG,4BAA4B,CAAC,UAAU,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;gBACpF,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB;gBAE5E,mEAAmE;gBACnE,MAAM,aAAa,GAAG,IAAI,sBAAsB,CAC9C,eAAe,EAAE,8CAA8C;gBAC/D,aAAa,EACb,YAAY,CACb,CAAC;gBACF,qDAAqD;gBACrD,WAAW,GAAG,aAAa,CAAC,qBAAqB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACzE,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,qEAAqE;gBACrE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,OAAO,CAAC,KAAK,CAAC,0BAA0B,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;gBAChE,sEAAsE;gBACtE,WAAW,GAAG,iBAAiB,CAC7B,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB;gBAC9D,OAAO,CACR,CAAC;YACJ,CAAC;YAED,6BAA6B;YAC7B,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACrD,OAAO,EAAE,QAAQ,EAAE,CAAC;QACtB,CAAC,CAAC;IAlFC,CAAC;IAEJ,WAAW;QACT,uCAAuC;QACvC,OAAO,IAAI,gBAAgB,CAAC,GAAG,QAAQ,2BAA2B,EAAE;YAClE,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,SAAS;SACpB,CAAC,CAAC;IACL,CAAC;CA2EF"}

package/dist/src/handlers/component-map-handler.d.ts

@@ -0,0 +1,14 @@
+import { ReadResourceTemplateCallback, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SpecLoaderService } from '../types.js';
+import { IFormatter } from '../services/formatters.js';
+/**
+ * Handles requests for listing component names of a specific type.
+ * Corresponds to the `openapi://components/{type}` template.
+ */
+export declare class ComponentMapHandler {
+    private specLoader;
+    private formatter;
+    constructor(specLoader: SpecLoaderService, formatter: IFormatter);
+    getTemplate(): ResourceTemplate;
+    handleRequest: ReadResourceTemplateCallback;
+}