@mcp-layer/gateway 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-layer/gateway",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Shared runtime primitives for MCP HTTP/GraphQL adapters with validation, resilience, telemetry, and catalog mapping.",
   "repository": {
     "type": "git",
@@ -18,8 +18,10 @@
     "telemetry"
   ],
   "main": "src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
@@ -27,6 +29,7 @@
   },
   "files": [
     "src",
+    "types",
     "LICENSE"
   ],
   "publishConfig": {
@@ -38,8 +41,8 @@
     "json-schema-traverse": "^1.0.0",
     "opossum": "^8.1.0",
     "safe-regex2": "^2.0.0",
-    "@mcp-layer/error": "0.2.0",
-    "@mcp-layer/schema": "1.0.2"
+    "@mcp-layer/error": "0.2.1",
+    "@mcp-layer/schema": "1.0.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0"
@@ -51,10 +54,12 @@
   },
   "devDependencies": {
     "fastify": "^5.7.4",
-    "@mcp-layer/attach": "1.1.1",
-    "@mcp-layer/test-server": "1.0.1"
+    "@mcp-layer/attach": "1.1.2",
+    "@mcp-layer/manager": "0.2.1",
+    "@mcp-layer/test-server": "1.0.4"
   },
   "scripts": {
-    "test": "node --test --experimental-test-coverage ./test/**/*.test.js"
+    "build:types": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-test-coverage \"./test/**/*.test.js\""
   }
 }

package/types/call.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Create telemetry helpers for a request lifecycle.
+ * @param {{ telemetry: ReturnType<import('./telemetry/index.js').createTelemetry> | null, spanName: string, attributes: Record<string, unknown>, labels: Record<string, string>, validationLabels?: Record<string, string> }} config - Telemetry context.
+ * @returns {{ recordValidation: () => void, recordSuccess: () => void, recordError: (error: Error & { code?: string | number }) => void, recordStatus: (status: string, errorType?: string | number) => void, finish: () => void }}
+ */
+export function createCallContext(config: {
+    telemetry: ReturnType<typeof import("./telemetry/index.js").createTelemetry> | null;
+    spanName: string;
+    attributes: Record<string, unknown>;
+    labels: Record<string, string>;
+    validationLabels?: Record<string, string>;
+}): {
+    recordValidation: () => void;
+    recordSuccess: () => void;
+    recordError: (error: Error & {
+        code?: string | number;
+    }) => void;
+    recordStatus: (status: string, errorType?: string | number) => void;
+    finish: () => void;
+};

package/types/config/defaults.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Build runtime defaults for an adapter.
+ * @param {string} serviceName - Default telemetry service name.
+ * @returns {{ prefix: string | undefined, validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean } }}
+ */
+export function defaults(serviceName: string): {
+    prefix: string | undefined;
+    validation: {
+        trustSchemas: "auto" | true | false;
+        maxSchemaDepth: number;
+        maxSchemaSize: number;
+        maxPatternLength: number;
+        maxToolNameLength: number;
+        maxTemplateParamLength: number;
+    };
+    resilience: {
+        enabled: boolean;
+        timeout: number;
+        errorThresholdPercentage: number;
+        resetTimeout: number;
+        volumeThreshold: number;
+    };
+    telemetry: {
+        enabled: boolean;
+        serviceName: string;
+        metricPrefix: string;
+        api?: typeof import("@opentelemetry/api");
+    };
+    errors: {
+        exposeDetails: boolean;
+    };
+};

package/types/config/validate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Validate base runtime options and apply defaults.
+ * @param {Record<string, unknown>} opts - User-supplied options.
+ * @param {{ name?: string, serviceName?: string }} [meta] - Validation metadata.
+ * @returns {{ session: unknown, manager?: { get: (request: import('fastify').FastifyRequest) => Promise<import('@mcp-layer/session').Session>, close?: () => Promise<void> }, prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string), validation: { trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }, resilience: { enabled: boolean, timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }, telemetry: { enabled: boolean, serviceName: string, metricPrefix: string, api?: import('@opentelemetry/api') }, errors: { exposeDetails: boolean }, normalizeError?: (error: Error & { code?: string | number }, instance: string, requestId?: string, options?: { exposeDetails?: boolean }) => unknown }}
+ */
+export function validateRuntimeOptions(opts: Record<string, unknown>, meta?: {
+    name?: string;
+    serviceName?: string;
+}): {
+    session: unknown;
+    manager?: {
+        get: (request: import("fastify").FastifyRequest) => Promise<any>;
+        close?: () => Promise<void>;
+    };
+    prefix?: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string);
+    validation: {
+        trustSchemas: "auto" | true | false;
+        maxSchemaDepth: number;
+        maxSchemaSize: number;
+        maxPatternLength: number;
+        maxToolNameLength: number;
+        maxTemplateParamLength: number;
+    };
+    resilience: {
+        enabled: boolean;
+        timeout: number;
+        errorThresholdPercentage: number;
+        resetTimeout: number;
+        volumeThreshold: number;
+    };
+    telemetry: {
+        enabled: boolean;
+        serviceName: string;
+        metricPrefix: string;
+        api?: typeof import("@opentelemetry/api");
+    };
+    errors: {
+        exposeDetails: boolean;
+    };
+    normalizeError?: (error: Error & {
+        code?: string | number;
+    }, instance: string, requestId?: string, options?: {
+        exposeDetails?: boolean;
+    }) => unknown;
+};

package/types/index.d.ts

@@ -0,0 +1,11 @@
+export { createRuntime } from "./runtime.js";
+export { createCallContext } from "./call.js";
+export { createTelemetry } from "./telemetry/index.js";
+export { shouldTrustSchemas } from "./validation/trust.js";
+export { checkSchemaSafety } from "./validation/safety.js";
+export { defaults } from "./config/defaults.js";
+export { validateRuntimeOptions } from "./config/validate.js";
+export { createMap, TYPES } from "./map.js";
+export { deriveApiVersion, resolvePrefix } from "./version.js";
+export { createCircuitBreaker, executeWithBreaker } from "./resilience/breaker.js";
+export { createValidator, SchemaValidator } from "./validation/validator.js";

package/types/map.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Create a deterministic catalog map for adapters.
+ * @param {{ items?: Array<Record<string, unknown>> }} catalog - Extracted catalog.
+ * @returns {{ tools: Array<Record<string, unknown>>, prompts: Array<Record<string, unknown>>, resources: Array<Record<string, unknown>>, templates: Array<Record<string, unknown>>, entries: Array<{ type: string, root: 'query' | 'mutation', name: string, field: string, item: Record<string, unknown> }>, byType: (type: string) => Array<Record<string, unknown>>, find: (type: string, name: string) => Record<string, unknown> | undefined, findField: (type: string, name: string) => string | undefined }}
+ */
+export function createMap(catalog?: {
+    items?: Array<Record<string, unknown>>;
+}): {
+    tools: Array<Record<string, unknown>>;
+    prompts: Array<Record<string, unknown>>;
+    resources: Array<Record<string, unknown>>;
+    templates: Array<Record<string, unknown>>;
+    entries: Array<{
+        type: string;
+        root: "query" | "mutation";
+        name: string;
+        field: string;
+        item: Record<string, unknown>;
+    }>;
+    byType: (type: string) => Array<Record<string, unknown>>;
+    find: (type: string, name: string) => Record<string, unknown> | undefined;
+    findField: (type: string, name: string) => string | undefined;
+};
+export const TYPES: string[];

package/types/resilience/breaker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Create a circuit breaker for an MCP session.
+ * @param {import('@mcp-layer/session').Session} session - MCP session.
+ * @param {{ timeout: number, errorThresholdPercentage: number, resetTimeout: number, volumeThreshold: number }} config - Breaker configuration.
+ * @returns {CircuitBreaker}
+ */
+export function createCircuitBreaker(session: any, config: {
+    timeout: number;
+    errorThresholdPercentage: number;
+    resetTimeout: number;
+    volumeThreshold: number;
+}): CircuitBreaker;
+/**
+ * Execute an MCP call through a circuit breaker if enabled.
+ * @param {CircuitBreaker | null} breaker - Breaker instance or null if disabled.
+ * @param {import('@mcp-layer/session').Session} session - MCP session.
+ * @param {string} method - MCP method name.
+ * @param {Record<string, unknown>} params - MCP parameters.
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export function executeWithBreaker(breaker: CircuitBreaker | null, session: any, method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;

package/types/runtime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Create shared runtime contexts for MCP adapters.
+ * @param {Record<string, unknown>} opts - Runtime options.
+ * @param {{ name?: string, serviceName?: string }} [meta] - Runtime metadata.
+ * @returns {Promise<{ config: ReturnType<typeof validateRuntimeOptions>, contexts: Array<{ session: import('@mcp-layer/session').Session, catalog: { server?: { info?: Record<string, unknown> }, items?: Array<Record<string, unknown>> }, info: Record<string, unknown> | undefined, version: string, prefix: string, validator: import('./validation/validator.js').SchemaValidator, telemetry: ReturnType<typeof createTelemetry> | null, resolve: (request: import('fastify').FastifyRequest) => Promise<{ session: import('@mcp-layer/session').Session, breaker: import('opossum') | null }>, execute: (request: import('fastify').FastifyRequest, method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown }>, breakers: Map<string, import('opossum')>, normalize: (error: Error & { code?: string | number }, instance: string, requestId?: string) => unknown, close: () => Promise<void> }>}
+ */
+export function createRuntime(opts: Record<string, unknown>, meta?: {
+    name?: string;
+    serviceName?: string;
+}): Promise<{
+    config: ReturnType<typeof validateRuntimeOptions>;
+    contexts: Array<{
+        session: any;
+        catalog: {
+            server?: {
+                info?: Record<string, unknown>;
+            };
+            items?: Array<Record<string, unknown>>;
+        };
+        info: Record<string, unknown> | undefined;
+        version: string;
+        prefix: string;
+        validator: import("./validation/validator.js").SchemaValidator;
+        telemetry: ReturnType<typeof createTelemetry> | null;
+        resolve: (request: import("fastify").FastifyRequest) => Promise<{
+            session: any;
+            breaker: any | null;
+        }>;
+        execute: (request: import("fastify").FastifyRequest, method: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+        normalize: (error: Error & {
+            code?: string | number;
+        }, instance: string, requestId?: string) => unknown;
+    }>;
+    breakers: Map<string, any>;
+    normalize: (error: Error & {
+        code?: string | number;
+    }, instance: string, requestId?: string) => unknown;
+    close: () => Promise<void>;
+}>;
+import { validateRuntimeOptions } from './config/validate.js';
+import { createTelemetry } from './telemetry/index.js';

package/types/telemetry/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Create a telemetry helper for adapter runtimes.
+ * @param {{ enabled?: boolean, serviceName: string, metricPrefix?: string, api?: import('@opentelemetry/api') }} config - Telemetry configuration.
+ * @returns {{ tracer: import('@opentelemetry/api').Tracer, meter: import('@opentelemetry/api').Meter, context: import('@opentelemetry/api').ContextAPI, propagation: import('@opentelemetry/api').PropagationAPI, metrics: { callDuration: import('@opentelemetry/api').Histogram, callErrors: import('@opentelemetry/api').Counter, validationErrors: import('@opentelemetry/api').Counter, circuitState: import('@opentelemetry/api').ObservableGauge }, setCircuitState: (session: string, state: string) => void } | null}
+ */
+export function createTelemetry(config: {
+    enabled?: boolean;
+    serviceName: string;
+    metricPrefix?: string;
+    api?: typeof import("@opentelemetry/api");
+}): {
+    tracer: import("@opentelemetry/api").Tracer;
+    meter: import("@opentelemetry/api").Meter;
+    context: import("@opentelemetry/api").ContextAPI;
+    propagation: import("@opentelemetry/api").PropagationAPI;
+    metrics: {
+        callDuration: import("@opentelemetry/api").Histogram;
+        callErrors: import("@opentelemetry/api").Counter;
+        validationErrors: import("@opentelemetry/api").Counter;
+        circuitState: import("@opentelemetry/api").ObservableGauge;
+    };
+    setCircuitState: (session: string, state: string) => void;
+} | null;

package/types/validation/safety.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Check a JSON Schema for safety constraints.
+ * @param {Record<string, unknown>} schema - JSON Schema to inspect.
+ * @param {{ maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number }} config - Safety limits.
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+export function checkSchemaSafety(schema: Record<string, unknown>, config: {
+    maxSchemaDepth: number;
+    maxSchemaSize: number;
+    maxPatternLength: number;
+}): {
+    safe: boolean;
+    reason?: string;
+};

package/types/validation/trust.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Determine whether schemas from a session should be trusted.
+ * @param {import('@mcp-layer/session').Session} session - MCP session to evaluate.
+ * @param {'auto' | true | false} policy - Trust policy.
+ * @returns {boolean}
+ */
+export function shouldTrustSchemas(session: any, policy: "auto" | true | false): boolean;

package/types/validation/validator.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Create a schema validator instance.
+ * @param {{ trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }} config - Validation configuration.
+ * @param {import('@mcp-layer/session').Session} session - MCP session.
+ * @returns {SchemaValidator}
+ */
+export function createValidator(config: {
+    trustSchemas: "auto" | true | false;
+    maxSchemaDepth: number;
+    maxSchemaSize: number;
+    maxPatternLength: number;
+    maxToolNameLength: number;
+    maxTemplateParamLength: number;
+}, session: any): SchemaValidator;
+/**
+ * Schema validator for MCP tool and prompt inputs.
+ */
+export class SchemaValidator {
+    /**
+     * @param {{ trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }} config - Validation configuration.
+     * @param {import('@mcp-layer/session').Session} session - MCP session.
+     */
+    constructor(config: {
+        trustSchemas: "auto" | true | false;
+        maxSchemaDepth: number;
+        maxSchemaSize: number;
+        maxPatternLength: number;
+        maxToolNameLength: number;
+        maxTemplateParamLength: number;
+    }, session: any);
+    /**
+     * Register a tool schema for validation.
+     * @param {string} name - Tool name.
+     * @param {Record<string, unknown> | undefined} schema - JSON Schema for input.
+     * @returns {{ success: boolean, error?: string, skipped?: boolean, reason?: string }}
+     */
+    registerToolSchema(name: string, schema: Record<string, unknown> | undefined): {
+        success: boolean;
+        error?: string;
+        skipped?: boolean;
+        reason?: string;
+    };
+    /**
+     * Register a prompt schema for validation.
+     * @param {string} name - Prompt name.
+     * @param {Record<string, unknown> | undefined} schema - JSON Schema for input.
+     * @returns {{ success: boolean, error?: string, skipped?: boolean, reason?: string }}
+     */
+    registerPromptSchema(name: string, schema: Record<string, unknown> | undefined): {
+        success: boolean;
+        error?: string;
+        skipped?: boolean;
+        reason?: string;
+    };
+    /**
+     * Validate a request payload against a registered schema.
+     * @param {'tool' | 'prompt'} type - Schema type.
+     * @param {string} name - Tool or prompt name.
+     * @param {unknown} input - Request payload.
+     * @returns {{ valid: boolean, errors?: Array<{ path: string, keyword?: string, message?: string, params?: Record<string, unknown> }> }}
+     */
+    validate(type: "tool" | "prompt", name: string, input: unknown): {
+        valid: boolean;
+        errors?: Array<{
+            path: string;
+            keyword?: string;
+            message?: string;
+            params?: Record<string, unknown>;
+        }>;
+    };
+    #private;
+}

package/types/version.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Derive an API version prefix from MCP server info.
+ * @param {{ version?: string } | undefined} info - MCP server info object.
+ * @returns {string}
+ */
+export function deriveApiVersion(info: {
+    version?: string;
+} | undefined): string;
+/**
+ * Resolve a route prefix for a runtime context.
+ * @param {string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string) | undefined} prefixOption - Prefix option.
+ * @param {string} version - API version.
+ * @param {Record<string, unknown> | undefined} info - Server info.
+ * @param {string} name - Session name.
+ * @returns {string}
+ */
+export function resolvePrefix(prefixOption: string | ((version: string, info: Record<string, unknown> | undefined, name: string) => string) | undefined, version: string, info: Record<string, unknown> | undefined, name: string): string;