Create mcpcat.md

Merge pull request #39 from harsha-iiiv/copilot/fix-33b9d782-1c7b-44d1-89a9-adbd77a32aa8
Upgrade package to version 3.2.0 and address code quality improvements based on review feedback
2025-09-30 12:15:47 -07:00 · 2025-08-24 22:03:57 -07:00 · 2025-08-25 04:59:26 +00:00 · 2025-08-25 04:41:52 +00:00 · 2025-08-24 23:14:41 +00:00 · 2025-08-24 23:09:33 +00:00
12 changed files with 484 additions and 201 deletions
--- a/.github/PULL_REQUEST_TEMPLATE/mcpcat.md
+++ b/.github/PULL_REQUEST_TEMPLATE/mcpcat.md
@ -0,0 +1,44 @@
+# Add optional MCPcat analytics scaffolding (`--with-mcpcat`) to generated MCP servers
+
+> **TL;DR**: This PR adds an **opt-in** flag to scaffold privacy-safe analytics wiring for MCPcat in projects generated by `openapi-mcp-generator`.
+
+## Summary
+This PR introduces a `--with-mcpcat` CLI flag that scaffolds:
+- A tiny analytics shim to emit initialize/tool-call events.
+- A default **local redaction** helper to scrub sensitive data before export.
+- Minimal config via environment variables.
+No behavior changes unless the flag and env vars are set.
+
+## Motivation
+- Make freshly generated MCP servers **observable in minutes**.
+- Encourage **privacy-by-default** analytics patterns.
+- Reduce copy/paste wiring; standardize event shape (operationId, path, duration, status).
+
+## Changes
+### CLI
+- `generate` accepts `--with-mcpcat` (default: off).
+
+### Template files (added conditionally)
+- `src/analytics/mcpcat.ts` – lazy import + safe no-op if SDK absent.
+- `src/analytics/redact.ts` – OpenAPI-aware heuristics (e.g., `*token*`, `password`, `apiKey`, `authorization`, `email`).
+- `src/analytics/config.ts` – reads env:
+  - `MCPCAT_ENABLED=true|false` (default `false`)
+  - `MCPCAT_PROJECT_ID=<id>`
+  - `MCPCAT_ENDPOINT=<optional override>`
+  - `MCPCAT_SAMPLE_RATE=1.0` (0–1)
+
+### Server wiring
+- Hooks server `.initialize` and each tool invocation to record:
+  - `operationId`, HTTP `method`, `path`
+  - redacted `args`
+  - `outcome` (`ok`/`error`) + truncated error message
+  - `duration_ms`
+
+### Docs
+- Adds a “Enable analytics (MCPcat)” section to generated README with privacy notes and quickstart.
+
+## Implementation Notes
+- **Compile-time optional**: no imports unless flag is used.
+- **Runtime safe**: try/catch around SDK import → graceful no-op if not installed.
+- **Transport-agnostic**: compatible with stdio, SSE/web, and StreamableHTTP templates.
+- **Edge-friendly**: avoids Node-only APIs in scaffolding to support edge runtimes (e.g., Workers).
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [3.2.0] - 2025-08-24
+
+### Added
+
+- Endpoint filtering using `x-mcp` OpenAPI extension to control which operations are exposed as MCP tools
+- CLI option `--default-include` to change default behavior for endpoint inclusion
+- Precedence rules for `x-mcp` extension (operation > path > root level)
+- Enhanced programmatic API with `defaultInclude` option in `getToolsFromOpenApi`
+
+### Changed
+
+- Improved documentation with examples for endpoint filtering and OpenAPI extensions.
+- Version bump to next minor release
+- Updated package version to reflect accumulated features and improvements
+
+## [3.1.4] - 2025-06-18
+
+### Chores
+
+- Updated the application version to 3.1.4 and ensured the CLI displays the version dynamically.
+
+### Style
+
+- Improved code formatting for better readability.
+
+### Bug Fixes
+
+- Tool names now retain their original casing during extraction.
+
+## [3.1.3] - 2025-06-12
+
+### Fixed
+
+- Cannot find the package after building and the problem during the building.
+
 ## [3.1.2] - 2025-06-08

 ### Fixed
--- a/PROGRAMMATIC_API.md
+++ b/PROGRAMMATIC_API.md
@ -22,7 +22,7 @@ This function extracts an array of tools from an OpenAPI specification.

 **Parameters:**

- `specPathOrUrl`: Path to a local OpenAPI spec file, URL to a remote spec, or a pre-parsed OpenAPIV3.Document
+- `specPathOrUrl`: Path to a local OpenAPI spec file or URL to a remote spec
 - `options`: (Optional) Configuration options

 **Options:**
@ -62,15 +62,18 @@ for (const tool of filteredTools) {
  console.log(`  Method: ${tool.method.toUpperCase()} ${tool.pathTemplate}`);
  console.log(`  OperationId: ${tool.operationId}`);
 }
+```

-// Using a pre-parsed OpenAPI document (helpful when @apidevtools/swagger-parser fails)
-import { parse } from '@readme/openapi-parser';
-import { OpenAPIV3 } from 'openapi-types';
+you can also provide a `OpenAPIV3.Document` to the parser:

-const api = await parse<OpenAPIV3.Document>(
-  'https://problematic-api-spec.com/openapi.json',
-  { dereference: { circular: true } }
-);
+```typescript
+import { parser } from '@readme/openapi-parser';
+
+const api = await parser('https://petstore3.swagger.io/api/v3/openapi.json', {
+  dereference: {
+    circular: true,
+  },
+});

 const tools = await getToolsFromOpenApi(api);
 ```
--- a/README.md
+++ b/README.md
@ -48,16 +48,17 @@ openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir -

 ### CLI Options

-| Option             | Alias | Description                                                                    | Default                           |
-| ------------------ | ----- | ------------------------------------------------------------------------------ | --------------------------------- |
-| `--input`          | `-i`  | Path or URL to OpenAPI specification (YAML or JSON)                            | **Required**                      |
-| `--output`         | `-o`  | Directory to output the generated MCP project                                  | **Required**                      |
-| `--server-name`    | `-n`  | Name of the MCP server (`package.json:name`)                                   | OpenAPI title or `mcp-api-server` |
-| `--server-version` | `-v`  | Version of the MCP server (`package.json:version`)                             | OpenAPI version or `1.0.0`        |
-| `--base-url`       | `-b`  | Base URL for API requests. Required if OpenAPI `servers` missing or ambiguous. | Auto-detected if possible         |
-| `--transport`      | `-t`  | Transport mode: `"stdio"` (default), `"web"`, or `"streamable-http"`           | `"stdio"`                         |
-| `--port`           | `-p`  | Port for web-based transports                                                  | `3000`                            |
-| `--force`          |       | Overwrite existing files in the output directory without confirmation          | `false`                           |
+| Option              | Alias | Description                                                                                                                                    | Default                           |
+| ------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `--input`           | `-i`  | Path or URL to OpenAPI specification (YAML or JSON)                                                                                            | **Required**                      |
+| `--output`          | `-o`  | Directory to output the generated MCP project                                                                                                  | **Required**                      |
+| `--server-name`     | `-n`  | Name of the MCP server (`package.json:name`)                                                                                                   | OpenAPI title or `mcp-api-server` |
+| `--server-version`  | `-v`  | Version of the MCP server (`package.json:version`)                                                                                             | OpenAPI version or `1.0.0`        |
+| `--base-url`        | `-b`  | Base URL for API requests. Required if OpenAPI `servers` missing or ambiguous.                                                                 | Auto-detected if possible         |
+| `--transport`       | `-t`  | Transport mode: `"stdio"` (default), `"web"`, or `"streamable-http"`                                                                           | `"stdio"`                         |
+| `--port`            | `-p`  | Port for web-based transports                                                                                                                  | `3000`                            |
+| `--default-include` |       | Default behavior for x-mcp filtering. Accepts `true` or `false` (case-insensitive). `true` = include by default, `false` = exclude by default. | `true`                            |
+| `--force`           |       | Overwrite existing files in the output directory without confirmation                                                                          | `false`                           |

 ## 📦 Programmatic API

@ -167,6 +168,38 @@ Configure auth credentials in your environment:

 ---

+## 🔎 Filtering Endpoints with OpenAPI Extensions
+
+You can control which operations are exposed as MCP tools using a vendor extension flag `x-mcp`. This extension is supported at the root, path, and operation levels. By default, endpoints are included unless explicitly excluded.
+
+- Extension: `x-mcp: true | false`
+- Default: `true` (include by default)
+- Precedence: operation > path > root (first non-undefined wins)
+- CLI option: `--default-include false` to change default to exclude by default
+
+Examples:
+
+```yaml
+# Optional root-level default
+x-mcp: true
+
+paths:
+  /pets:
+    x-mcp: false # exclude all ops under /pets
+    get:
+      x-mcp: true # include this operation anyway
+
+  /users/{id}:
+    get:
+      # no x-mcp -> included by default
+```
+
+This uses standard OpenAPI extensions (x-… fields). See the [OpenAPI Extensions guide](https://swagger.io/docs/specification/v3_0/openapi-extensions/) for details.
+
+Note: `x-mcp` must be a boolean or the strings `"true"`/`"false"` (case-insensitive). Other values are ignored in favor of higher-precedence or default behavior.
+
+---
+
 ## ▶️ Running the Generated Server

 ```bash
--- a/package-lock.json
+++ b/package-lock.json
@ -1,12 +1,12 @@
 {
  "name": "openapi-mcp-generator",
-  "version": "3.1.4",
+  "version": "3.2.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "openapi-mcp-generator",
-      "version": "3.1.4",
+      "version": "3.2.0",
      "license": "MIT",
      "dependencies": {
        "@apidevtools/swagger-parser": "^10.1.1",
@ -17,19 +17,19 @@
        "openapi-mcp-generator": "bin/openapi-mcp-generator.js"
      },
      "devDependencies": {
-        "@types/node": "^22.15.2",
-        "@typescript-eslint/eslint-plugin": "^8.31.0",
-        "@typescript-eslint/parser": "^8.31.0",
-        "eslint": "^9.25.1",
-        "prettier": "^3.5.3",
+        "@types/node": "^22.17.2",
+        "@typescript-eslint/eslint-plugin": "^8.39.1",
+        "@typescript-eslint/parser": "^8.39.1",
+        "eslint": "^9.33.0",
+        "prettier": "^3.6.2",
        "rimraf": "^6.0.1",
-        "typescript": "^5.8.3"
+        "typescript": "^5.9.2"
      },
      "engines": {
        "node": ">=20.0.0"
      },
      "peerDependencies": {
-        "@modelcontextprotocol/sdk": "^1.10.0",
+        "@modelcontextprotocol/sdk": "^1.10.2",
        "json-schema-to-zod": "^2.6.1",
        "zod": "^3.24.3"
      }
@ -85,9 +85,9 @@
      }
    },
    "node_modules/@eslint-community/eslint-utils": {
-      "version": "4.6.0",
-      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.6.0.tgz",
-      "integrity": "sha512-WhCn7Z7TauhBtmzhvKpoQs0Wwb/kBcy4CwpuI0/eEIr2Lx2auxmulAzLr91wVZJaz47iUZdkXOK7WlAfxGKCnA==",
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.7.0.tgz",
+      "integrity": "sha512-dyybb3AcajC7uha6CvhdVRJqaKyn7w2YKqKyAN37NKYgZT36w+iRb0Dymmc5qEJ549c/S31cMMSFd75bteCpCw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@ -114,9 +114,9 @@
      }
    },
    "node_modules/@eslint/config-array": {
-      "version": "0.20.0",
-      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.20.0.tgz",
-      "integrity": "sha512-fxlS1kkIjx8+vy2SjuCB94q3htSNrufYTXubwiBFeaQHbH6Ipi43gFJq2zCMt6PHhImH3Xmr0NksKDvchWlpQQ==",
+      "version": "0.21.0",
+      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.21.0.tgz",
+      "integrity": "sha512-ENIdc4iLu0d93HeYirvKmrzshzofPw6VkZRKQGe9Nv46ZnWUzcF1xV01dcvEg/1wXUR61OmmlSfyeyO7EvjLxQ==",
      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
@ -129,9 +129,9 @@
      }
    },
    "node_modules/@eslint/config-array/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@ -153,9 +153,9 @@
      }
    },
    "node_modules/@eslint/config-helpers": {
-      "version": "0.2.1",
-      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.2.1.tgz",
-      "integrity": "sha512-RI17tsD2frtDu/3dmI7QRrD4bedNKPM08ziRYaC5AhkGrzIAJelm9kJU1TznK+apx6V+cqRz8tfpEeG3oIyjxw==",
+      "version": "0.3.1",
+      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.3.1.tgz",
+      "integrity": "sha512-xR93k9WhrDYpXHORXpxVL5oHj3Era7wo6k/Wd8/IsQNnZUTzkGS29lyn3nAT05v6ltUuTFVCCYDEGfy2Or/sPA==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@ -163,9 +163,9 @@
      }
    },
    "node_modules/@eslint/core": {
-      "version": "0.13.0",
-      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.13.0.tgz",
-      "integrity": "sha512-yfkgDw1KR66rkT5A8ci4irzDysN7FRpq3ttJolR88OqQikAWqwA8j5VZyas+vjyBNFIJ7MfybJ9plMILI2UrCw==",
+      "version": "0.15.2",
+      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.15.2.tgz",
+      "integrity": "sha512-78Md3/Rrxh83gCxoUc0EiciuOHsIITzLy53m3d9UyiW8y9Dj2D29FeETqyKA+BRK76tnTp6RXWb3pCay8Oyomg==",
      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
@ -217,9 +217,9 @@
      }
    },
    "node_modules/@eslint/eslintrc/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@ -227,6 +227,16 @@
        "concat-map": "0.0.1"
      }
    },
+    "node_modules/@eslint/eslintrc/node_modules/ignore": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
+      "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 4"
+      }
+    },
    "node_modules/@eslint/eslintrc/node_modules/json-schema-traverse": {
      "version": "0.4.1",
      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
@ -248,13 +258,16 @@
      }
    },
    "node_modules/@eslint/js": {
-      "version": "9.25.1",
-      "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.25.1.tgz",
-      "integrity": "sha512-dEIwmjntEx8u3Uvv+kr3PDeeArL8Hw07H9kyYxCjnM9pBjfEhk6uLXSchxxzgiwtRhhzVzqmUSDFBOi1TuZ7qg==",
+      "version": "9.33.0",
+      "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.33.0.tgz",
+      "integrity": "sha512-5K1/mKhWaMfreBGJTwval43JJmkip0RmM+3+IuqupeSKNC/Th2Kc7ucaq5ovTSra/OOKB9c58CGSz3QMVbWt0A==",
      "dev": true,
      "license": "MIT",
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://eslint.org/donate"
      }
    },
    "node_modules/@eslint/object-schema": {
@ -268,13 +281,13 @@
      }
    },
    "node_modules/@eslint/plugin-kit": {
-      "version": "0.2.8",
-      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.2.8.tgz",
-      "integrity": "sha512-ZAoA40rNMPwSm+AeHpCq8STiNAwzWLJuP8Xv4CHIc9wv/PSuExjMrmjfYNj682vW0OOiZ1HKxzvjQr9XZIisQA==",
+      "version": "0.3.5",
+      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.3.5.tgz",
+      "integrity": "sha512-Z5kJ+wU3oA7MMIqVR9tyZRtjYPr4OC004Q4Rw7pgOKUOKkJfZ3O24nz3WYfGRpMDNmcOi3TwQOmgm7B7Tpii0w==",
      "dev": true,
      "license": "Apache-2.0",
      "dependencies": {
-        "@eslint/core": "^0.13.0",
+        "@eslint/core": "^0.15.2",
        "levn": "^0.4.1"
      },
      "engines": {
@ -334,9 +347,9 @@
      }
    },
    "node_modules/@humanwhocodes/retry": {
-      "version": "0.4.2",
-      "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.2.tgz",
-      "integrity": "sha512-xeO57FpIu4p1Ri3Jq/EXq4ClRm86dVF2z/+kvFnyqVYRavTZmaFaUBbWCOuuTh0o/g7DSsk6kc2vrS4Vl5oPOQ==",
+      "version": "0.4.3",
+      "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.3.tgz",
+      "integrity": "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@ -432,9 +445,9 @@
      }
    },
    "node_modules/@types/estree": {
-      "version": "1.0.7",
-      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.7.tgz",
-      "integrity": "sha512-w28IoSUCJpidD/TGviZwwMJckNESJZXFu7NBZ5YJ4mEUnNraUn9Pm8HSZm/jDF1pDWYKspWE7oVphigUPRakIQ==",
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
      "dev": true,
      "license": "MIT"
    },
@ -445,9 +458,9 @@
      "license": "MIT"
    },
    "node_modules/@types/node": {
-      "version": "22.15.2",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.15.2.tgz",
-      "integrity": "sha512-uKXqKN9beGoMdBfcaTY1ecwz6ctxuJAcUlwE55938g0ZJ8lRxwAZqRz2AJ4pzpt5dHdTPMB863UZ0ESiFUcP7A==",
+      "version": "22.17.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.17.2.tgz",
+      "integrity": "sha512-gL6z5N9Jm9mhY+U2KXZpteb+09zyffliRkZyZOHODGATyC5B1Jt/7TzuuiLkFsSUMLbS1OLmlj/E+/3KF4Q/4w==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@ -455,21 +468,21 @@
      }
    },
    "node_modules/@typescript-eslint/eslint-plugin": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.31.0.tgz",
-      "integrity": "sha512-evaQJZ/J/S4wisevDvC1KFZkPzRetH8kYZbkgcTRyql3mcKsf+ZFDV1BVWUGTCAW5pQHoqn5gK5b8kn7ou9aFQ==",
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.39.1.tgz",
+      "integrity": "sha512-yYegZ5n3Yr6eOcqgj2nJH8cH/ZZgF+l0YIdKILSDjYFRjgYQMgv/lRjV5Z7Up04b9VYUondt8EPMqg7kTWgJ2g==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "@eslint-community/regexpp": "^4.10.0",
-        "@typescript-eslint/scope-manager": "8.31.0",
-        "@typescript-eslint/type-utils": "8.31.0",
-        "@typescript-eslint/utils": "8.31.0",
-        "@typescript-eslint/visitor-keys": "8.31.0",
+        "@typescript-eslint/scope-manager": "8.39.1",
+        "@typescript-eslint/type-utils": "8.39.1",
+        "@typescript-eslint/utils": "8.39.1",
+        "@typescript-eslint/visitor-keys": "8.39.1",
        "graphemer": "^1.4.0",
-        "ignore": "^5.3.1",
+        "ignore": "^7.0.0",
        "natural-compare": "^1.4.0",
-        "ts-api-utils": "^2.0.1"
+        "ts-api-utils": "^2.1.0"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@ -479,22 +492,22 @@
        "url": "https://opencollective.com/typescript-eslint"
      },
      "peerDependencies": {
-        "@typescript-eslint/parser": "^8.0.0 || ^8.0.0-alpha.0",
+        "@typescript-eslint/parser": "^8.39.1",
        "eslint": "^8.57.0 || ^9.0.0",
-        "typescript": ">=4.8.4 <5.9.0"
+        "typescript": ">=4.8.4 <6.0.0"
      }
    },
    "node_modules/@typescript-eslint/parser": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.31.0.tgz",
-      "integrity": "sha512-67kYYShjBR0jNI5vsf/c3WG4u+zDnCTHTPqVMQguffaWWFs7artgwKmfwdifl+r6XyM5LYLas/dInj2T0SgJyw==",
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.39.1.tgz",
+      "integrity": "sha512-pUXGCuHnnKw6PyYq93lLRiZm3vjuslIy7tus1lIQTYVK9bL8XBgJnCWm8a0KcTtHC84Yya1Q6rtll+duSMj0dg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@typescript-eslint/scope-manager": "8.31.0",
-        "@typescript-eslint/types": "8.31.0",
-        "@typescript-eslint/typescript-estree": "8.31.0",
-        "@typescript-eslint/visitor-keys": "8.31.0",
+        "@typescript-eslint/scope-manager": "8.39.1",
+        "@typescript-eslint/types": "8.39.1",
+        "@typescript-eslint/typescript-estree": "8.39.1",
+        "@typescript-eslint/visitor-keys": "8.39.1",
        "debug": "^4.3.4"
      },
      "engines": {
@ -506,18 +519,40 @@
      },
      "peerDependencies": {
        "eslint": "^8.57.0 || ^9.0.0",
-        "typescript": ">=4.8.4 <5.9.0"
+        "typescript": ">=4.8.4 <6.0.0"
      }
    },
-    "node_modules/@typescript-eslint/scope-manager": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.31.0.tgz",
-      "integrity": "sha512-knO8UyF78Nt8O/B64i7TlGXod69ko7z6vJD9uhSlm0qkAbGeRUSudcm0+K/4CrRjrpiHfBCjMWlc08Vav1xwcw==",
+    "node_modules/@typescript-eslint/project-service": {
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.39.1.tgz",
+      "integrity": "sha512-8fZxek3ONTwBu9ptw5nCKqZOSkXshZB7uAxuFF0J/wTMkKydjXCzqqga7MlFMpHi9DoG4BadhmTkITBcg8Aybw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@typescript-eslint/types": "8.31.0",
-        "@typescript-eslint/visitor-keys": "8.31.0"
+        "@typescript-eslint/tsconfig-utils": "^8.39.1",
+        "@typescript-eslint/types": "^8.39.1",
+        "debug": "^4.3.4"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "typescript": ">=4.8.4 <6.0.0"
+      }
+    },
+    "node_modules/@typescript-eslint/scope-manager": {
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.39.1.tgz",
+      "integrity": "sha512-RkBKGBrjgskFGWuyUGz/EtD8AF/GW49S21J8dvMzpJitOF1slLEbbHnNEtAHtnDAnx8qDEdRrULRnWVx27wGBw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@typescript-eslint/types": "8.39.1",
+        "@typescript-eslint/visitor-keys": "8.39.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@ -527,17 +562,35 @@
        "url": "https://opencollective.com/typescript-eslint"
      }
    },
+    "node_modules/@typescript-eslint/tsconfig-utils": {
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.39.1.tgz",
+      "integrity": "sha512-ePUPGVtTMR8XMU2Hee8kD0Pu4NDE1CN9Q1sxGSGd/mbOtGZDM7pnhXNJnzW63zk/q+Z54zVzj44HtwXln5CvHA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      },
+      "peerDependencies": {
+        "typescript": ">=4.8.4 <6.0.0"
+      }
+    },
    "node_modules/@typescript-eslint/type-utils": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.31.0.tgz",
-      "integrity": "sha512-DJ1N1GdjI7IS7uRlzJuEDCgDQix3ZVYVtgeWEyhyn4iaoitpMBX6Ndd488mXSx0xah/cONAkEaYyylDyAeHMHg==",
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.39.1.tgz",
+      "integrity": "sha512-gu9/ahyatyAdQbKeHnhT4R+y3YLtqqHyvkfDxaBYk97EcbfChSJXyaJnIL3ygUv7OuZatePHmQvuH5ru0lnVeA==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@typescript-eslint/typescript-estree": "8.31.0",
-        "@typescript-eslint/utils": "8.31.0",
+        "@typescript-eslint/types": "8.39.1",
+        "@typescript-eslint/typescript-estree": "8.39.1",
+        "@typescript-eslint/utils": "8.39.1",
        "debug": "^4.3.4",
-        "ts-api-utils": "^2.0.1"
+        "ts-api-utils": "^2.1.0"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@ -548,13 +601,13 @@
      },
      "peerDependencies": {
        "eslint": "^8.57.0 || ^9.0.0",
-        "typescript": ">=4.8.4 <5.9.0"
+        "typescript": ">=4.8.4 <6.0.0"
      }
    },
    "node_modules/@typescript-eslint/types": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.31.0.tgz",
-      "integrity": "sha512-Ch8oSjVyYyJxPQk8pMiP2FFGYatqXQfQIaMp+TpuuLlDachRWpUAeEu1u9B/v/8LToehUIWyiKcA/w5hUFRKuQ==",
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.39.1.tgz",
+      "integrity": "sha512-7sPDKQQp+S11laqTrhHqeAbsCfMkwJMrV7oTDvtDds4mEofJYir414bYKUEb8YPUm9QL3U+8f6L6YExSoAGdQw==",
      "dev": true,
      "license": "MIT",
      "engines": {
@ -566,20 +619,22 @@
      }
    },
    "node_modules/@typescript-eslint/typescript-estree": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.31.0.tgz",
-      "integrity": "sha512-xLmgn4Yl46xi6aDSZ9KkyfhhtnYI15/CvHbpOy/eR5NWhK/BK8wc709KKwhAR0m4ZKRP7h07bm4BWUYOCuRpQQ==",
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.39.1.tgz",
+      "integrity": "sha512-EKkpcPuIux48dddVDXyQBlKdeTPMmALqBUbEk38McWv0qVEZwOpVJBi7ugK5qVNgeuYjGNQxrrnoM/5+TI/BPw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@typescript-eslint/types": "8.31.0",
-        "@typescript-eslint/visitor-keys": "8.31.0",
+        "@typescript-eslint/project-service": "8.39.1",
+        "@typescript-eslint/tsconfig-utils": "8.39.1",
+        "@typescript-eslint/types": "8.39.1",
+        "@typescript-eslint/visitor-keys": "8.39.1",
        "debug": "^4.3.4",
        "fast-glob": "^3.3.2",
        "is-glob": "^4.0.3",
        "minimatch": "^9.0.4",
        "semver": "^7.6.0",
-        "ts-api-utils": "^2.0.1"
+        "ts-api-utils": "^2.1.0"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@ -589,20 +644,20 @@
        "url": "https://opencollective.com/typescript-eslint"
      },
      "peerDependencies": {
-        "typescript": ">=4.8.4 <5.9.0"
+        "typescript": ">=4.8.4 <6.0.0"
      }
    },
    "node_modules/@typescript-eslint/utils": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.31.0.tgz",
-      "integrity": "sha512-qi6uPLt9cjTFxAb1zGNgTob4x9ur7xC6mHQJ8GwEzGMGE9tYniublmJaowOJ9V2jUzxrltTPfdG2nKlWsq0+Ww==",
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.39.1.tgz",
+      "integrity": "sha512-VF5tZ2XnUSTuiqZFXCZfZs1cgkdd3O/sSYmdo2EpSyDlC86UM/8YytTmKnehOW3TGAlivqTDT6bS87B/GQ/jyg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@eslint-community/eslint-utils": "^4.4.0",
-        "@typescript-eslint/scope-manager": "8.31.0",
-        "@typescript-eslint/types": "8.31.0",
-        "@typescript-eslint/typescript-estree": "8.31.0"
+        "@eslint-community/eslint-utils": "^4.7.0",
+        "@typescript-eslint/scope-manager": "8.39.1",
+        "@typescript-eslint/types": "8.39.1",
+        "@typescript-eslint/typescript-estree": "8.39.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@ -613,18 +668,18 @@
      },
      "peerDependencies": {
        "eslint": "^8.57.0 || ^9.0.0",
-        "typescript": ">=4.8.4 <5.9.0"
+        "typescript": ">=4.8.4 <6.0.0"
      }
    },
    "node_modules/@typescript-eslint/visitor-keys": {
-      "version": "8.31.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.31.0.tgz",
-      "integrity": "sha512-QcGHmlRHWOl93o64ZUMNewCdwKGU6WItOU52H0djgNmn1EOrhVudrDzXz4OycCRSCPwFCDrE2iIt5vmuUdHxuQ==",
+      "version": "8.39.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.39.1.tgz",
+      "integrity": "sha512-W8FQi6kEh2e8zVhQ0eeRnxdvIoOkAp/CPAahcNio6nO9dsIwb9b34z90KOlheoyuVf6LSOEdjlkxSkapNEc+4A==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@typescript-eslint/types": "8.31.0",
-        "eslint-visitor-keys": "^4.2.0"
+        "@typescript-eslint/types": "8.39.1",
+        "eslint-visitor-keys": "^4.2.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@ -635,9 +690,9 @@
      }
    },
    "node_modules/@typescript-eslint/visitor-keys/node_modules/eslint-visitor-keys": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz",
-      "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
+      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@ -662,9 +717,9 @@
      }
    },
    "node_modules/acorn": {
-      "version": "8.14.1",
-      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.1.tgz",
-      "integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==",
+      "version": "8.15.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
+      "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
      "dev": true,
      "license": "MIT",
      "bin": {
@ -1115,20 +1170,20 @@
      }
    },
    "node_modules/eslint": {
-      "version": "9.25.1",
-      "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.25.1.tgz",
-      "integrity": "sha512-E6Mtz9oGQWDCpV12319d59n4tx9zOTXSTmc8BLVxBx+G/0RdM5MvEEJLU9c0+aleoePYYgVTOsRblx433qmhWQ==",
+      "version": "9.33.0",
+      "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.33.0.tgz",
+      "integrity": "sha512-TS9bTNIryDzStCpJN93aC5VRSW3uTx9sClUn4B87pwiCaJh220otoI0X8mJKr+VcPtniMdN8GKjlwgWGUv5ZKA==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "@eslint-community/eslint-utils": "^4.2.0",
        "@eslint-community/regexpp": "^4.12.1",
-        "@eslint/config-array": "^0.20.0",
-        "@eslint/config-helpers": "^0.2.1",
-        "@eslint/core": "^0.13.0",
+        "@eslint/config-array": "^0.21.0",
+        "@eslint/config-helpers": "^0.3.1",
+        "@eslint/core": "^0.15.2",
        "@eslint/eslintrc": "^3.3.1",
-        "@eslint/js": "9.25.1",
-        "@eslint/plugin-kit": "^0.2.8",
+        "@eslint/js": "9.33.0",
+        "@eslint/plugin-kit": "^0.3.5",
        "@humanfs/node": "^0.16.6",
        "@humanwhocodes/module-importer": "^1.0.1",
        "@humanwhocodes/retry": "^0.4.2",
@ -1139,9 +1194,9 @@
        "cross-spawn": "^7.0.6",
        "debug": "^4.3.2",
        "escape-string-regexp": "^4.0.0",
-        "eslint-scope": "^8.3.0",
-        "eslint-visitor-keys": "^4.2.0",
-        "espree": "^10.3.0",
+        "eslint-scope": "^8.4.0",
+        "eslint-visitor-keys": "^4.2.1",
+        "espree": "^10.4.0",
        "esquery": "^1.5.0",
        "esutils": "^2.0.2",
        "fast-deep-equal": "^3.1.3",
@ -1176,9 +1231,9 @@
      }
    },
    "node_modules/eslint-scope": {
-      "version": "8.3.0",
-      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.3.0.tgz",
-      "integrity": "sha512-pUNxi75F8MJ/GdeKtVLSbYg4ZI34J6C0C7sbL4YOp2exGwen7ZsuBqKzUhXd0qMQ362yET3z+uPwKeg/0C2XCQ==",
+      "version": "8.4.0",
+      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.4.0.tgz",
+      "integrity": "sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==",
      "dev": true,
      "license": "BSD-2-Clause",
      "dependencies": {
@ -1223,9 +1278,9 @@
      }
    },
    "node_modules/eslint/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@ -1234,9 +1289,9 @@
      }
    },
    "node_modules/eslint/node_modules/eslint-visitor-keys": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz",
-      "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
+      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@ -1246,6 +1301,16 @@
        "url": "https://opencollective.com/eslint"
      }
    },
+    "node_modules/eslint/node_modules/ignore": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
+      "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 4"
+      }
+    },
    "node_modules/eslint/node_modules/json-schema-traverse": {
      "version": "0.4.1",
      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
@ -1267,15 +1332,15 @@
      }
    },
    "node_modules/espree": {
-      "version": "10.3.0",
-      "resolved": "https://registry.npmjs.org/espree/-/espree-10.3.0.tgz",
-      "integrity": "sha512-0QYC8b24HWY8zjRnDTL6RiHfDbAWn63qb4LMj1Z4b076A4une81+z03Kg7l7mn/48PUTqoLptSXez8oknU8Clg==",
+      "version": "10.4.0",
+      "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz",
+      "integrity": "sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==",
      "dev": true,
      "license": "BSD-2-Clause",
      "dependencies": {
-        "acorn": "^8.14.0",
+        "acorn": "^8.15.0",
        "acorn-jsx": "^5.3.2",
-        "eslint-visitor-keys": "^4.2.0"
+        "eslint-visitor-keys": "^4.2.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@ -1285,9 +1350,9 @@
      }
    },
    "node_modules/espree/node_modules/eslint-visitor-keys": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz",
-      "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
+      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
      "dev": true,
      "license": "Apache-2.0",
      "engines": {
@ -1832,9 +1897,9 @@
      }
    },
    "node_modules/ignore": {
-      "version": "5.3.2",
-      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
-      "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
+      "version": "7.0.5",
+      "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz",
+      "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==",
      "dev": true,
      "license": "MIT",
      "engines": {
@ -2397,9 +2462,9 @@
      }
    },
    "node_modules/prettier": {
-      "version": "3.5.3",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.5.3.tgz",
-      "integrity": "sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw==",
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
+      "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
      "dev": true,
      "license": "MIT",
      "bin": {
@ -2619,9 +2684,9 @@
      "peer": true
    },
    "node_modules/semver": {
-      "version": "7.7.1",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.1.tgz",
-      "integrity": "sha512-hlq8tAfn0m/61p4BVRcPzIGr6LKiMwo4VM6dGi6pt4qcRkmNzTcWq6eCEjEh+qXjkMDvPlOFFSGwQjoEa6gyMA==",
+      "version": "7.7.2",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
+      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
      "dev": true,
      "license": "ISC",
      "bin": {
@ -2992,9 +3057,9 @@
      }
    },
    "node_modules/typescript": {
-      "version": "5.8.3",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.3.tgz",
-      "integrity": "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==",
+      "version": "5.9.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.2.tgz",
+      "integrity": "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A==",
      "dev": true,
      "license": "Apache-2.0",
      "bin": {
--- a/package.json
+++ b/package.json
@ -1,6 +1,6 @@
 {
  "name": "openapi-mcp-generator",
-  "version": "3.1.4",
+  "version": "3.2.0",
  "description": "Generates MCP server code from OpenAPI specifications",
  "license": "MIT",
  "author": "Harsha",
@ -25,7 +25,7 @@
    "format.check": "prettier --check .",
    "format.write": "prettier --write .",
    "typecheck": "tsc --noEmit",
-    "build": "tsc && chmod 755 dist/index.js && chmod 755 bin/openapi-mcp-generator.js",
+    "build": "tsc && chmod 755 dist/index.js bin/openapi-mcp-generator.js",
    "version:patch": "npm version patch",
    "version:minor": "npm version minor",
    "version:major": "npm version major"
@ -53,16 +53,16 @@
    "openapi-types": "^12.1.3"
  },
  "devDependencies": {
-    "@types/node": "^22.15.2",
-    "@typescript-eslint/eslint-plugin": "^8.31.0",
-    "@typescript-eslint/parser": "^8.31.0",
-    "eslint": "^9.25.1",
-    "prettier": "^3.5.3",
+    "@types/node": "^22.17.2",
+    "@typescript-eslint/eslint-plugin": "^8.39.1",
+    "@typescript-eslint/parser": "^8.39.1",
+    "eslint": "^9.33.0",
+    "prettier": "^3.6.2",
    "rimraf": "^6.0.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.2"
  },
  "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.0",
+    "@modelcontextprotocol/sdk": "^1.10.2",
    "json-schema-to-zod": "^2.6.1",
    "zod": "^3.24.3"
  }
--- a/src/api.ts
+++ b/src/api.ts
@ -9,16 +9,6 @@ import { extractToolsFromApi } from './parser/extract-tools.js';
 import { McpToolDefinition } from './types/index.js';
 import { determineBaseUrl } from './utils/url.js';

-/**
- * Type guard to check if the input is an OpenAPI document
- *
- * @param spec Input that could be a string or OpenAPIV3.Document
- * @returns True if input is an OpenAPIV3.Document, false otherwise
- */
-function isOpenApiDocument(spec: string | OpenAPIV3.Document): spec is OpenAPIV3.Document {
-  return typeof spec === 'object' && spec !== null && 'openapi' in spec;
-}
-
 /**
 * Options for generating the MCP tools
 */
@ -34,12 +24,19 @@ export interface GetToolsOptions {

  /** Optional filter function to exclude tools based on custom criteria */
  filterFn?: (tool: McpToolDefinition) => boolean;
+
+  /** Default behavior for x-mcp filtering (default: true = include by default) */
+  defaultInclude?: boolean;
+}
+
+function isOpenApiDocument(spec: string | OpenAPIV3.Document): spec is OpenAPIV3.Document {
+  return typeof spec === 'object' && spec !== null && 'openapi' in spec;
 }

 /**
 * Get a list of tools from an OpenAPI specification
 *
- * @param specPathOrUrl Path or URL to the OpenAPI specification, or a pre-parsed OpenAPI document
+ * @param specPathOrUrl Path or URL to the OpenAPI specification
 * @param options Options for generating the tools
 * @returns Promise that resolves to an array of tool definitions
 */
@ -48,26 +45,15 @@ export async function getToolsFromOpenApi(
  options: GetToolsOptions = {}
 ): Promise<McpToolDefinition[]> {
  try {
-    // Parse the OpenAPI spec or use the provided document
-    let api: OpenAPIV3.Document;
-    
-    if (isOpenApiDocument(specPathOrUrl)) {
-      // Input is already a parsed OpenAPI document
-      api = specPathOrUrl;
-      
-      // If dereference option is requested, apply it to the document
-      if (options.dereference) {
-        api = (await SwaggerParser.dereference(api)) as OpenAPIV3.Document;
-      }
-    } else {
-      // Input is a string path or URL, parse it
-      api = options.dereference
+    // Parse the OpenAPI spec
+    const api = isOpenApiDocument(specPathOrUrl)
+      ? specPathOrUrl
+      : options.dereference
        ? ((await SwaggerParser.dereference(specPathOrUrl)) as OpenAPIV3.Document)
        : ((await SwaggerParser.parse(specPathOrUrl)) as OpenAPIV3.Document);
-    }

    // Extract tools from the API
-    const allTools = extractToolsFromApi(api);
+    const allTools = extractToolsFromApi(api, options.defaultInclude ?? true);

    // Add base URL to each tool
    const baseUrl = determineBaseUrl(api, options.baseUrl);
@ -94,7 +80,8 @@ export async function getToolsFromOpenApi(
  } catch (error) {
    // Provide more context for the error
    if (error instanceof Error) {
-      throw new Error(`Failed to extract tools from OpenAPI: ${error.message}`);
+      // Preserve original stack/context
+      throw new Error(`Failed to extract tools from OpenAPI: ${error.message}`, { cause: error });
    }
    throw error;
  }
--- a/src/generator/server-code.ts
+++ b/src/generator/server-code.ts
@ -25,7 +25,7 @@ export function generateMcpServerCode(
  serverVersion: string
 ): string {
  // Extract tools from API
-  const tools = extractToolsFromApi(api);
+  const tools = extractToolsFromApi(api, options.defaultInclude ?? true);

  // Determine base URL
  const determinedBaseUrl = determineBaseUrl(api, options.baseUrl);
--- a/src/index.ts
+++ b/src/index.ts
@ -30,6 +30,7 @@ import {

 // Import types
 import { CliOptions, TransportType } from './types/index.js';
+import { normalizeBoolean } from './utils/helpers.js';
 import pkg from '../package.json' with { type: 'json' };

 // Export programmatic API
@ -72,6 +73,19 @@ program
    'Port for web or streamable-http transport (default: 3000)',
    (val) => parseInt(val, 10)
  )
+  .option(
+    '--default-include <boolean>',
+    'Default behavior for x-mcp filtering (true|false, case-insensitive). Default: true (include by default), false = exclude by default',
+    (val) => {
+      const parsed = normalizeBoolean(val);
+      if (typeof parsed === 'boolean') return parsed;
+      console.warn(
+        `Invalid value for --default-include: "${val}". Expected true/false (case-insensitive). Using default: true.`
+      );
+      return true;
+    },
+    true
+  )
  .option('--force', 'Overwrite existing files without prompting')
  .version(pkg.version) // Match package.json version
  .action((options) => {
--- a/src/parser/extract-tools.ts
+++ b/src/parser/extract-tools.ts
@ -5,6 +5,7 @@ import { OpenAPIV3 } from 'openapi-types';
 import type { JSONSchema7, JSONSchema7TypeName } from 'json-schema';
 import { generateOperationId } from '../utils/code-gen.js';
 import { McpToolDefinition } from '../types/index.js';
+import { shouldIncludeOperationForMcp } from '../utils/helpers.js';

 /**
 * Extracts tool definitions from an OpenAPI document
@ -12,7 +13,10 @@ import { McpToolDefinition } from '../types/index.js';
 * @param api OpenAPI document
 * @returns Array of MCP tool definitions
 */
-export function extractToolsFromApi(api: OpenAPIV3.Document): McpToolDefinition[] {
+export function extractToolsFromApi(
+  api: OpenAPIV3.Document,
+  defaultInclude: boolean = true
+): McpToolDefinition[] {
  const tools: McpToolDefinition[] = [];
  const usedNames = new Set<string>();
  const globalSecurity = api.security || [];
@ -26,6 +30,37 @@ export function extractToolsFromApi(api: OpenAPIV3.Document): McpToolDefinition[
      const operation = pathItem[method];
      if (!operation) continue;

+      // Apply x-mcp filtering, precedence: operation > path > root
+      try {
+        if (
+          !shouldIncludeOperationForMcp(
+            api,
+            pathItem as OpenAPIV3.PathItemObject,
+            operation,
+            defaultInclude
+          )
+        ) {
+          continue;
+        }
+      } catch (error) {
+        const loc = operation.operationId || `${method} ${path}`;
+        const extVal =
+          (operation as any)['x-mcp'] ?? (pathItem as any)['x-mcp'] ?? (api as any)['x-mcp'];
+        let extPreview: string;
+        try {
+          extPreview = JSON.stringify(extVal);
+        } catch {
+          extPreview = String(extVal);
+        }
+        console.warn(
+          `Error evaluating x-mcp extension for operation ${loc} (x-mcp=${extPreview}):`,
+          error
+        );
+        if (!defaultInclude) {
+          continue;
+        }
+      }
+
      // Generate a unique name for the tool
      let baseName = operation.operationId || generateOperationId(method, path);
      if (!baseName) continue;
--- a/src/types/index.ts
+++ b/src/types/index.ts
@ -29,6 +29,12 @@ export interface CliOptions {
  transport?: TransportType;
  /** Server port (for web and streamable-http transports) */
  port?: number;
+  /**
+   * Default behavior for x-mcp filtering.
+   * true (default) = include by default when x-mcp is missing or invalid;
+   * false = exclude by default unless x-mcp explicitly enables.
+   */
+  defaultInclude?: boolean;
 }

 /**
--- a/src/utils/helpers.ts
+++ b/src/utils/helpers.ts
@ -1,6 +1,7 @@
 /**
 * General helper utilities for OpenAPI to MCP generator
 */
+import { OpenAPIV3 } from 'openapi-types';

 /**
 * Safely stringify a JSON object with proper error handling
@ -110,3 +111,63 @@ export function formatComment(str: string, maxLineLength: number = 80): string {

  return lines.join('\n * ');
 }
+
+/**
+ * Normalize a value to boolean if it looks like a boolean; otherwise undefined.
+ */
+export function normalizeBoolean(value: unknown): boolean | undefined {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(normalized)) return true;
+    if (['false', '0', 'no', 'off'].includes(normalized)) return false;
+    return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Determine if an operation should be included in MCP generation based on x-mcp.
+ * Precedence: operation > path > root; uses provided default when all undefined.
+ */
+export function shouldIncludeOperationForMcp(
+  api: OpenAPIV3.Document,
+  pathItem: OpenAPIV3.PathItemObject,
+  operation: OpenAPIV3.OperationObject,
+  defaultInclude: boolean = true
+): boolean {
+  const opRaw = (operation as any)['x-mcp'];
+  const opVal = normalizeBoolean(opRaw);
+  if (typeof opVal !== 'undefined') return opVal;
+  if (typeof opRaw !== 'undefined') {
+    console.warn(
+      `Invalid x-mcp value on operation '${operation.operationId ?? '[no operationId]'}':`,
+      opRaw,
+      `-> expected boolean or 'true'/'false'. Falling back to path/root/default.`
+    );
+  }
+
+  const pathRaw = (pathItem as any)['x-mcp'];
+  const pathVal = normalizeBoolean(pathRaw);
+  if (typeof pathVal !== 'undefined') return pathVal;
+  if (typeof pathRaw !== 'undefined') {
+    console.warn(
+      `Invalid x-mcp value on path item:`,
+      pathRaw,
+      `-> expected boolean or 'true'/'false'. Falling back to root/default.`
+    );
+  }
+
+  const rootRaw = (api as any)['x-mcp'];
+  const rootVal = normalizeBoolean(rootRaw);
+  if (typeof rootVal !== 'undefined') return rootVal;
+  if (typeof rootRaw !== 'undefined') {
+    console.warn(
+      `Invalid x-mcp value at API root:`,
+      rootRaw,
+      `-> expected boolean or 'true'/'false'. Falling back to defaultInclude=${defaultInclude}.`
+    );
+  }
+
+  return defaultInclude;
+}
Author	SHA1	Message	Date
Harsha v	8ee9fc383d	Create mcpcat.md	2025-09-30 12:15:47 -07:00
Harsha v	f29c277860	Merge pull request #39 from harsha-iiiv/copilot/fix-33b9d782-1c7b-44d1-89a9-adbd77a32aa8 Upgrade package to version 3.2.0 and address code quality improvements based on review feedback	2025-08-24 22:03:57 -07:00
copilot-swe-agent[bot]	33220c1e82	Address coderabbitai review feedback: improve docs, error handling, and boolean normalization Co-authored-by: harsha-iiiv <31560965+harsha-iiiv@users.noreply.github.com>	2025-08-25 04:59:26 +00:00
copilot-swe-agent[bot]	eda4505a63	Update CHANGELOG.md with corrected version details and proper categorization Co-authored-by: harsha-iiiv <31560965+harsha-iiiv@users.noreply.github.com>	2025-08-25 04:41:52 +00:00
copilot-swe-agent[bot]	4bf66d9efd	Upgrade package version to 3.2.0 and update CHANGELOG.md Co-authored-by: harsha-iiiv <31560965+harsha-iiiv@users.noreply.github.com>	2025-08-24 23:14:41 +00:00
copilot-swe-agent[bot]	7a31e1f6e9	Initial plan	2025-08-24 23:09:33 +00:00
Harsha v	82ff2b726d	Merge pull request #37 from atomicpages/main feat: allow folks to BYO OpenAPIV3.Document harsha-iiiv/openapi-mcp-generator#35	2025-08-24 16:04:56 -07:00
Harsha v	1c806b8dab	Merge pull request #38 from FabriBorgobello/feature/endpoint-filtering feature: Add endpoint filtering	2025-08-24 16:04:01 -07:00
Fabricio Borgobello	c9015f395e	Update src/utils/helpers.ts Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>	2025-08-22 11:58:27 +02:00
Fabricio Borgobello	af1b664653	Adjust boolean validation	2025-08-22 11:57:58 +02:00
Fabricio Borgobello	1f001bb47a	Remove comment	2025-08-22 11:04:08 +02:00
Fabricio Borgobello	b1e29c22de	feature/endpoint-filtering	2025-08-22 11:00:13 +02:00
Dennis Thompson	e6352d13b6	chore: fix clerical error on docs	2025-08-17 21:48:46 -07:00
Dennis Thompson	26307f26ad	Update src/api.ts Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>	2025-08-17 21:48:06 -07:00
Dennis Thompson	b7bc67e444	fix: addresses harsha-iiiv/openapi-mcp-generator#35	2025-08-17 21:26:27 -07:00