mcp-openapi-schema-explorer 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.3.1](https://github.com/kadykov/mcp-openapi-schema-explorer/compare/v1.3.0...v1.3.1) (2025-11-20)
+
+### Bug Fixes
+
+- **package:** exclude unnecessary files from npm artifact ([b1fc7f6](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/b1fc7f677ad7e008f078956cbc8e1e3f16b2679f))
+
 # [1.3.0](https://github.com/kadykov/mcp-openapi-schema-explorer/compare/v1.2.1...v1.3.0) (2025-08-12)
 
 ### Bug Fixes

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/logo-400.png" alt="MCP OpenAPI Schema Explorer Logo" width="200">
+  <img src="https://github.com/kadykov/mcp-openapi-schema-explorer/raw/main/assets/logo.min.svg" alt="MCP OpenAPI Schema Explorer Logo" width="200">
 </p>
 
 # MCP OpenAPI Schema Explorer
@@ -10,7 +10,8 @@
 [![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)
 [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/819a3ba3-ad54-4657-9241-648497e57d7b)
-[![](https://tokei.rs/b1/github/kadykov/mcp-openapi-schema-explorer?category=code)](https://github.com/kadykov/mcp-openapi-schema-explorer)
+[![Lines of code](https://tokei.rs/b1/github/kadykov/mcp-openapi-schema-explorer?category=code)](https://github.com/kadykov/mcp-openapi-schema-explorer)
+[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/kadykov/mcp-openapi-schema-explorer)](https://archestra.ai/mcp-catalog/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**.
 
@@ -230,14 +231,12 @@ Some resource templates include parameters ending with an asterisk (`*`), like `
 **Resource Templates:**
 
 - **`openapi://{field}`**
-
   - **Description:** Accesses top-level fields of the OpenAPI document (e.g., `info`, `servers`, `tags`) or lists the contents of `paths` or `components`. The specific available fields depend on the loaded specification.
   - **Example:** `openapi://info`
   - **Output:** `text/plain` list for `paths` and `components`; configured format (JSON/YAML/minified JSON) for other fields.
   - **Completions:** Provides dynamic suggestions for `{field}` based on the actual top-level keys found in the loaded spec.
 
 - **`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`).
   - **Example:** `openapi://paths/users%2F%7Bid%7D`
@@ -245,7 +244,6 @@ Some resource templates include parameters ending with an asterisk (`*`), like `
   - **Completions:** Provides dynamic suggestions for `{path}` based on the paths found in the loaded spec (URL-encoded).
 
 - **`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**.
@@ -256,7 +254,6 @@ Some resource templates include parameters ending with an asterisk (`*`), like `
   - **Completions:** Provides dynamic suggestions for `{path}`. Provides static suggestions for `{method*}` (common HTTP verbs like GET, POST, PUT, DELETE, etc.).
 
 - **`openapi://components/{type}`**
-
   - **Description:** Lists the names of all defined components of a specific type (e.g., `schemas`, `responses`, `parameters`). The specific available types depend on the loaded specification. Also provides a short description for each listed type.
   - **Example:** `openapi://components/schemas`
   - **Output:** `text/plain` list of component names with descriptions.

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.3.0";
+export declare const VERSION = "1.3.1";

package/dist/src/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-openapi-schema-explorer",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "MCP OpenAPI schema explorer",
   "type": "module",
   "main": "dist/src/index.js",
@@ -8,6 +8,10 @@
   "bin": {
     "mcp-openapi-schema-explorer": "dist/src/index.js"
   },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "rm -rf dist && mkdir -p dist && npx tsc && chmod +x dist/src/index.js",
     "test": "jest",
@@ -49,8 +53,8 @@
     "@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/github": "^12.0.0",
+    "@semantic-release/npm": "^13.1.1",
     "@semantic-release/release-notes-generator": "^14.0.3",
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
@@ -70,7 +74,7 @@
     "msw": "^2.7.4",
     "openapi-typescript": "^7.6.1",
     "prettier": "^3.5.3",
-    "semantic-release": "^24.2.3",
+    "semantic-release": "^25.0.1",
     "ts-jest": "^29.3.1",
     "typescript": "^5.8.3"
   }

package/.devcontainer/Dockerfile

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

package/.devcontainer/devcontainer.json

@@ -1,24 +0,0 @@
-{
-  "name": "MCP OpenAPI Schema Explorer",
-  "dockerFile": "Dockerfile", // Updated path
-  "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

@@ -1,25 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: 'npm'
-    directory: '/'
-    schedule:
-      interval: 'weekly'
-    open-pull-requests-limit: 10
-    groups:
-      # Group all development dependencies together
-      dev-dependencies:
-        dependency-type: 'development'
-
-      # Group production dependencies together
-      production-dependencies:
-        dependency-type: 'production'
-
-  - package-ecosystem: 'github-actions'
-    directory: '/'
-    schedule:
-      interval: 'weekly'
-    open-pull-requests-limit: 10
-    groups:
-      github-actions:
-        patterns:
-          - '*'

package/.github/workflows/ci.yml

@@ -1,132 +0,0 @@
-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
-        with:
-          persist-credentials: false
-
-      - 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
-
-      # Docker setup steps (Still needed for the environment where the action runs)
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Semantic Release
-        uses: cycjimmy/semantic-release-action@v4
-        with:
-          # Add the docker plugin to extra_plugins
-          extra_plugins: |
-            @semantic-release/changelog
-            @semantic-release/exec
-            @semantic-release/git
-            @codedependant/semantic-release-docker
-        env:
-          GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }} # Use dedicated release token if needed
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          # Docker login is handled by the login-action step above

package/.husky/pre-commit

@@ -1,3 +0,0 @@
-#!/usr/bin/env sh
-prettier $(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g') --write --ignore-unknown
-git update-index --again

package/.prettierignore

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

package/.prettierrc.json

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

package/.releaserc.json

@@ -1,31 +0,0 @@
-{
-  "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}"
-      }
-    ],
-    [
-      "@codedependant/semantic-release-docker",
-      {
-        "dockerProject": "kadykov",
-        "dockerImage": "mcp-openapi-schema-explorer",
-        "dockerLogin": false
-      }
-    ],
-    "@semantic-release/github"
-  ]
-}

package/.tokeignore

@@ -1 +0,0 @@
-package-lock.json

package/CONTRIBUTING.md

@@ -1,67 +0,0 @@
-# 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/DOCKERHUB_README.md

@@ -1,126 +0,0 @@
-# MCP OpenAPI Schema Explorer
-
-[![Docker Pulls](https://img.shields.io/docker/pulls/kadykov/mcp-openapi-schema-explorer.svg)](https://hub.docker.com/r/kadykov/mcp-openapi-schema-explorer)
-[![GitHub Repo](https://img.shields.io/badge/GitHub-kadykov/mcp--openapi--schema--explorer-blue?logo=github)](https://github.com/kadykov/mcp-openapi-schema-explorer)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-This Docker image runs the **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**.
-
-It allows 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.
-
-**Source Code & Full Documentation:** [https://github.com/kadykov/mcp-openapi-schema-explorer](https://github.com/kadykov/mcp-openapi-schema-explorer)
-
-## 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 (via volume mount) or HTTP/HTTPS URLs.
-- **Token-Efficient:** Designed to minimize token usage for LLMs.
-- **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.
-
-## How to Run
-
-Pull the image:
-
-```bash
-docker pull kadykov/mcp-openapi-schema-explorer:latest
-```
-
-The container expects the path or URL to the OpenAPI specification as a command-line argument.
-
-### Using a Remote Specification URL
-
-Pass the URL directly to `docker run`:
-
-```bash
-docker run --rm -i kadykov/mcp-openapi-schema-explorer:latest https://petstore3.swagger.io/api/v3/openapi.json
-```
-
-### Using a Local Specification File
-
-Mount your local file into the container using the `-v` flag and provide the path _inside the container_ as the argument:
-
-```bash
-# Example: Mount local file ./my-spec.yaml to /spec/api.yaml inside the container
-docker run --rm -i -v "$(pwd)/my-spec.yaml:/spec/api.yaml" kadykov/mcp-openapi-schema-explorer:latest /spec/api.yaml
-```
-
-_(Note: Replace `$(pwd)/my-spec.yaml` with the actual absolute path to your local file on the host machine)_
-
-### Specifying Output Format
-
-Use the `--output-format` flag (optional, defaults to `json`):
-
-```bash
-# Using YAML output with a remote URL
-docker run --rm -i kadykov/mcp-openapi-schema-explorer:latest https://petstore3.swagger.io/api/v3/openapi.json --output-format yaml
-
-# Using minified JSON with a local file
-docker run --rm -i -v "$(pwd)/my-spec.yaml:/spec/api.yaml" kadykov/mcp-openapi-schema-explorer:latest /spec/api.yaml --output-format json-minified
-```
-
-Supported formats: `json`, `yaml`, `json-minified`.
-
-## Tags
-
-- `latest`: Points to the most recent stable release.
-- Specific version tags (e.g., `1.2.1`) are available corresponding to the npm package versions.
-
-## Usage with MCP Clients
-
-You can configure your MCP client (like Cline or Claude Desktop) to run this Docker image as an MCP server.
-
-### Example: Remote URL Specification
-
-```json
-// Example: ~/.config/cline/mcp_config.json
-{
-  "mcpServers": {
-    "My API Spec (Docker Remote)": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "-i", // Required for MCP communication
-        "kadykov/mcp-openapi-schema-explorer:latest",
-        "https://petstore3.swagger.io/api/v3/openapi.json"
-        // Optional: Add "--output-format", "yaml" here if needed
-      ],
-      "env": {}
-    }
-  }
-}
-```
-
-### Example: Local File Specification
-
-```json
-// Example: ~/.config/cline/mcp_config.json
-{
-  "mcpServers": {
-    "My API Spec (Docker Local)": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "-i", // Required for MCP communication
-        "-v",
-        "/full/path/to/your/local/openapi.yaml:/spec/api.yaml", // Host path : Container path
-        "kadykov/mcp-openapi-schema-explorer:latest",
-        "/spec/api.yaml", // Path inside the container
-        "--output-format",
-        "yaml" // Optional format
-      ],
-      "env": {}
-    }
-  }
-}
-```
-
-_(Remember to replace `/full/path/to/your/local/openapi.yaml` with the correct absolute path on your host machine)_
-
-## Support
-
-For issues or questions, please refer to the [GitHub repository](https://github.com/kadykov/mcp-openapi-schema-explorer) or open an [issue](https://github.com/kadykov/mcp-openapi-schema-explorer/issues).

package/Dockerfile

@@ -1,32 +0,0 @@
-# Stage 1: Builder
-FROM node:22-alpine AS builder
-
-WORKDIR /app
-
-# Copy necessary files for installation and build
-COPY package.json package-lock.json ./
-COPY tsconfig.json ./
-COPY src ./src
-
-# Install all dependencies (including devDependencies needed for build)
-RUN npm ci
-
-# Build the project
-RUN npm run build
-
-# Stage 2: Release
-FROM node:22-alpine AS release
-
-WORKDIR /app
-
-# Copy only necessary files from the builder stage
-COPY --from=builder /app/package.json ./package.json
-COPY --from=builder /app/package-lock.json ./package-lock.json
-COPY --from=builder /app/dist ./dist
-
-# Install only production dependencies
-RUN npm ci --omit=dev --ignore-scripts
-
-# Set the entrypoint to run the compiled server
-# Corrected path based on tsconfig.json ("rootDir": ".", "outDir": "dist")
-ENTRYPOINT ["node", "dist/src/index.js"]