mcp-openapi-schema-explorer 1.1.0 → 1.2.1

package/.devcontainer/Dockerfile

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

package/.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
   "name": "MCP OpenAPI Schema Explorer",
-  "dockerFile": "../Dockerfile",
+  "dockerFile": "Dockerfile", // Updated path
   "features": {
     "ghcr.io/devcontainers/features/common-utils:2": {
       "username": "vscode"

package/.github/workflows/ci.yml

@@ -96,6 +96,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
@@ -105,8 +106,27 @@ jobs:
       - 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 }}
+          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,6 +1,3 @@
 #!/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/.releaserc.json

@@ -18,6 +18,14 @@
         "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/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [1.2.1](https://github.com/kadykov/mcp-openapi-schema-explorer/compare/v1.2.0...v1.2.1) (2025-04-13)
+
+### Bug Fixes
+
+- update Node.js setup to match Dockerfile version and include dev dependencies ([8658705](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/86587059268ad4c18d219729b39e4e4f990e05e9))
+
+# [1.2.0](https://github.com/kadykov/mcp-openapi-schema-explorer/compare/v1.1.0...v1.2.0) (2025-04-13)
+
+### Bug Fixes
+
+- remove husky.sh sourcing from pre-commit hook ([2cf9455](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/2cf9455f1432cb0c6cbda71d61cad9f2f87031ab))
+- update Docker Hub login to use secrets for credentials ([ab2136b](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/ab2136bd8c052d7287ef1fd6d2768a9fd93148c8))
+
+### Features
+
+- implement Docker support with multi-stage builds and CI integration ([910dc02](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/910dc021b3e203574dee93198ce5896a9e8aa16d))
+
 # [1.1.0](https://github.com/kadykov/mcp-openapi-schema-explorer/compare/v1.0.2...v1.1.0) (2025-04-13)
 
 ### Features

package/Dockerfile

@@ -1,3 +1,32 @@
-FROM node:22-alpine3.21
+# Stage 1: Builder
+FROM node:22-alpine AS builder
 
-WORKDIR /workspaces/mcp-openapi-schema-explorer
+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"]

package/README.md

@@ -62,7 +62,83 @@ This server is designed to be run by MCP clients. The recommended way to configu
 
 - 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 and using a unique server name.
 
-## Alternative: Global Installation
+## Usage with Docker
+
+As an alternative to `npx` or global installation, you can run the server using Docker. The official image is available on Docker Hub: `kadykov/mcp-openapi-schema-explorer`.
+
+**Running the Container:**
+
+The container expects the path or URL to the OpenAPI specification as a command-line argument, similar to the `npx` usage.
+
+- **Remote 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
+  ```
+
+- **Local File:** Mount the 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 path to your local file)_
+
+- **Output Format:** You can still use the `--output-format` flag:
+  ```bash
+  docker run --rm -i kadykov/mcp-openapi-schema-explorer:latest https://petstore3.swagger.io/api/v3/openapi.json --output-format yaml
+  ```
+
+**Example MCP Client Configuration (Docker):**
+
+Here's how you might configure this in a client like Claude Desktop (`claude_desktop_config.json`):
+
+- **Using a Remote URL:**
+
+  ```json
+  {
+    "mcpServers": {
+      "My API Spec (Docker Remote)": {
+        "command": "docker",
+        "args": [
+          "run",
+          "--rm",
+          "-i",
+          "kadykov/mcp-openapi-schema-explorer:latest",
+          "https://petstore3.swagger.io/api/v3/openapi.json"
+        ],
+        "env": {}
+      }
+    }
+  }
+  ```
+
+- **Using a Local File:**
+  ```json
+  {
+    "mcpServers": {
+      "My API Spec (Docker Local)": {
+        "command": "docker",
+        "args": [
+          "run",
+          "--rm",
+          "-i",
+          "-v",
+          "/full/path/to/your/local/openapi.yaml:/spec/api.yaml",
+          "kadykov/mcp-openapi-schema-explorer:latest",
+          "/spec/api.yaml",
+          "--output-format",
+          "yaml"
+        ],
+        "env": {}
+      }
+    }
+  }
+  ```
+  _(Remember to replace `/full/path/to/your/local/openapi.yaml` with the correct absolute path on your host machine)_
+
+## Alternative: Global Installation (Less Common)
 
 If you prefer, you can install the server globally:
 
@@ -148,4 +224,4 @@ This project uses [`semantic-release`](https://github.com/semantic-release/seman
 
 ## Future Plans
 
-- Docker container support for easier deployment.
+(Future plans to be determined)

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.1.0";
+export declare const VERSION = "1.2.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.1.0';
+export const VERSION = '1.2.1';
 //# sourceMappingURL=version.js.map

package/memory-bank/activeContext.md

@@ -29,9 +29,24 @@ Completed setup of automated versioning and releases using `semantic-release` an
     - Added `extractions/setup-just@v3` action to both jobs.
     - Updated `test` job to run checks via `just all`.
     - Updated `security` job to run checks via `just security` (keeping CodeQL separate).
-    - Added a new `release` job triggered on pushes to `main` (after `test` and `security` pass) that runs `npx semantic-release`. Configured necessary permissions and environment variables (`GITHUB_TOKEN`, placeholder for `NPM_TOKEN`).
+    - Added a new `release` job triggered on pushes to `main` (after `test` and `security` pass) that uses `cycjimmy/semantic-release-action@v4`. Configured necessary permissions and environment variables (`GITHUB_TOKEN`, `NPM_TOKEN`).
 5.  **Memory Bank Update (✓):** Updated `activeContext.md`, `progress.md`, `systemPatterns.md`, and `techContext.md`.
 
+### Docker Support Implementation (✓)
+
+1.  **Dockerfile Strategy:**
+    - Moved existing devcontainer `Dockerfile` to `.devcontainer/Dockerfile`.
+    - Updated `.devcontainer/devcontainer.json` to reference the new path.
+    - Created a new multi-stage production `Dockerfile` at the project root (`./Dockerfile`).
+2.  **Docker Plugin:**
+    - Installed `@codedependant/semantic-release-docker` dev dependency.
+    - Configured the plugin in `.releaserc.json` to publish to `kadykov/mcp-openapi-schema-explorer` on Docker Hub, disabling the plugin's built-in login.
+3.  **CI Workflow Update (`.github/workflows/ci.yml`):**
+    - Added Docker setup steps (QEMU, Buildx, Login using `docker/login-action@v3` with `DOCKERHUB_USERNAME` var and `DOCKERHUB_TOKEN` secret) to the `release` job.
+    - Updated the `cycjimmy/semantic-release-action@v4` step to include `@codedependant/semantic-release-docker` in `extra_plugins`.
+    - Removed redundant Node.js setup and `npm ci` steps from the `release` job, as the action handles plugin installation.
+4.  **Documentation:** Updated `README.md` with a "Usage with Docker" section, including `docker run` examples and MCP client configuration examples for local and remote specs.
+
 ### Dynamic Server Name (✓)
 
 1.  **Spec Loading:** Modified `src/index.ts` to load the OpenAPI spec using `createSpecLoader` _before_ initializing `McpServer`.
@@ -113,7 +128,8 @@ Completed setup of automated versioning and releases using `semantic-release` an
 - Added `json-minified` output format option.
 - Server name is now dynamically set based on the loaded spec's `info.title`.
 - **New:** Automated versioning and release process implemented using `semantic-release`.
-- **New:** CI workflow adapted for Node 22, uses `just` for checks, and includes a release job.
+- **New:** CI workflow adapted for Node 22, uses `just` for checks, and includes a `release` job using `cycjimmy/semantic-release-action@v4`.
+- **New:** Docker support added, including a production `Dockerfile`, integration with `semantic-release` via `@codedependant/semantic-release-docker`, and updated CI workflow for automated Docker Hub publishing.
 - Dependencies correctly categorized (`swagger2openapi` in `dependencies`, types in `devDependencies`).
 - Resource completion logic implemented.
 - Dynamic server name implemented.
@@ -125,10 +141,10 @@ Completed setup of automated versioning and releases using `semantic-release` an
 
 ## Next Actions / Immediate Focus
 
-1.  **README Update:** Enhance `README.md` with:
-    - Details about the automated release process and the requirement for Conventional Commits.
-    - Instructions for setting up the `NPM_TOKEN` secret for publishing.
-    - Updated usage examples and explanations (including `json-minified` format).
+1.  **README Update (Partially Done):**
+    - **Done:** Added Docker usage instructions.
+    - **TODO:** Add details about the automated release process (npm + Docker) and Conventional Commits requirement.
+    - **TODO:** Add instructions for setting up `NPM_TOKEN`, `DOCKERHUB_USERNAME`, and `DOCKERHUB_TOKEN` secrets/variables.
 2.  **Handler Unit Tests:** Implement comprehensive unit tests for each handler class (`TopLevelFieldHandler`, `PathItemHandler`, etc.), mocking `SpecLoaderService` and `IFormatter`.
 3.  **Refactor Helpers:** Consolidate duplicated helper functions (`formatResults`, `isOpenAPIV3`) fully into `handler-utils.ts` and remove from individual handlers.
 4.  **Code Cleanup:** Address remaining TODOs (e.g., checking warnings in `spec-loader.ts`) and minor ESLint warnings.

package/memory-bank/productContext.md

@@ -22,18 +22,20 @@ An MCP server that:
 
 ## User Experience Goals
 
-1. Easy installation via npm.
+1. Easy installation/usage via npm (`npx`) or Docker.
 2. Simple configuration via a single command-line argument (path or URL).
 3. Intuitive resource URIs for exploring API parts.
 4. Clear and consistent response formats.
 
 ## Usage Workflow
 
-1. User installs MCP server via `npm install -g mcp-openapi-schema-explorer`.
-2. User runs the server providing the path or URL to the spec file via CLI argument (e.g., `mcp-openapi-schema-explorer ./spec.yaml` or `mcp-openapi-schema-explorer https://.../spec.json`).
-3. Server loads the spec (from file or URL), converts v2.0 to v3.0 if necessary, and transforms internal references to MCP URIs.
-4. LLM explores API structure through exposed resources:
+1. User configures the server in their MCP client using either:
+   - `npx mcp-openapi-schema-explorer <path-or-url-to-spec> [options]` (Recommended for most users)
+   - `docker run kadykov/mcp-openapi-schema-explorer:latest <path-or-url-to-spec> [options]` (Requires Docker, local files need volume mounting)
+   - Global installation (`npm i -g ...` then `mcp-openapi-schema-explorer ...`) (Less common)
+2. Server loads the spec (from file or URL), converts v2.0 to v3.0 if necessary, and transforms internal references to MCP URIs.
+3. LLM explores API structure through exposed resources:
    - List paths, components, methods.
    - View details for info, operations, components, etc.
    - Follow transformed reference URIs (`openapi://components/...`) to view component details without loading the whole spec initially.
-5. Server restarts required if the source specification file/URL content changes.
+4. Server restarts required if the source specification file/URL content changes.

package/memory-bank/progress.md

@@ -45,6 +45,13 @@
     - Created new E2E test file (`spec-loading.test.ts`) to verify loading from local v2 and remote v3 sources.
     - Added v2.0 test fixture (`sample-v2-api.json`).
 
+### Docker Support (✓)
+
+1.  **Dockerfile:** Added a multi-stage production `Dockerfile` at the root. Moved the devcontainer Dockerfile to `.devcontainer/`.
+2.  **Release Integration:** Added `@codedependant/semantic-release-docker` plugin to `.releaserc.json` to automate Docker image building and publishing to Docker Hub (`kadykov/mcp-openapi-schema-explorer`).
+3.  **CI Workflow:** Updated the `release` job in `.github/workflows/ci.yml` to set up Docker environment (QEMU, Buildx, Login) and use `cycjimmy/semantic-release-action@v4` with the Docker plugin included in `extra_plugins`. Removed redundant Node setup/install steps from the release job.
+4.  **Documentation:** Updated `README.md` with instructions and examples for running the server via Docker.
+
 ## Technical Features (✓)
 
 ### Codebase Organization (Updated)
@@ -106,7 +113,7 @@
 1.  **Dependency Correction:** Correctly categorized runtime (`swagger2openapi`) vs. development (`@types/*`) dependencies in `package.json`. Removed unused types.
 2.  **Automated Releases:** Implemented `semantic-release` with conventional commit analysis, changelog generation, npm publishing, and GitHub releases.
 3.  **Dynamic Versioning:** Server version is now dynamically injected via `src/version.ts`, which is generated during the release process by `semantic-release` using `scripts/generate-version.js`. A default version file is tracked in Git for local builds.
-4.  **CI Workflow:** Updated `.github/workflows/ci.yml` to use Node 22, remove Docker Compose, use `just` for running checks (`just all`, `just security`), and added a `release` job to automate publishing on pushes to `main`.
+4.  **CI Workflow:** Updated `.github/workflows/ci.yml` to use Node 22, use `just` for running checks (`just all`, `just security`), and includes a `release` job using `cycjimmy/semantic-release-action@v4` to automate npm and Docker Hub publishing on pushes to `main`.
 
 ## Planned Features (⏳)
 
@@ -118,6 +125,7 @@
 - **Enhanced Component Support:** Ensure all component types listed in `VALID_COMPONENT_TYPES` are fully handled if present in spec. (Reference transformation now supports all types).
 - **Parameter Validation:** Add validation logic if needed. (Current Map-based approach handles key validation).
 - **Further Token Optimizations:** Explore more ways to reduce token usage in list/detail views.
+- **README Enhancements:** Add details on release process, secrets/vars setup. (Partially done).
 
 ## Technical Improvements (Ongoing)
 
@@ -133,7 +141,7 @@
    - Unit tests updated for URI builder, reference transformer, and path item rendering.
    - E2E tests updated for new structure and complex fixture. Added tests for resource completion.
    - Unit tests for `SpecLoaderService` updated for `swagger2openapi`.
-   - CI workflow updated to use `just` and includes automated release job.
+   - CI workflow updated to use `just` and includes automated release job for npm and Docker.
 
 3. API Design
    - New URI structure implemented, aligned with OpenAPI spec.

package/memory-bank/systemPatterns.md

@@ -128,8 +128,11 @@ graph TD
   4.  `@semantic-release/npm`: Updates `version` in `package.json`.
   5.  `@semantic-release/exec`: Runs `scripts/generate-version.js` to create/update `src/version.ts` with the new version.
   6.  `@semantic-release/git`: Commits `package.json`, `package-lock.json`, `CHANGELOG.md`, and `src/version.ts`. Creates Git tag.
-  7.  `@semantic-release/github`: Creates GitHub Release.
-- **Trigger:** Executed by the `release` job in the GitHub Actions workflow (`.github/workflows/ci.yml`) on pushes to the `main` branch.
+  7.  `@codedependant/semantic-release-docker`: Builds the Docker image using `./Dockerfile` and pushes it to Docker Hub (`kadykov/mcp-openapi-schema-explorer`) with `latest` and version tags.
+  8.  `@semantic-release/github`: Creates GitHub Release.
+- **Trigger:** Executed by the `release` job in the GitHub Actions workflow (`.github/workflows/ci.yml`) on pushes to the `main` branch, using `cycjimmy/semantic-release-action@v4`.
+- **CI Action:** The `cycjimmy/semantic-release-action` handles installing `semantic-release` and the plugins listed in its `extra_plugins` input (`@semantic-release/changelog`, `@semantic-release/exec`, `@semantic-release/git`, `@codedependant/semantic-release-docker`).
+- **Docker Environment:** The CI job sets up Docker QEMU, Buildx, and logs into Docker Hub before running the semantic-release action.
 - **Versioning:** The server version in `src/index.ts` is dynamically imported from the generated `src/version.ts`. A default `src/version.ts` (with `0.0.0-dev`) is kept in the repository for local builds.
 
 ## Resource Design Patterns
@@ -221,4 +224,4 @@ graph TD
 4. **CI Integration (`.github/workflows/ci.yml`):**
    - **`test` Job:** Runs on push/PR to `main`. Uses Node 22, installs `just`, runs `npm ci`, then `just all` (format, lint, build, test). Uploads coverage.
    - **`security` Job:** Runs on push/PR to `main`. Uses Node 22, installs `just`, runs `npm ci`, then `just security` (audit, licenses). Runs CodeQL analysis separately.
-   - **`release` Job:** Runs _only_ on push to `main` after `test` and `security` pass. Checks out full history, installs dependencies, runs `npx semantic-release` using `GITHUB_TOKEN` and `NPM_TOKEN`.
+   - **`release` Job:** Runs _only_ on push to `main` after `test` and `security` pass. Checks out full history, sets up Docker (QEMU, Buildx, Login), then runs `cycjimmy/semantic-release-action@v4` with necessary `extra_plugins` and environment variables (`GITHUB_TOKEN`, `NPM_TOKEN`, Docker Hub credentials handled by login action).

package/memory-bank/techContext.md

@@ -19,7 +19,7 @@
 - `jest`: Testing framework (devDependency)
 - `eslint`: Code linting (devDependency)
 - `prettier`: Code formatting (devDependency)
-- `semantic-release` & plugins (`@semantic-release/*`): Automated releases (devDependencies)
+- `semantic-release` & plugins (`@semantic-release/*`, `@codedependant/semantic-release-docker`): Automated releases (devDependencies)
 - `just`: Task runner (Used locally, installed via action in CI)
 
 ## Technical Requirements
@@ -71,6 +71,7 @@
 - CI Integration (`.github/workflows/ci.yml`):
   - Runs checks (`just all`, `just security`, CodeQL) on pushes/PRs to `main`.
   - Uses Node 22 environment.
+  - Includes automated release job using `cycjimmy/semantic-release-action@v4`.
 
 ## Response Formats
 
@@ -99,10 +100,12 @@
 
 ## Deployment / Release Process
 
-- Automated publishing to npm via `semantic-release` triggered by pushes to `main` branch in GitHub Actions.
+- Automated publishing to npm **and Docker Hub** (`kadykov/mcp-openapi-schema-explorer`) via `semantic-release` triggered by pushes to `main` branch in GitHub Actions.
+- Uses `cycjimmy/semantic-release-action@v4` in the CI workflow.
 - Relies on Conventional Commits to determine version bumps.
+- Uses `@codedependant/semantic-release-docker` plugin for Docker build and push.
 - Creates version tags (e.g., `v1.2.3`) and GitHub Releases automatically.
-- Requires `NPM_TOKEN` secret configured in GitHub repository for publishing.
+- Requires `NPM_TOKEN`, `DOCKERHUB_USERNAME`, and `DOCKERHUB_TOKEN` secrets/variables configured in GitHub repository.
 - `CHANGELOG.md` is automatically generated and updated.
 - Server version is dynamically set at runtime based on the release version.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-openapi-schema-explorer",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "MCP OpenAPI schema explorer",
   "type": "module",
   "main": "dist/src/index.js",
@@ -43,6 +43,7 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@codedependant/semantic-release-docker": "^5.1.0",
     "@eslint/js": "^9.24.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",

package/src/version.ts

@@ -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.1.0';
+export const VERSION = '1.2.1';