@mcp-layer/gateway 0.1.0

package/src/telemetry/index.js

@@ -0,0 +1,77 @@
+import { createRequire } from 'node:module';
+
+/**
+ * Load the OpenTelemetry API module dynamically.
+ * @returns {import('@opentelemetry/api')} OTel API module.
+ */
+function loadOtel() {
+  const req = createRequire(import.meta.url);
+  return req('@opentelemetry/api');
+}
+
+/**
+ * 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) {
+  const enabled = config.enabled ?? Boolean(config.api);
+  if (!enabled) return null;
+  const prefix = typeof config.metricPrefix === 'string' && config.metricPrefix.length > 0
+    ? config.metricPrefix
+    : 'adapter';
+
+  const otel = config.api ?? loadOtel();
+  const tracer = otel.trace.getTracer(config.serviceName, '1.0.0');
+  const meter = otel.metrics.getMeter(config.serviceName, '1.0.0');
+
+  const callDuration = meter.createHistogram('mcp.call.duration', {
+    description: 'Duration of MCP calls',
+    unit: 'ms'
+  });
+
+  const callErrors = meter.createCounter('mcp.call.errors', {
+    description: 'Number of MCP call errors'
+  });
+
+  const validationErrors = meter.createCounter(`${prefix}.validation.errors`, {
+    description: 'Number of validation errors'
+  });
+
+  const states = new Map();
+  const circuitState = meter.createObservableGauge(`${prefix}.circuit.state`, {
+    description: 'Circuit breaker state'
+  });
+
+  circuitState.addCallback(function observe(obs) {
+    for (const [session, value] of states.entries()) {
+      obs.observe(value, { session });
+    }
+  });
+
+  /**
+   * Update circuit breaker state metric.
+   * @param {string} session - Session name.
+   * @param {string} state - Circuit breaker state.
+   * @returns {void}
+   */
+  function setCircuitState(session, state) {
+    const map = { open: 2, half_open: 1, closed: 0 };
+    const value = Object.hasOwn(map, state) ? map[state] : 0;
+    states.set(session, value);
+  }
+
+  return {
+    tracer,
+    meter,
+    context: otel.context,
+    propagation: otel.propagation,
+    metrics: {
+      callDuration,
+      callErrors,
+      validationErrors,
+      circuitState
+    },
+    setCircuitState
+  };
+}

package/src/validation/safety.js

@@ -0,0 +1,73 @@
+import traverse from 'json-schema-traverse';
+import safeRegex from 'safe-regex2';
+
+/**
+ * Check a regex pattern for safety.
+ * @param {string} pattern - Regex pattern string.
+ * @param {number} maxPatternLength - Maximum allowed pattern length.
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+function checkPattern(pattern, maxPatternLength) {
+  if (pattern.length > maxPatternLength) {
+    return { safe: false, reason: `Regex pattern exceeds maximum length of ${maxPatternLength}` };
+  }
+
+  if (!safeRegex(pattern)) {
+    return { safe: false, reason: 'Schema contains potentially unsafe regex pattern' };
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Compute the maximum depth for a JSON Schema tree.
+ * @param {Record<string, unknown>} schema - JSON Schema to traverse.
+ * @returns {number}
+ */
+function maxdepth(schema) {
+  let max = 0;
+  const seen = new WeakMap();
+
+  traverse(schema, function visit(node, _jsonPtr, _root, _parentJsonPtr, _parentKeyword, parentSchema) {
+    if (!node || typeof node !== 'object') return;
+    const parentDepth = parentSchema && seen.has(parentSchema) ? seen.get(parentSchema) : 0;
+    const depth = parentSchema ? parentDepth + 1 : 0;
+    seen.set(node, depth);
+    if (depth > max) max = depth;
+  });
+
+  return max;
+}
+
+/**
+ * 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, config) {
+  const depth = maxdepth(schema);
+  if (depth > config.maxSchemaDepth) {
+    return { safe: false, reason: `Schema exceeds maximum depth of ${config.maxSchemaDepth}` };
+  }
+
+  const size = JSON.stringify(schema).length;
+  if (size > config.maxSchemaSize) {
+    return { safe: false, reason: `Schema exceeds maximum size of ${config.maxSchemaSize} bytes` };
+  }
+
+  let patternError;
+  traverse(schema, function visit(node) {
+    if (patternError || !node || typeof node !== 'object') return;
+    if (typeof node.pattern === 'string') {
+      const check = checkPattern(node.pattern, config.maxPatternLength);
+      if (!check.safe) patternError = check.reason;
+    }
+  });
+
+  if (patternError) {
+    return { safe: false, reason: patternError };
+  }
+
+  return { safe: true };
+}

package/src/validation/trust.js

@@ -0,0 +1,14 @@
+/**
+ * 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, policy) {
+  if (policy === true) return true;
+  if (policy === false) return false;
+
+  const type = session?.transport?.constructor?.name;
+  const remote = type === 'StreamableHTTPClientTransport';
+  return !remote;
+}

package/src/validation/validator.js

@@ -0,0 +1,147 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { shouldTrustSchemas } from './trust.js';
+import { checkSchemaSafety } from './safety.js';
+
+/**
+ * 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, session) {
+    this.#config = config;
+    this.#trusted = shouldTrustSchemas(session, config.trustSchemas);
+    this.#ajv = new Ajv({
+      allErrors: true,
+      strict: this.#trusted ? false : 'log',
+      validateFormats: true,
+      coerceTypes: 'array',
+      removeAdditional: true
+    });
+    addFormats(this.#ajv);
+  }
+
+  /**
+   * 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, schema) {
+    return this.#registerSchema(`tool:${name}`, schema);
+  }
+
+  /**
+   * 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, schema) {
+    return this.#registerSchema(`prompt:${name}`, schema);
+  }
+
+  /**
+   * 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, name, input) {
+    const key = `${type}:${name}`;
+    const fn = this.#validators.get(key);
+
+    if (fn === undefined) {
+      return {
+        valid: false,
+        errors: [{ path: '', message: `Unknown ${type}: ${name}` }]
+      };
+    }
+
+    if (fn === null) {
+      return { valid: true };
+    }
+
+    const ok = fn(input);
+    if (ok) {
+      return { valid: true };
+    }
+
+    const errs = [];
+    const list = Array.isArray(fn.errors) ? fn.errors : [];
+    for (const err of list) {
+      errs.push({
+        path: err.instancePath || '/',
+        keyword: err.keyword,
+        message: err.message,
+        params: err.params
+      });
+    }
+
+    return { valid: false, errors: errs };
+  }
+
+  /**
+   * Register and compile a schema into an Ajv validator.
+   * @param {string} key - Internal map key.
+   * @param {Record<string, unknown> | undefined} schema - JSON Schema.
+   * @returns {{ success: boolean, error?: string, skipped?: boolean, reason?: string }}
+   */
+  #registerSchema(key, schema) {
+    if (!schema) {
+      this.#validators.set(key, null);
+      return { success: true };
+    }
+
+    if (!this.#trusted) {
+      const safety = checkSchemaSafety(schema, this.#config);
+      if (!safety.safe) {
+        this.#validators.set(key, null);
+        return { success: true, skipped: true, reason: safety.reason };
+      }
+    }
+
+    try {
+      const fn = this.#ajv.compile(schema);
+      this.#validators.set(key, fn);
+      return { success: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { success: false, error: `Schema compilation failed: ${message}` };
+    }
+  }
+
+  /**
+   * @type {Map<string, import('ajv').ValidateFunction | null>}
+   */
+  #validators = new Map();
+
+  /**
+   * @type {Ajv}
+   */
+  #ajv;
+
+  /**
+   * @type {{ trustSchemas: 'auto' | true | false, maxSchemaDepth: number, maxSchemaSize: number, maxPatternLength: number, maxToolNameLength: number, maxTemplateParamLength: number }}
+   */
+  #config;
+
+  /**
+   * @type {boolean}
+   */
+  #trusted;
+}
+
+/**
+ * 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, session) {
+  return new SchemaValidator(config, session);
+}

package/src/version.js

@@ -0,0 +1,31 @@
+/**
+ * Derive an API version prefix from MCP server info.
+ * @param {{ version?: string } | undefined} info - MCP server info object.
+ * @returns {string}
+ */
+export function deriveApiVersion(info) {
+  if (!info || !info.version) return 'v0';
+
+  const version = String(info.version).replace(/^v/, '');
+  const semver = version.match(/^(\d+)/);
+  if (semver) return `v${semver[1]}`;
+
+  const date = version.match(/^(\d{4})-/);
+  if (date) return `v${date[1]}`;
+
+  return 'v0';
+}
+
+/**
+ * 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, version, info, name) {
+  if (typeof prefixOption === 'function') return prefixOption(version, info, name);
+  if (typeof prefixOption === 'string') return prefixOption;
+  return `/${version}`;
+}