mcp-openapi-schema-explorer 1.0.0

package/dist/src/services/reference-transform.js

@@ -0,0 +1,75 @@
+import { buildComponentDetailUri } from '../utils/uri-builder.js'; // Added .js extension
+export class ReferenceTransformService {
+    constructor() {
+        this.transformers = new Map();
+    }
+    registerTransformer(format, transformer) {
+        this.transformers.set(format, transformer);
+    }
+    transformDocument(document, context) {
+        const transformer = this.transformers.get(context.format);
+        if (!transformer) {
+            throw new Error(`No transformer registered for format: ${context.format}`);
+        }
+        return transformer.transformRefs(document, context);
+    }
+}
+export class OpenAPITransformer {
+    // Handle nested objects recursively
+    transformObject(obj, _context) {
+        if (!obj || typeof obj !== 'object') {
+            return obj;
+        }
+        // Handle arrays
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.transformObject(item, _context));
+        }
+        // Handle references
+        if (this.isReferenceObject(obj)) {
+            return this.transformReference(obj.$ref);
+        }
+        // Recursively transform object properties
+        const result = {};
+        if (typeof obj === 'object') {
+            for (const [key, value] of Object.entries(obj)) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    Object.defineProperty(result, key, {
+                        value: this.transformObject(value, _context),
+                        enumerable: true,
+                        writable: true,
+                        configurable: true,
+                    });
+                }
+            }
+        }
+        return result;
+    }
+    isReferenceObject(obj) {
+        return typeof obj === 'object' && obj !== null && '$ref' in obj;
+    }
+    transformReference(ref) {
+        // Handle only internal references for now
+        if (!ref.startsWith('#/')) {
+            return { $ref: ref }; // Keep external refs as-is
+        }
+        // Example ref: #/components/schemas/MySchema
+        const parts = ref.split('/');
+        // Check if it's an internal component reference
+        if (parts[0] === '#' && parts[1] === 'components' && parts.length === 4) {
+            const componentType = parts[2];
+            const componentName = parts[3];
+            // Use the centralized builder to create the correct URI
+            const newUri = buildComponentDetailUri(componentType, componentName);
+            return {
+                $ref: newUri,
+            };
+        }
+        // Keep other internal references (#/paths/...) and external references as-is
+        return { $ref: ref };
+    }
+    transformRefs(document, context) {
+        const transformed = this.transformObject(document, context);
+        return transformed;
+    }
+}
+//# sourceMappingURL=reference-transform.js.map

package/dist/src/services/reference-transform.js.map

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

package/dist/src/services/spec-loader.d.ts

@@ -0,0 +1,27 @@
+import { OpenAPI } from 'openapi-types';
+import { ReferenceTransformService, TransformContext } from './reference-transform.js';
+/**
+ * Service for loading and transforming OpenAPI specifications
+ */
+export declare class SpecLoaderService {
+    private specPath;
+    private referenceTransform;
+    private specData;
+    constructor(specPath: string, referenceTransform: ReferenceTransformService);
+    /**
+     * Load, potentially convert (from v2), and parse the OpenAPI specification.
+     */
+    loadSpec(): Promise<OpenAPI.Document>;
+    /**
+     * Get the loaded specification
+     */
+    getSpec(): Promise<OpenAPI.Document>;
+    /**
+     * Get transformed specification with MCP resource references
+     */
+    getTransformedSpec(context: TransformContext): Promise<OpenAPI.Document>;
+}
+/**
+ * Create and initialize a new SpecLoaderService instance
+ */
+export declare function createSpecLoader(specPath: string, referenceTransform: ReferenceTransformService): Promise<SpecLoaderService>;

package/dist/src/services/spec-loader.js

@@ -0,0 +1,77 @@
+import * as swagger2openapi from 'swagger2openapi';
+/**
+ * Service for loading and transforming OpenAPI specifications
+ */
+export class SpecLoaderService {
+    constructor(specPath, referenceTransform) {
+        this.specPath = specPath;
+        this.referenceTransform = referenceTransform;
+        this.specData = null;
+    }
+    /**
+     * Load, potentially convert (from v2), and parse the OpenAPI specification.
+     */
+    async loadSpec() {
+        const options = {
+            patch: true, // Fix minor errors in the spec
+            warnOnly: true, // Add warnings for non-patchable errors instead of throwing
+            origin: this.specPath, // Helps with resolving relative references if needed
+            source: this.specPath,
+        };
+        try {
+            let result;
+            // Check if specPath is a URL
+            if (this.specPath.startsWith('http://') || this.specPath.startsWith('https://')) {
+                result = await swagger2openapi.convertUrl(this.specPath, options);
+            }
+            else {
+                result = await swagger2openapi.convertFile(this.specPath, options);
+            }
+            // swagger2openapi returns the result in result.openapi
+            if (!result || !result.openapi) {
+                throw new Error('Conversion or parsing failed to produce an OpenAPI document.');
+            }
+            // TODO: Check result.options?.warnings for potential issues?
+            this.specData = result.openapi; // Assuming result.openapi is compatible
+            return this.specData;
+        }
+        catch (error) {
+            // Improve error message clarity
+            let message = `Failed to load/convert OpenAPI spec from ${this.specPath}: `;
+            if (error instanceof Error) {
+                message += error.message;
+                // Include stack trace if available and helpful?
+                // console.error(error.stack);
+            }
+            else {
+                message += String(error);
+            }
+            throw new Error(message);
+        }
+    }
+    /**
+     * Get the loaded specification
+     */
+    async getSpec() {
+        if (!this.specData) {
+            await this.loadSpec();
+        }
+        return this.specData;
+    }
+    /**
+     * Get transformed specification with MCP resource references
+     */
+    async getTransformedSpec(context) {
+        const spec = await this.getSpec();
+        return this.referenceTransform.transformDocument(spec, context);
+    }
+}
+/**
+ * Create and initialize a new SpecLoaderService instance
+ */
+export async function createSpecLoader(specPath, referenceTransform) {
+    const loader = new SpecLoaderService(specPath, referenceTransform);
+    await loader.loadSpec();
+    return loader;
+}
+//# sourceMappingURL=spec-loader.js.map

package/dist/src/services/spec-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-loader.js","sourceRoot":"","sources":["../../../src/services/spec-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,eAAe,MAAM,iBAAiB,CAAC;AAInD;;GAEG;AACH,MAAM,OAAO,iBAAiB;IAG5B,YACU,QAAgB,EAChB,kBAA6C;QAD7C,aAAQ,GAAR,QAAQ,CAAQ;QAChB,uBAAkB,GAAlB,kBAAkB,CAA2B;QAJ/C,aAAQ,GAA4B,IAAI,CAAC;IAK9C,CAAC;IAEJ;;OAEG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,OAAO,GAAG;YACd,KAAK,EAAE,IAAI,EAAE,+BAA+B;YAC5C,QAAQ,EAAE,IAAI,EAAE,4DAA4D;YAC5E,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,qDAAqD;YAC5E,MAAM,EAAE,IAAI,CAAC,QAAQ;SACtB,CAAC;QAEF,IAAI,CAAC;YACH,IAAI,MAAM,CAAC;YACX,6BAA6B;YAC7B,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChF,MAAM,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpE,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,MAAM,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACrE,CAAC;YAED,uDAAuD;YACvD,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC/B,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;YAClF,CAAC;YAED,6DAA6D;YAE7D,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,OAA2B,CAAC,CAAC,wCAAwC;YAC5F,OAAO,IAAI,CAAC,QAAQ,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gCAAgC;YAChC,IAAI,OAAO,GAAG,4CAA4C,IAAI,CAAC,QAAQ,IAAI,CAAC;YAC5E,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC;gBACzB,gDAAgD;gBAChD,8BAA8B;YAChC,CAAC;iBAAM,CAAC;gBACN,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxB,CAAC;QACD,OAAO,IAAI,CAAC,QAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB,CAAC,OAAyB;QAChD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,kBAA6C;IAE7C,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;IACnE,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,11 @@
+import { OpenAPI } from 'openapi-types';
+import type { TransformContext } from './services/reference-transform.js';
+/** Common HTTP methods used in OpenAPI specs */
+export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'patch';
+/** Interface for spec loader */
+export interface SpecLoaderService {
+    getSpec(): Promise<OpenAPI.Document>;
+    getTransformedSpec(context: TransformContext): Promise<OpenAPI.Document>;
+}
+export type { TransformContext };
+export type { OpenAPI };

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/utils/uri-builder.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Utility functions for building standardized MCP URIs for this server.
+ */
+/**
+ * Encodes a string component for safe inclusion in a URI path segment.
+ * Uses standard encodeURIComponent.
+ * Encodes a path string for safe inclusion in a URI.
+ * This specifically targets path strings which might contain characters
+ * like '{', '}', etc., that need encoding when forming the URI path part.
+ * Uses standard encodeURIComponent.
+ * Encodes a path string for safe inclusion in a URI path segment.
+ * This is necessary because the path segment comes from the user potentially
+ * containing characters that need encoding (like '{', '}').
+ * Uses standard encodeURIComponent.
+ * @param path The path string to encode.
+ * @returns The encoded path string, with leading slashes removed before encoding.
+ */
+export declare function encodeUriPathComponent(path: string): string;
+/**
+ * Builds the URI for accessing a specific component's details.
+ * Example: openapi://components/schemas/MySchema
+ * @param type The component type (e.g., 'schemas', 'responses').
+ * @param name The component name.
+ * @returns The full component detail URI.
+ */
+export declare function buildComponentDetailUri(type: string, name: string): string;
+/**
+ * Builds the URI for listing components of a specific type.
+ * Example: openapi://components/schemas
+ * @param type The component type (e.g., 'schemas', 'responses').
+ * @returns The full component map URI.
+ */
+export declare function buildComponentMapUri(type: string): string;
+/**
+ * Builds the URI for accessing a specific operation's details.
+ * Example: openapi://paths/users/{userId}/GET
+ * @param path The API path (e.g., '/users/{userId}').
+ * @param method The HTTP method (e.g., 'GET', 'POST').
+ * @returns The full operation detail URI.
+ */
+export declare function buildOperationUri(path: string, method: string): string;
+/**
+ * Builds the URI for listing methods available at a specific path.
+ * Example: openapi://paths/users/{userId}
+ * @param path The API path (e.g., '/users/{userId}').
+ * @returns The full path item URI.
+ */
+export declare function buildPathItemUri(path: string): string;
+/**
+ * Builds the URI for accessing a top-level field (like 'info' or 'servers')
+ * or triggering a list view ('paths', 'components').
+ * Example: openapi://info, openapi://paths
+ * @param field The top-level field name.
+ * @returns The full top-level field URI.
+ */
+export declare function buildTopLevelFieldUri(field: string): string;
+/**
+ * Builds the URI suffix for a specific component's details.
+ * Example: components/schemas/MySchema
+ */
+export declare function buildComponentDetailUriSuffix(type: string, name: string): string;
+/**
+ * Builds the URI suffix for listing components of a specific type.
+ * Example: components/schemas
+ */
+export declare function buildComponentMapUriSuffix(type: string): string;
+/**
+ * Builds the URI suffix for a specific operation's details.
+ * Example: paths/users/{userId}/get
+ */
+export declare function buildOperationUriSuffix(path: string, method: string): string;
+/**
+ * Builds the URI suffix for listing methods available at a specific path.
+ * Example: paths/users/{userId}
+ */
+export declare function buildPathItemUriSuffix(path: string): string;
+/**
+ * Builds the URI suffix for a top-level field.
+ * Example: info, paths
+ */
+export declare function buildTopLevelFieldUriSuffix(field: string): string;

package/dist/src/utils/uri-builder.js

@@ -0,0 +1,121 @@
+/**
+ * Utility functions for building standardized MCP URIs for this server.
+ */
+const BASE_URI_SCHEME = 'openapi://';
+/**
+ * Encodes a string component for safe inclusion in a URI path segment.
+ * Uses standard encodeURIComponent.
+ * Encodes a path string for safe inclusion in a URI.
+ * This specifically targets path strings which might contain characters
+ * like '{', '}', etc., that need encoding when forming the URI path part.
+ * Uses standard encodeURIComponent.
+ * Encodes a path string for safe inclusion in a URI path segment.
+ * This is necessary because the path segment comes from the user potentially
+ * containing characters that need encoding (like '{', '}').
+ * Uses standard encodeURIComponent.
+ * @param path The path string to encode.
+ * @returns The encoded path string, with leading slashes removed before encoding.
+ */
+export function encodeUriPathComponent(path) {
+    // Added export
+    // Remove leading slashes before encoding
+    const pathWithoutLeadingSlash = path.replace(/^\/+/, '');
+    return encodeURIComponent(pathWithoutLeadingSlash);
+}
+// --- Full URI Builders ---
+/**
+ * Builds the URI for accessing a specific component's details.
+ * Example: openapi://components/schemas/MySchema
+ * @param type The component type (e.g., 'schemas', 'responses').
+ * @param name The component name.
+ * @returns The full component detail URI.
+ */
+export function buildComponentDetailUri(type, name) {
+    // Per user instruction, do not encode type or name here.
+    return `${BASE_URI_SCHEME}components/${type}/${name}`;
+}
+/**
+ * Builds the URI for listing components of a specific type.
+ * Example: openapi://components/schemas
+ * @param type The component type (e.g., 'schemas', 'responses').
+ * @returns The full component map URI.
+ */
+export function buildComponentMapUri(type) {
+    // Per user instruction, do not encode type here.
+    return `${BASE_URI_SCHEME}components/${type}`;
+}
+/**
+ * Builds the URI for accessing a specific operation's details.
+ * Example: openapi://paths/users/{userId}/GET
+ * @param path The API path (e.g., '/users/{userId}').
+ * @param method The HTTP method (e.g., 'GET', 'POST').
+ * @returns The full operation detail URI.
+ */
+export function buildOperationUri(path, method) {
+    // Encode only the path component. Assume 'path' is raw/decoded.
+    // Method is assumed to be safe or handled by SDK/client.
+    return `${BASE_URI_SCHEME}paths/${encodeUriPathComponent(path)}/${method.toLowerCase()}`; // Standardize method to lowercase
+}
+/**
+ * Builds the URI for listing methods available at a specific path.
+ * Example: openapi://paths/users/{userId}
+ * @param path The API path (e.g., '/users/{userId}').
+ * @returns The full path item URI.
+ */
+export function buildPathItemUri(path) {
+    // Encode only the path component. Assume 'path' is raw/decoded.
+    return `${BASE_URI_SCHEME}paths/${encodeUriPathComponent(path)}`;
+}
+/**
+ * Builds the URI for accessing a top-level field (like 'info' or 'servers')
+ * or triggering a list view ('paths', 'components').
+ * Example: openapi://info, openapi://paths
+ * @param field The top-level field name.
+ * @returns The full top-level field URI.
+ */
+export function buildTopLevelFieldUri(field) {
+    // Per user instruction, do not encode field here.
+    return `${BASE_URI_SCHEME}${field}`;
+}
+// --- URI Suffix Builders (for RenderResultItem) ---
+/**
+ * Builds the URI suffix for a specific component's details.
+ * Example: components/schemas/MySchema
+ */
+export function buildComponentDetailUriSuffix(type, name) {
+    // Per user instruction, do not encode type or name here.
+    return `components/${type}/${name}`;
+}
+/**
+ * Builds the URI suffix for listing components of a specific type.
+ * Example: components/schemas
+ */
+export function buildComponentMapUriSuffix(type) {
+    // Per user instruction, do not encode type here.
+    return `components/${type}`;
+}
+/**
+ * Builds the URI suffix for a specific operation's details.
+ * Example: paths/users/{userId}/get
+ */
+export function buildOperationUriSuffix(path, method) {
+    // Encode only the path component for the suffix. Assume 'path' is raw/decoded.
+    return `paths/${encodeUriPathComponent(path)}/${method.toLowerCase()}`;
+}
+/**
+ * Builds the URI suffix for listing methods available at a specific path.
+ * Example: paths/users/{userId}
+ */
+export function buildPathItemUriSuffix(path) {
+    // Encode only the path component for the suffix. Assume 'path' is raw/decoded.
+    return `paths/${encodeUriPathComponent(path)}`;
+}
+/**
+ * Builds the URI suffix for a top-level field.
+ * Example: info, paths
+ */
+export function buildTopLevelFieldUriSuffix(field) {
+    // Per user instruction, do not encode field here.
+    return field;
+}
+//# sourceMappingURL=uri-builder.js.map

package/dist/src/utils/uri-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-builder.js","sourceRoot":"","sources":["../../../src/utils/uri-builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,eAAe,GAAG,YAAY,CAAC;AAErC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,eAAe;IACf,yCAAyC;IACzC,MAAM,uBAAuB,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,kBAAkB,CAAC,uBAAuB,CAAC,CAAC;AACrD,CAAC;AAED,4BAA4B;AAE5B;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,IAAY;IAChE,yDAAyD;IACzD,OAAO,GAAG,eAAe,cAAc,IAAI,IAAI,IAAI,EAAE,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,iDAAiD;IACjD,OAAO,GAAG,eAAe,cAAc,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAc;IAC5D,gEAAgE;IAChE,yDAAyD;IACzD,OAAO,GAAG,eAAe,SAAS,sBAAsB,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,kCAAkC;AAC9H,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,gEAAgE;IAChE,OAAO,GAAG,eAAe,SAAS,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,kDAAkD;IAClD,OAAO,GAAG,eAAe,GAAG,KAAK,EAAE,CAAC;AACtC,CAAC;AAED,qDAAqD;AAErD;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAAC,IAAY,EAAE,IAAY;IACtE,yDAAyD;IACzD,OAAO,cAAc,IAAI,IAAI,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,iDAAiD;IACjD,OAAO,cAAc,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,MAAc;IAClE,+EAA+E;IAC/E,OAAO,SAAS,sBAAsB,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,+EAA+E;IAC/E,OAAO,SAAS,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,kDAAkD;IAClD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "1.0.0";

package/dist/src/version.js

@@ -0,0 +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.0';
+//# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,kCAAkC;AAElC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/eslint.config.js

@@ -0,0 +1,88 @@
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+import eslintJs from '@eslint/js';
+import globals from 'globals';
+import security from 'eslint-plugin-security';
+
+export default [
+  {
+    ignores: ['dist/**', 'node_modules/**', 'local-docs/**'],
+  },
+  eslintJs.configs.recommended,
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        project: './tsconfig.json',
+        ecmaVersion: 2020,
+        sourceType: 'module',
+      },
+      globals: {
+        ...globals.node,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+      security: security,
+    },
+    rules: {
+      ...tseslint.configs['recommended'].rules,
+      ...tseslint.configs['recommended-requiring-type-checking'].rules,
+      '@typescript-eslint/explicit-function-return-type': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/naming-convention': [
+        'error',
+        {
+          selector: 'interface',
+          format: ['PascalCase'],
+        },
+      ],
+      'no-console': ['error', { allow: ['warn', 'error'] }],
+      ...security.configs.recommended.rules,
+    },
+  },
+  {
+    files: ['test/**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        project: './tsconfig.test.json',
+        ecmaVersion: 2020,
+        sourceType: 'module',
+      },
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+      security: security,
+    },
+    rules: {
+      ...tseslint.configs['recommended'].rules,
+      ...tseslint.configs['recommended-requiring-type-checking'].rules,
+      '@typescript-eslint/explicit-function-return-type': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'no-console': 'off', // Allow console in tests
+    },
+  },
+  // Configuration for scripts (like generate-version.js)
+  {
+    files: ['scripts/**/*.js'],
+    languageOptions: {
+      globals: {
+        ...globals.node, // Enable Node.js global variables
+      },
+      ecmaVersion: 2022, // Use a recent version supporting top-level await etc.
+      sourceType: 'module', // Treat .js files in scripts/ as ES Modules
+    },
+    rules: {
+      // Add any specific rules for scripts if needed, e.g., allow console
+      'no-console': 'off',
+    },
+  },
+];

package/jest.config.js

@@ -0,0 +1,32 @@
+/** @type {import('jest').Config} */
+export default {
+  testPathIgnorePatterns: ['/node_modules/', '/local-docs/', '/dist/'],
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        useESM: true,
+        tsconfig: 'tsconfig.test.json',
+      },
+    ],
+  },
+  setupFilesAfterEnv: ['./test/setup.ts'],
+  reporters: [
+    [
+      'jest-silent-reporter',
+      {
+        useDots: true,
+        showPaths: true,
+        showInlineStatus: true,
+        showWarnings: true,
+      },
+    ],
+  ],
+  verbose: true,
+};

package/justfile

@@ -0,0 +1,66 @@
+default:
+    @just --list
+
+# Install dependencies
+install:
+    npm install
+
+# Run tests
+test *ARGS='':
+    npm run test {{ARGS}}
+    @echo "All tests passed successfully!"
+
+# Run tests with coverage
+test-coverage *ARGS='':
+    npm run test:coverage {{ARGS}}
+
+# Lint code
+lint:
+    npm run lint
+    @echo "Linting completed successfully!"
+
+# Format code
+format:
+    npm run format
+
+# Type check
+type-check:
+    npm run type-check
+    @echo "Type checking completed successfully!"
+
+# Security scan dependencies for vulnerabilities
+audit:
+    npm audit
+
+# Check license compliance
+check-licenses:
+    npx license-checker --production \
+        --onlyAllow "MIT;ISC;BSD-2-Clause;BSD-3-Clause;Apache-2.0;Python-2.0" \
+        --excludePrivatePackages \
+        --summary
+
+# Run all security checks
+security:
+    @just audit
+    @just check-licenses
+
+# Build the project
+build:
+    npm run build
+
+# Launch MCP inspector server
+inspect:
+    #!/usr/bin/env sh
+    just build
+    npx @modelcontextprotocol/inspector \
+        node dist/src/index.js \
+        test/fixtures/complex-endpoint.json \
+        --output-format yaml
+
+# Run all checks including security
+all:
+    @just format
+    @just lint
+    @just build
+    @just test-coverage
+    @just security