mcp-openapi-schema-explorer 1.0.2 → 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,26 @@
+## [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
+
+- enhance component and path item rendering with descriptions and examples in hints ([6989159](https://github.com/kadykov/mcp-openapi-schema-explorer/commit/698915972338b4a16419c9cea3e2377b7701f50b))
+
 ## [1.0.2](https://github.com/kadykov/mcp-openapi-schema-explorer/compare/v1.0.1...v1.0.2) (2025-04-13)
 
 ### Bug Fixes

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

@@ -33,28 +33,112 @@ This server is designed to be run by MCP clients. The recommended way to configu
 {
   "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
+        "-y",
         "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"
+        "/path/to/your/local/openapi.json",
+        "--output-format",
+        "yaml"
       ],
-      "env": {} // No environment variables needed currently
+      "env": {}
     }
   }
 }
 ```
 
+**Configuration Details:**
+
+- **`"My API Spec"`:** Choose a descriptive name for this server instance. This is how you'll identify it within your MCP client.
+- **`command`:** Use `"npx"` to run the package directly.
+- **`args`:**
+  - `"-y"`: Auto-confirms the `npx` installation prompt if needed the first time.
+  - `"mcp-openapi-schema-explorer"`: The name of the package to execute.
+  - `"/path/to/your/local/openapi.json"`: **Required.** The absolute path to your local spec file or the full URL to a remote spec (e.g., `"https://remote/url/spec.json"`).
+  - `"--output-format", "yaml"`: **Optional.** Specifies the output format for detailed resource views. Defaults to `"json"`. Other options are `"yaml"` and `"json-minified"`.
+- **`env`:** Currently, no environment variables are needed for this server.
+
 **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.
+- 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.
+
+## 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
+  ```
 
-## Alternative: Global Installation
+**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:
 
@@ -79,40 +163,56 @@ If installed globally, your MCP client configuration would change:
 
 ## Available MCP Resources
 
-This server exposes the following MCP resource templates for exploring the OpenAPI specification:
+This server exposes the following MCP resource templates for exploring the OpenAPI specification.
+
+**Understanding Multi-Value Parameters (`*`)**
+
+Some resource templates include parameters ending with an asterisk (`*`), like `{method*}` or `{name*}`. This indicates that the parameter accepts **multiple comma-separated values**. For example, to request details for both the `GET` and `POST` methods of a path, you would use a URI like `openapi://paths/users/get,post`. This allows fetching details for multiple items in a single request.
+
+**Resource Templates:**
 
 - **`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`).
+  - **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`
   - **Output:** `text/plain` list of methods.
+  - **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**.
-    - `{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`).
+    - `{method*}` - One or more HTTP methods (e.g., `get`, `post`, `get,post`). Case-insensitive.
+  - **Example (Single):** `openapi://paths/users%2F%7Bid%7D/get`
+  - **Example (Multiple):** `openapi://paths/users%2F%7Bid%7D/get,post`
   - **Output:** Configured format (JSON/YAML/minified JSON).
+  - **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.
-  - **Parameter:** `{type}` - The component type (e.g., `schemas`, `responses`, `parameters`, `examples`, `requestBodies`, `headers`, `securitySchemes`, `links`, `callbacks`).
-  - **Output:** `text/plain` list of component names.
+  - **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.
+  - **Completions:** Provides dynamic suggestions for `{type}` based on the component types found in the loaded spec.
 
 - **`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`).
+    - `{name*}` - One or more component names (e.g., `User`, `Order`, `User,Order`). Case-sensitive.
+  - **Example (Single):** `openapi://components/schemas/User`
+  - **Example (Multiple):** `openapi://components/schemas/User,Order`
   - **Output:** Configured format (JSON/YAML/minified JSON).
+  - **Completions:** Provides dynamic suggestions for `{type}`. Provides dynamic suggestions for `{name*}` _only if_ the loaded spec contains exactly one component type overall (e.g., only `schemas`). This limitation exists because the MCP SDK currently doesn't support providing completions scoped to the selected `{type}`; providing all names across all types could be misleading.
 
 ## Contributing
 
@@ -124,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/index.js

@@ -54,7 +54,16 @@ async function main() {
         const operationHandler = new OperationHandler(specLoader, formatter);
         const componentMapHandler = new ComponentMapHandler(specLoader, formatter);
         const componentDetailHandler = new ComponentDetailHandler(specLoader, formatter);
-        // Register new resources
+        // --- Define Resource Templates and Register Handlers ---
+        // Helper to get dynamic field list for descriptions
+        const getFieldList = () => Object.keys(transformedSpec).join(', ');
+        // Helper to get dynamic component type list for descriptions
+        const getComponentTypeList = () => {
+            if (isOpenAPIV3(transformedSpec) && transformedSpec.components) {
+                return Object.keys(transformedSpec.components).join(', ');
+            }
+            return ''; // Return empty if no components or not V3
+        };
         // 1. openapi://{field}
         const fieldTemplate = new ResourceTemplate('openapi://{field}', {
             list: undefined, // List is handled by the handler logic based on field value
@@ -64,8 +73,8 @@ async function main() {
         });
         server.resource('openapi-field', // Unique ID for the resource registration
         fieldTemplate, {
-            // MimeType varies (text/plain for lists, JSON/YAML for details) - SDK might handle this? Or maybe set a default? Let's omit for now.
-            description: 'Access top-level fields (info, servers, tags), list paths, or list component types.',
+            // MimeType varies (text/plain for lists, JSON/YAML for details)
+            description: `Access top-level fields like ${getFieldList()}. (e.g., openapi://info)`,
             name: 'OpenAPI Field/List', // Generic name
         }, topLevelFieldHandler.handleRequest);
         // 2. openapi://paths/{path}
@@ -77,7 +86,7 @@ async function main() {
         });
         server.resource('openapi-path-methods', pathTemplate, {
             mimeType: 'text/plain', // This always returns a list
-            description: 'List available HTTP methods for a specific path. (Note: {path} must be URL-encoded, e.g., /users/{id} becomes users%2F%7Bid%7D)',
+            description: 'List methods for a specific path (URL encode paths with slashes). (e.g., openapi://paths/users%2F%7Bid%7D)',
             name: 'Path Methods List',
         }, pathItemHandler.handleRequest);
         // 3. openapi://paths/{path}/{method*}
@@ -100,7 +109,7 @@ async function main() {
         });
         server.resource('openapi-operation-detail', operationTemplate, {
             mimeType: formatter.getMimeType(), // Detail view uses formatter
-            description: 'Get details for one or more specific API operations (methods). (Note: {path} must be URL-encoded, e.g., /users/{id} becomes users%2F%7Bid%7D)',
+            description: 'Get details for one or more operations (comma-separated). (e.g., openapi://paths/users%2F%7Bid%7D/get,post)',
             name: 'Operation Detail',
         }, operationHandler.handleRequest);
         // 4. openapi://components/{type}
@@ -118,7 +127,7 @@ async function main() {
         });
         server.resource('openapi-component-list', componentMapTemplate, {
             mimeType: 'text/plain', // This always returns a list
-            description: 'List available components of a specific type (e.g., schemas, parameters).',
+            description: `List components of a specific type like ${getComponentTypeList()}. (e.g., openapi://components/schemas)`,
             name: 'Component List',
         }, componentMapHandler.handleRequest);
         // 5. openapi://components/{type}/{name*}
@@ -131,7 +140,7 @@ async function main() {
                         return Object.keys(transformedSpec.components ?? {});
                     }
                     return []; // Return empty array if not V3
-                }, // <<< Added missing closing brace
+                },
                 name: () => {
                     // Provide names only if there's exactly one component type defined
                     if (isOpenAPIV3(transformedSpec) &&
@@ -157,7 +166,7 @@ async function main() {
         });
         server.resource('openapi-component-detail', componentDetailTemplate, {
             mimeType: formatter.getMimeType(), // Detail view uses formatter
-            description: 'Get details for one or more specific components (e.g., schemas, parameters).',
+            description: 'Get details for one or more components (comma-separated). (e.g., openapi://components/schemas/User,Task)',
             name: 'Component Detail',
         }, componentDetailHandler.handleRequest);
         // Start server

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/rendering/components.js

@@ -11,6 +11,21 @@ export const VALID_COMPONENT_TYPES = [
     'callbacks',
     // 'pathItems' is technically allowed but we handle paths separately
 ];
+// Simple descriptions for component types
+const componentTypeDescriptions = {
+    schemas: 'Reusable data structures (models)',
+    responses: 'Reusable API responses',
+    parameters: 'Reusable request parameters (query, path, header, cookie)',
+    examples: 'Reusable examples of media type payloads',
+    requestBodies: 'Reusable request body definitions',
+    headers: 'Reusable header definitions for responses',
+    securitySchemes: 'Reusable security scheme definitions (e.g., API keys, OAuth2)',
+    links: 'Reusable descriptions of links between responses and operations',
+    callbacks: 'Reusable descriptions of callback operations',
+    // pathItems: 'Reusable path item definitions (rarely used directly here)' // Excluded as per comment above
+};
+// Use a Map for safer lookups against prototype pollution
+const componentDescriptionsMap = new Map(Object.entries(componentTypeDescriptions));
 /**
  * Wraps an OpenAPIV3.ComponentsObject to make it renderable.
  * Handles listing the available component types.
@@ -33,10 +48,15 @@ export class RenderableComponents {
         }
         let listText = 'Available Component Types:\n\n';
         availableTypes.sort().forEach(type => {
-            listText += `- ${type}\n`;
+            const description = componentDescriptionsMap.get(type) ?? 'Unknown component type'; // Removed unnecessary 'as ComponentType'
+            listText += `- ${type}: ${description}\n`;
+        });
+        // Use the new hint generator structure, providing the first type as an example
+        const firstTypeExample = availableTypes.length > 0 ? availableTypes[0] : undefined;
+        listText += generateListHint(context, {
+            itemType: 'componentType',
+            firstItemExample: firstTypeExample,
         });
-        // Use the new hint generator structure
-        listText += generateListHint(context, { itemType: 'componentType' });
         return [
             {
                 uriSuffix: 'components',
@@ -92,10 +112,12 @@ export class RenderableComponentMap {
         names.forEach(name => {
             listText += `- ${name}\n`;
         });
-        // Use the new hint generator structure, providing parent type
+        // Use the new hint generator structure, providing parent type and first name as example
+        const firstNameExample = names.length > 0 ? names[0] : undefined;
         listText += generateListHint(context, {
             itemType: 'componentName',
             parentComponentType: this.componentType,
+            firstItemExample: firstNameExample,
         });
         return [
             {

package/dist/src/rendering/components.js.map

@@ -1 +1 @@
-{"version":3,"file":"components.js","sourceRoot":"","sources":["../../../src/rendering/components.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../../src/rendering/components.ts"],"names":[],"mappings":"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"}

package/dist/src/rendering/path-item.js

@@ -36,14 +36,19 @@ export class RenderablePathItem {
                 },
             ];
         }
-        // Generate hint first using the new structure
+        // Sort methods first to get the correct example
+        methods.sort();
+        const firstMethodExample = methods.length > 0 ? methods[0] : undefined;
+        // Generate hint using the new structure, providing the first *sorted* method as an example
         const hint = generateListHint(context, {
             itemType: 'pathMethod',
             parentPath: this.path, // Use the stored raw path
+            firstItemExample: firstMethodExample,
         });
         // Hint includes leading newline, so start output with it directly
         let outputLines = [hint.trim(), '']; // Trim leading newline from hint for first line
-        methods.sort().forEach(method => {
+        // Iterate over the already sorted methods
+        methods.forEach(method => {
             const operation = this.getOperation(method);
             // Use summary or operationId (via getOperationSummary)
             const summaryText = getOperationSummary(operation);

package/dist/src/rendering/path-item.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-item.js","sourceRoot":"","sources":["../../../src/rendering/path-item.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"path-item.js","sourceRoot":"","sources":["../../../src/rendering/path-item.ts"],"names":[],"mappings":"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"}

package/dist/src/rendering/utils.d.ts

@@ -3,6 +3,7 @@ import { RenderContext, RenderResultItem } from './types.js';
 type ListItemType = 'componentType' | 'componentName' | 'pathMethod';
 interface HintContext {
     itemType: ListItemType;
+    firstItemExample?: string;
     parentComponentType?: string;
     parentPath?: string;
 }

package/dist/src/rendering/utils.js

@@ -21,12 +21,16 @@ export function getOperationSummary(operation) {
 export function generateListHint(renderContext, hintContext) {
     let detailUriSuffixPattern;
     let itemTypeName; // User-friendly name for the item type in the hint text
+    let exampleUriSuffix; // To hold the generated example URI
     switch (hintContext.itemType) {
         case 'componentType':
             // Listing component types (e.g., schemas, responses) at openapi://components
             // Hint should point to openapi://components/{type}
             detailUriSuffixPattern = buildComponentMapUriSuffix('{type}'); // Use placeholder
             itemTypeName = 'component type';
+            if (hintContext.firstItemExample) {
+                exampleUriSuffix = buildComponentMapUriSuffix(hintContext.firstItemExample);
+            }
             break;
         case 'componentName':
             // Listing component names (e.g., MySchema, User) at openapi://components/{type}
@@ -38,6 +42,9 @@ export function generateListHint(renderContext, hintContext) {
             // Use the actual parent type and a placeholder for the name
             detailUriSuffixPattern = buildComponentDetailUriSuffix(hintContext.parentComponentType, '{name}');
             itemTypeName = hintContext.parentComponentType.slice(0, -1); // e.g., 'schema' from 'schemas'
+            if (hintContext.firstItemExample) {
+                exampleUriSuffix = buildComponentDetailUriSuffix(hintContext.parentComponentType, hintContext.firstItemExample);
+            }
             break;
         case 'pathMethod':
             // Listing methods (e.g., get, post) at openapi://paths/{path}
@@ -49,6 +56,10 @@ export function generateListHint(renderContext, hintContext) {
             // Use the actual parent path and a placeholder for the method
             detailUriSuffixPattern = buildOperationUriSuffix(hintContext.parentPath, '{method}');
             itemTypeName = 'operation'; // Or 'method'? 'operation' seems clearer
+            if (hintContext.firstItemExample) {
+                // Ensure the example method is valid if needed, though usually it's just 'get', 'post' etc.
+                exampleUriSuffix = buildOperationUriSuffix(hintContext.parentPath, hintContext.firstItemExample);
+            }
             break;
         default:
             // Explicitly cast to string to avoid potential 'never' type issue in template literal
@@ -57,7 +68,14 @@ export function generateListHint(renderContext, hintContext) {
     }
     // Construct the full hint URI pattern using the base URI
     const fullHintPattern = `${renderContext.baseUri}${detailUriSuffixPattern}`;
-    return `\nHint: Use '${fullHintPattern}' to view details for a specific ${itemTypeName}.`;
+    const fullExampleUri = exampleUriSuffix
+        ? `${renderContext.baseUri}${exampleUriSuffix}`
+        : undefined;
+    let hintText = `\nHint: Use '${fullHintPattern}' to view details for a specific ${itemTypeName}.`;
+    if (fullExampleUri) {
+        hintText += ` (e.g., ${fullExampleUri})`;
+    }
+    return hintText;
 }
 /**
  * Helper to generate a standard error item for RenderResultItem arrays.

package/dist/src/rendering/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/rendering/utils.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,uBAAuB;AACvB,oEAAoE;EACrE,MAAM,yBAAyB,CAAC,CAAC,sBAAsB;AAcxD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAgD;IAEhD,mDAAmD;IACnD,OAAO,SAAS,EAAE,OAAO,IAAI,SAAS,EAAE,WAAW,IAAI,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAA4B,EAAE,WAAwB;IACrF,IAAI,sBAA8B,CAAC;IACnC,IAAI,YAAoB,CAAC,CAAC,wDAAwD;IAElF,QAAQ,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC7B,KAAK,eAAe;YAClB,6EAA6E;YAC7E,mDAAmD;YACnD,sBAAsB,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB;YACjF,YAAY,GAAG,gBAAgB,CAAC;YAChC,MAAM;QACR,KAAK,eAAe;YAClB,gFAAgF;YAChF,0DAA0D;YAC1D,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC;gBACrC,OAAO,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;gBACtF,OAAO,EAAE,CAAC,CAAC,iCAAiC;YAC9C,CAAC;YACD,4DAA4D;YAC5D,sBAAsB,GAAG,6BAA6B,CACpD,WAAW,CAAC,mBAAmB,EAC/B,QAAQ,CACT,CAAC;YACF,YAAY,GAAG,WAAW,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,gCAAgC;YAC7F,MAAM;QACR,KAAK,YAAY;YACf,8DAA8D;YAC9D,uDAAuD;YACvD,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;gBAC5B,OAAO,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;gBAC1E,OAAO,EAAE,CAAC,CAAC,iCAAiC;YAC9C,CAAC;YACD,8DAA8D;YAC9D,sBAAsB,GAAG,uBAAuB,CAAC,WAAW,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACrF,YAAY,GAAG,WAAW,CAAC,CAAC,yCAAyC;YACrE,MAAM;QACR;YACE,sFAAsF;YACtF,OAAO,CAAC,IAAI,CAAC,yCAAyC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YACtF,OAAO,EAAE,CAAC,CAAC,gDAAgD;IAC/D,CAAC;IAED,yDAAyD;IACzD,MAAM,eAAe,GAAG,GAAG,aAAa,CAAC,OAAO,GAAG,sBAAsB,EAAE,CAAC;IAE5E,OAAO,gBAAgB,eAAe,oCAAoC,YAAY,GAAG,CAAC;AAC5F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,OAAe;IAClE,OAAO;QACL;YACE,SAAS,EAAE,SAAS;YACpB,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,OAAO;YAClB,YAAY,EAAE,IAAI,EAAE,kCAAkC;SACvD;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/rendering/utils.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,uBAAuB;AACvB,oEAAoE;EACrE,MAAM,yBAAyB,CAAC,CAAC,sBAAsB;AAexD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAgD;IAEhD,mDAAmD;IACnD,OAAO,SAAS,EAAE,OAAO,IAAI,SAAS,EAAE,WAAW,IAAI,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAA4B,EAAE,WAAwB;IACrF,IAAI,sBAA8B,CAAC;IACnC,IAAI,YAAoB,CAAC,CAAC,wDAAwD;IAClF,IAAI,gBAAoC,CAAC,CAAC,oCAAoC;IAE9E,QAAQ,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC7B,KAAK,eAAe;YAClB,6EAA6E;YAC7E,mDAAmD;YACnD,sBAAsB,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB;YACjF,YAAY,GAAG,gBAAgB,CAAC;YAChC,IAAI,WAAW,CAAC,gBAAgB,EAAE,CAAC;gBACjC,gBAAgB,GAAG,0BAA0B,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;YAC9E,CAAC;YACD,MAAM;QACR,KAAK,eAAe;YAClB,gFAAgF;YAChF,0DAA0D;YAC1D,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC;gBACrC,OAAO,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;gBACtF,OAAO,EAAE,CAAC,CAAC,iCAAiC;YAC9C,CAAC;YACD,4DAA4D;YAC5D,sBAAsB,GAAG,6BAA6B,CACpD,WAAW,CAAC,mBAAmB,EAC/B,QAAQ,CACT,CAAC;YACF,YAAY,GAAG,WAAW,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,gCAAgC;YAC7F,IAAI,WAAW,CAAC,gBAAgB,EAAE,CAAC;gBACjC,gBAAgB,GAAG,6BAA6B,CAC9C,WAAW,CAAC,mBAAmB,EAC/B,WAAW,CAAC,gBAAgB,CAC7B,CAAC;YACJ,CAAC;YACD,MAAM;QACR,KAAK,YAAY;YACf,8DAA8D;YAC9D,uDAAuD;YACvD,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;gBAC5B,OAAO,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;gBAC1E,OAAO,EAAE,CAAC,CAAC,iCAAiC;YAC9C,CAAC;YACD,8DAA8D;YAC9D,sBAAsB,GAAG,uBAAuB,CAAC,WAAW,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACrF,YAAY,GAAG,WAAW,CAAC,CAAC,yCAAyC;YACrE,IAAI,WAAW,CAAC,gBAAgB,EAAE,CAAC;gBACjC,4FAA4F;gBAC5F,gBAAgB,GAAG,uBAAuB,CACxC,WAAW,CAAC,UAAU,EACtB,WAAW,CAAC,gBAAgB,CAC7B,CAAC;YACJ,CAAC;YACD,MAAM;QACR;YACE,sFAAsF;YACtF,OAAO,CAAC,IAAI,CAAC,yCAAyC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YACtF,OAAO,EAAE,CAAC,CAAC,gDAAgD;IAC/D,CAAC;IAED,yDAAyD;IACzD,MAAM,eAAe,GAAG,GAAG,aAAa,CAAC,OAAO,GAAG,sBAAsB,EAAE,CAAC;IAC5E,MAAM,cAAc,GAAG,gBAAgB;QACrC,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,GAAG,gBAAgB,EAAE;QAC/C,CAAC,CAAC,SAAS,CAAC;IAEd,IAAI,QAAQ,GAAG,gBAAgB,eAAe,oCAAoC,YAAY,GAAG,CAAC;IAClG,IAAI,cAAc,EAAE,CAAC;QACnB,QAAQ,IAAI,WAAW,cAAc,GAAG,CAAC;IAC3C,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,OAAe;IAClE,OAAO;QACL;YACE,SAAS,EAAE,SAAS;YACpB,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,OAAO;YAClB,YAAY,EAAE,IAAI,EAAE,kCAAkC;SACvD;KACF,CAAC;AACJ,CAAC"}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.0.2";
+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.0.2';
+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.0.2",
+  "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/index.ts

@@ -64,7 +64,18 @@ async function main(): Promise<void> {
     const componentMapHandler = new ComponentMapHandler(specLoader, formatter);
     const componentDetailHandler = new ComponentDetailHandler(specLoader, formatter);
 
-    // Register new resources
+    // --- Define Resource Templates and Register Handlers ---
+
+    // Helper to get dynamic field list for descriptions
+    const getFieldList = (): string => Object.keys(transformedSpec).join(', ');
+    // Helper to get dynamic component type list for descriptions
+    const getComponentTypeList = (): string => {
+      if (isOpenAPIV3(transformedSpec) && transformedSpec.components) {
+        return Object.keys(transformedSpec.components).join(', ');
+      }
+      return ''; // Return empty if no components or not V3
+    };
+
     // 1. openapi://{field}
     const fieldTemplate = new ResourceTemplate('openapi://{field}', {
       list: undefined, // List is handled by the handler logic based on field value
@@ -76,9 +87,8 @@ async function main(): Promise<void> {
       'openapi-field', // Unique ID for the resource registration
       fieldTemplate,
       {
-        // MimeType varies (text/plain for lists, JSON/YAML for details) - SDK might handle this? Or maybe set a default? Let's omit for now.
-        description:
-          'Access top-level fields (info, servers, tags), list paths, or list component types.',
+        // MimeType varies (text/plain for lists, JSON/YAML for details)
+        description: `Access top-level fields like ${getFieldList()}. (e.g., openapi://info)`,
         name: 'OpenAPI Field/List', // Generic name
       },
       topLevelFieldHandler.handleRequest
@@ -97,7 +107,7 @@ async function main(): Promise<void> {
       {
         mimeType: 'text/plain', // This always returns a list
         description:
-          'List available HTTP methods for a specific path. (Note: {path} must be URL-encoded, e.g., /users/{id} becomes users%2F%7Bid%7D)',
+          'List methods for a specific path (URL encode paths with slashes). (e.g., openapi://paths/users%2F%7Bid%7D)',
         name: 'Path Methods List',
       },
       pathItemHandler.handleRequest
@@ -127,7 +137,7 @@ async function main(): Promise<void> {
       {
         mimeType: formatter.getMimeType(), // Detail view uses formatter
         description:
-          'Get details for one or more specific API operations (methods). (Note: {path} must be URL-encoded, e.g., /users/{id} becomes users%2F%7Bid%7D)',
+          'Get details for one or more operations (comma-separated). (e.g., openapi://paths/users%2F%7Bid%7D/get,post)',
         name: 'Operation Detail',
       },
       operationHandler.handleRequest
@@ -151,7 +161,7 @@ async function main(): Promise<void> {
       componentMapTemplate,
       {
         mimeType: 'text/plain', // This always returns a list
-        description: 'List available components of a specific type (e.g., schemas, parameters).',
+        description: `List components of a specific type like ${getComponentTypeList()}. (e.g., openapi://components/schemas)`,
         name: 'Component List',
       },
       componentMapHandler.handleRequest
@@ -167,7 +177,7 @@ async function main(): Promise<void> {
             return Object.keys(transformedSpec.components ?? {});
           }
           return []; // Return empty array if not V3
-        }, // <<< Added missing closing brace
+        },
         name: (): string[] => {
           // Provide names only if there's exactly one component type defined
           if (
@@ -197,7 +207,8 @@ async function main(): Promise<void> {
       componentDetailTemplate,
       {
         mimeType: formatter.getMimeType(), // Detail view uses formatter
-        description: 'Get details for one or more specific components (e.g., schemas, parameters).',
+        description:
+          'Get details for one or more components (comma-separated). (e.g., openapi://components/schemas/User,Task)',
         name: 'Component Detail',
       },
       componentDetailHandler.handleRequest

package/src/rendering/components.ts

@@ -17,6 +17,22 @@ export const VALID_COMPONENT_TYPES: ComponentType[] = [
   // 'pathItems' is technically allowed but we handle paths separately
 ];
 
+// Simple descriptions for component types
+const componentTypeDescriptions: Record<ComponentType, string> = {
+  schemas: 'Reusable data structures (models)',
+  responses: 'Reusable API responses',
+  parameters: 'Reusable request parameters (query, path, header, cookie)',
+  examples: 'Reusable examples of media type payloads',
+  requestBodies: 'Reusable request body definitions',
+  headers: 'Reusable header definitions for responses',
+  securitySchemes: 'Reusable security scheme definitions (e.g., API keys, OAuth2)',
+  links: 'Reusable descriptions of links between responses and operations',
+  callbacks: 'Reusable descriptions of callback operations',
+  // pathItems: 'Reusable path item definitions (rarely used directly here)' // Excluded as per comment above
+};
+// Use a Map for safer lookups against prototype pollution
+const componentDescriptionsMap = new Map(Object.entries(componentTypeDescriptions));
+
 /**
  * Wraps an OpenAPIV3.ComponentsObject to make it renderable.
  * Handles listing the available component types.
@@ -43,11 +59,16 @@ export class RenderableComponents implements RenderableSpecObject {
 
     let listText = 'Available Component Types:\n\n';
     availableTypes.sort().forEach(type => {
-      listText += `- ${type}\n`;
+      const description = componentDescriptionsMap.get(type) ?? 'Unknown component type'; // Removed unnecessary 'as ComponentType'
+      listText += `- ${type}: ${description}\n`;
     });
 
-    // Use the new hint generator structure
-    listText += generateListHint(context, { itemType: 'componentType' });
+    // Use the new hint generator structure, providing the first type as an example
+    const firstTypeExample = availableTypes.length > 0 ? availableTypes[0] : undefined;
+    listText += generateListHint(context, {
+      itemType: 'componentType',
+      firstItemExample: firstTypeExample,
+    });
 
     return [
       {
@@ -126,10 +147,12 @@ export class RenderableComponentMap implements RenderableSpecObject {
       listText += `- ${name}\n`;
     });
 
-    // Use the new hint generator structure, providing parent type
+    // Use the new hint generator structure, providing parent type and first name as example
+    const firstNameExample = names.length > 0 ? names[0] : undefined;
     listText += generateListHint(context, {
       itemType: 'componentName',
       parentComponentType: this.componentType,
+      firstItemExample: firstNameExample,
     });
 
     return [

package/src/rendering/path-item.ts

@@ -43,15 +43,21 @@ export class RenderablePathItem implements RenderableSpecObject {
       ];
     }
 
-    // Generate hint first using the new structure
+    // Sort methods first to get the correct example
+    methods.sort();
+    const firstMethodExample = methods.length > 0 ? methods[0] : undefined;
+
+    // Generate hint using the new structure, providing the first *sorted* method as an example
     const hint = generateListHint(context, {
       itemType: 'pathMethod',
       parentPath: this.path, // Use the stored raw path
+      firstItemExample: firstMethodExample,
     });
     // Hint includes leading newline, so start output with it directly
     let outputLines: string[] = [hint.trim(), '']; // Trim leading newline from hint for first line
 
-    methods.sort().forEach(method => {
+    // Iterate over the already sorted methods
+    methods.forEach(method => {
       const operation = this.getOperation(method);
       // Use summary or operationId (via getOperationSummary)
       const summaryText = getOperationSummary(operation);

package/src/rendering/utils.ts

@@ -14,6 +14,7 @@ type ListItemType = 'componentType' | 'componentName' | 'pathMethod';
 // Define context needed for generating the correct detail URI suffix
 interface HintContext {
   itemType: ListItemType;
+  firstItemExample?: string; // Example value from the first item in the list
   // For componentName hints, the parent component type is needed
   parentComponentType?: string;
   // For pathMethod hints, the parent path is needed
@@ -43,6 +44,7 @@ export function getOperationSummary(
 export function generateListHint(renderContext: RenderContext, hintContext: HintContext): string {
   let detailUriSuffixPattern: string;
   let itemTypeName: string; // User-friendly name for the item type in the hint text
+  let exampleUriSuffix: string | undefined; // To hold the generated example URI
 
   switch (hintContext.itemType) {
     case 'componentType':
@@ -50,6 +52,9 @@ export function generateListHint(renderContext: RenderContext, hintContext: Hint
       // Hint should point to openapi://components/{type}
       detailUriSuffixPattern = buildComponentMapUriSuffix('{type}'); // Use placeholder
       itemTypeName = 'component type';
+      if (hintContext.firstItemExample) {
+        exampleUriSuffix = buildComponentMapUriSuffix(hintContext.firstItemExample);
+      }
       break;
     case 'componentName':
       // Listing component names (e.g., MySchema, User) at openapi://components/{type}
@@ -64,6 +69,12 @@ export function generateListHint(renderContext: RenderContext, hintContext: Hint
         '{name}'
       );
       itemTypeName = hintContext.parentComponentType.slice(0, -1); // e.g., 'schema' from 'schemas'
+      if (hintContext.firstItemExample) {
+        exampleUriSuffix = buildComponentDetailUriSuffix(
+          hintContext.parentComponentType,
+          hintContext.firstItemExample
+        );
+      }
       break;
     case 'pathMethod':
       // Listing methods (e.g., get, post) at openapi://paths/{path}
@@ -75,6 +86,13 @@ export function generateListHint(renderContext: RenderContext, hintContext: Hint
       // Use the actual parent path and a placeholder for the method
       detailUriSuffixPattern = buildOperationUriSuffix(hintContext.parentPath, '{method}');
       itemTypeName = 'operation'; // Or 'method'? 'operation' seems clearer
+      if (hintContext.firstItemExample) {
+        // Ensure the example method is valid if needed, though usually it's just 'get', 'post' etc.
+        exampleUriSuffix = buildOperationUriSuffix(
+          hintContext.parentPath,
+          hintContext.firstItemExample
+        );
+      }
       break;
     default:
       // Explicitly cast to string to avoid potential 'never' type issue in template literal
@@ -84,8 +102,16 @@ export function generateListHint(renderContext: RenderContext, hintContext: Hint
 
   // Construct the full hint URI pattern using the base URI
   const fullHintPattern = `${renderContext.baseUri}${detailUriSuffixPattern}`;
+  const fullExampleUri = exampleUriSuffix
+    ? `${renderContext.baseUri}${exampleUriSuffix}`
+    : undefined;
+
+  let hintText = `\nHint: Use '${fullHintPattern}' to view details for a specific ${itemTypeName}.`;
+  if (fullExampleUri) {
+    hintText += ` (e.g., ${fullExampleUri})`;
+  }
 
-  return `\nHint: Use '${fullHintPattern}' to view details for a specific ${itemTypeName}.`;
+  return hintText;
 }
 
 /**

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

package/test/__tests__/unit/rendering/components.test.ts

@@ -40,13 +40,18 @@ describe('RenderableComponents (List Types)', () => {
     expect(result[0].renderAsList).toBe(true);
     expect(result[0].isError).toBeUndefined();
     expect(result[0].data).toContain('Available Component Types:');
-    // Check sorted types
-    expect(result[0].data).toMatch(/-\s+examples\n/); // Empty but present
-    expect(result[0].data).toMatch(/-\s+parameters\n/);
-    expect(result[0].data).toMatch(/-\s+responses\n/);
-    expect(result[0].data).toMatch(/-\s+schemas\n/);
+    // Check sorted types with descriptions
+    expect(result[0].data).toMatch(/-\s+examples: Reusable examples of media type payloads\n/);
+    expect(result[0].data).toMatch(
+      /-\s+parameters: Reusable request parameters \(query, path, header, cookie\)\n/
+    );
+    expect(result[0].data).toMatch(/-\s+responses: Reusable API responses\n/);
+    expect(result[0].data).toMatch(/-\s+schemas: Reusable data structures \(models\)\n/);
     expect(result[0].data).not.toContain('- securitySchemes'); // Missing type
-    expect(result[0].data).toContain("Hint: Use 'openapi://components/{type}'");
+    // Check hint with example
+    expect(result[0].data).toContain(
+      "Hint: Use 'openapi://components/{type}' to view details for a specific component type. (e.g., openapi://components/examples)"
+    );
   });
 
   it('should handle empty components object', () => {
@@ -121,7 +126,10 @@ describe('RenderableComponentMap (List/Detail Names)', () => {
       expect(result[0].data).toContain('Available schemas:');
       expect(result[0].data).toMatch(/-\s+Error\n/); // Sorted
       expect(result[0].data).toMatch(/-\s+User\n/);
-      expect(result[0].data).toContain("Hint: Use 'openapi://components/schemas/{name}'");
+      // Check hint with example
+      expect(result[0].data).toContain(
+        "Hint: Use 'openapi://components/schemas/{name}' to view details for a specific schema. (e.g., openapi://components/schemas/Error)"
+      );
     });
 
     it('should list component names correctly (parameters)', () => {
@@ -131,7 +139,10 @@ describe('RenderableComponentMap (List/Detail Names)', () => {
       expect(result[0].uriSuffix).toBe(paramsUriSuffix);
       expect(result[0].data).toContain('Available parameters:');
       expect(result[0].data).toMatch(/-\s+userIdParam\n/);
-      expect(result[0].data).toContain("Hint: Use 'openapi://components/parameters/{name}'");
+      // Check hint with example
+      expect(result[0].data).toContain(
+        "Hint: Use 'openapi://components/parameters/{name}' to view details for a specific parameter. (e.g., openapi://components/parameters/userIdParam)"
+      );
     });
 
     it('should handle empty component map', () => {

package/test/__tests__/unit/rendering/path-item.test.ts

@@ -49,8 +49,9 @@ describe('RenderablePathItem', () => {
       // Define expected output lines based on the new format and builder logic
       // generateListHint uses buildOperationUriSuffix which encodes the path
       // Since rawPath is '/items', encoded is 'items'.
+      // The first sorted method is 'delete'.
       const expectedHint =
-        "Hint: Use 'openapi://paths/items/{method}' to view details for a specific operation.";
+        "Hint: Use 'openapi://paths/items/{method}' to view details for a specific operation. (e.g., openapi://paths/items/delete)";
       const expectedLineDelete = 'DELETE'; // No summary/opId
       const expectedLineGet = 'GET: Get Item'; // Summary exists
       const expectedLinePost = 'POST: Create Item'; // Summary exists