@casys/mcp-server 0.8.0

package/src/middleware/backpressure.ts

@@ -0,0 +1,36 @@
+/**
+ * Backpressure middleware.
+ *
+ * Controls concurrent execution using RequestQueue.
+ * Acquires a slot before calling next(), releases after.
+ *
+ * @module lib/server/middleware/backpressure
+ */
+
+import type { RequestQueue } from "../concurrency/request-queue.js";
+import type { Middleware } from "./types.js";
+
+/**
+ * Create a backpressure middleware.
+ *
+ * Wraps the downstream pipeline in acquire/release:
+ * ```
+ * acquire() → next() → release()
+ * ```
+ *
+ * The slot is always released, even if an error occurs.
+ *
+ * @param queue - RequestQueue instance with configured concurrency limits
+ */
+export function createBackpressureMiddleware(
+  queue: RequestQueue,
+): Middleware {
+  return async (_ctx, next) => {
+    await queue.acquire();
+    try {
+      return await next();
+    } finally {
+      queue.release();
+    }
+  };
+}

package/src/middleware/mod.ts

@@ -0,0 +1,21 @@
+/**
+ * Middleware module for ConcurrentMCPServer.
+ *
+ * @module lib/server/middleware
+ */
+
+// Types
+export type {
+  Middleware,
+  MiddlewareContext,
+  MiddlewareResult,
+  NextFunction,
+} from "./types.js";
+
+// Runner
+export { createMiddlewareRunner } from "./runner.js";
+
+// Built-in middlewares
+export { createRateLimitMiddleware } from "./rate-limit.js";
+export { createValidationMiddleware } from "./validation.js";
+export { createBackpressureMiddleware } from "./backpressure.js";

package/src/middleware/rate-limit.ts

@@ -0,0 +1,45 @@
+/**
+ * Rate limiting middleware.
+ *
+ * Extracted from ConcurrentMCPServer's inline rate limit logic.
+ *
+ * @module lib/server/middleware/rate-limit
+ */
+
+import type { RateLimiter } from "../concurrency/rate-limiter.js";
+import type { RateLimitOptions } from "../types.js";
+import type { Middleware } from "./types.js";
+
+/**
+ * Create a rate limiting middleware.
+ *
+ * Behavior depends on `options.onLimitExceeded`:
+ * - `'reject'`: throws immediately when limit is exceeded
+ * - `'wait'` (default): waits with backoff until a slot is available
+ *
+ * @param limiter - RateLimiter instance
+ * @param options - Rate limit configuration
+ */
+export function createRateLimitMiddleware(
+  limiter: RateLimiter,
+  options: RateLimitOptions,
+): Middleware {
+  return async (ctx, next) => {
+    const key =
+      options.keyExtractor?.({ toolName: ctx.toolName, args: ctx.args }) ??
+        "default";
+
+    if (options.onLimitExceeded === "reject") {
+      if (!limiter.checkLimit(key)) {
+        const waitTime = limiter.getTimeUntilSlot(key);
+        throw new Error(
+          `Rate limit exceeded. Retry after ${Math.ceil(waitTime / 1000)}s`,
+        );
+      }
+    } else {
+      await limiter.waitForSlot(key);
+    }
+
+    return next();
+  };
+}

package/src/middleware/runner.ts

@@ -0,0 +1,63 @@
+/**
+ * Middleware pipeline runner.
+ *
+ * Composes an array of middlewares into a single callable function
+ * using the onion model: each middleware wraps the next.
+ *
+ * @module lib/server/middleware/runner
+ */
+
+import type {
+  Middleware,
+  MiddlewareContext,
+  MiddlewareResult,
+} from "./types.js";
+
+/**
+ * Create a middleware runner that composes middlewares + a final handler.
+ *
+ * Execution order (onion model):
+ * ```
+ * m1-before → m2-before → handler → m2-after → m1-after
+ * ```
+ *
+ * @param middlewares - Array of middleware functions to execute in order
+ * @param handler - Final handler (the tool execution)
+ * @returns A function that runs the full pipeline for a given context
+ *
+ * @example
+ * ```typescript
+ * const run = createMiddlewareRunner(
+ *   [rateLimitMiddleware, validationMiddleware],
+ *   async (ctx) => toolHandler(ctx.args),
+ * );
+ * const result = await run({ toolName: "my_tool", args: { x: 1 } });
+ * ```
+ */
+export function createMiddlewareRunner(
+  middlewares: Middleware[],
+  handler: (ctx: MiddlewareContext) => Promise<MiddlewareResult>,
+): (ctx: MiddlewareContext) => Promise<MiddlewareResult> {
+  return (ctx: MiddlewareContext) => {
+    let index = 0;
+    let handlerCalled = false;
+
+    // deno-lint-ignore require-await
+    const next = async (): Promise<MiddlewareResult> => {
+      if (index < middlewares.length) {
+        const middleware = middlewares[index++];
+        return middleware(ctx, next);
+      }
+      if (handlerCalled) {
+        throw new Error(
+          "[MiddlewareRunner] next() called after pipeline already completed. " +
+            "A middleware may be calling next() multiple times.",
+        );
+      }
+      handlerCalled = true;
+      return handler(ctx);
+    };
+
+    return next();
+  };
+}

package/src/middleware/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Middleware pipeline types for ConcurrentMCPServer.
+ *
+ * Provides an onion-model middleware system (similar to Koa/Hono)
+ * where each middleware wraps the next, enabling before/after logic.
+ *
+ * @module lib/server/middleware/types
+ */
+
+/**
+ * Context passed through the middleware pipeline.
+ * Each middleware can read and enrich the context.
+ */
+export interface MiddlewareContext {
+  /** Name of the tool being called */
+  toolName: string;
+
+  /** Tool arguments */
+  args: Record<string, unknown>;
+
+  /** HTTP request (only present for HTTP transport, undefined for STDIO) */
+  request?: Request;
+
+  /** Session ID (only present for HTTP transport) */
+  sessionId?: string;
+
+  /** Extensible by middlewares (e.g., authInfo added by auth middleware) */
+  [key: string]: unknown;
+}
+
+/**
+ * Result returned by a middleware or the final handler.
+ */
+export type MiddlewareResult = unknown;
+
+/**
+ * Function to invoke the next middleware in the chain.
+ */
+export type NextFunction = () => Promise<MiddlewareResult>;
+
+/**
+ * A middleware function.
+ *
+ * Receives the context and a `next()` function to call the next middleware.
+ * Can short-circuit the pipeline by not calling `next()`.
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: Middleware = async (ctx, next) => {
+ *   console.log(`Before: ${ctx.toolName}`);
+ *   const result = await next();
+ *   console.log(`After: ${ctx.toolName}`);
+ *   return result;
+ * };
+ * ```
+ */
+export type Middleware = (
+  ctx: MiddlewareContext,
+  next: NextFunction,
+) => Promise<MiddlewareResult>;

package/src/middleware/validation.ts

@@ -0,0 +1,28 @@
+/**
+ * Schema validation middleware.
+ *
+ * Validates tool arguments against JSON Schema before execution.
+ *
+ * @module lib/server/middleware/validation
+ */
+
+import type { SchemaValidator } from "../validation/schema-validator.js";
+import type { Middleware } from "./types.js";
+
+/**
+ * Create a schema validation middleware.
+ *
+ * Validates `ctx.args` against the registered schema for `ctx.toolName`.
+ * Throws with a descriptive error if validation fails.
+ *
+ * @param validator - SchemaValidator instance with pre-registered schemas
+ */
+export function createValidationMiddleware(
+  validator: SchemaValidator,
+): Middleware {
+  // deno-lint-ignore require-await
+  return async (ctx, next) => {
+    validator.validateOrThrow(ctx.toolName, ctx.args);
+    return next();
+  };
+}

package/src/observability/metrics.ts

@@ -0,0 +1,378 @@
+/**
+ * Server Metrics Collector for @casys/mcp-server
+ *
+ * In-memory counters, histograms, and gauges with Prometheus text format export.
+ * Designed to be embedded in ConcurrentMCPServer — no external dependencies.
+ *
+ * @module lib/server/observability/metrics
+ */
+
+/**
+ * Histogram bucket
+ */
+interface HistogramBucket {
+  le: number;
+  count: number;
+}
+
+/**
+ * Latency histogram with cumulative buckets
+ */
+interface Histogram {
+  buckets: HistogramBucket[];
+  sum: number;
+  count: number;
+}
+
+/**
+ * Default histogram buckets (milliseconds)
+ */
+const DEFAULT_BUCKETS = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+
+function createHistogram(buckets: number[] = DEFAULT_BUCKETS): Histogram {
+  return {
+    buckets: buckets.map((le) => ({ le, count: 0 })),
+    sum: 0,
+    count: 0,
+  };
+}
+
+function observeHistogram(histogram: Histogram, value: number): void {
+  histogram.sum += value;
+  histogram.count++;
+  for (const bucket of histogram.buckets) {
+    if (value <= bucket.le) {
+      bucket.count++;
+    }
+  }
+}
+
+/**
+ * Metrics snapshot returned by getMetrics()
+ */
+export interface ServerMetricsSnapshot {
+  counters: {
+    tool_calls_total: number;
+    tool_calls_success: number;
+    tool_calls_failed: number;
+    requests_rate_limited: number;
+    requests_rejected_backpressure: number;
+    auth_success: number;
+    auth_failed: number;
+    auth_cache_hits: number;
+    sessions_created: number;
+    sessions_expired: number;
+  };
+  histograms: {
+    tool_call_duration_ms: Histogram;
+  };
+  gauges: {
+    active_requests: number;
+    queued_requests: number;
+    active_sessions: number;
+    sse_clients: number;
+    rate_limiter_keys: number;
+  };
+  collected_at: number;
+  uptime_seconds: number;
+}
+
+/**
+ * Tool call metrics by tool name
+ */
+interface PerToolMetrics {
+  calls: number;
+  success: number;
+  failed: number;
+  totalDurationMs: number;
+}
+
+/**
+ * Server metrics collector.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new ServerMetrics();
+ * metrics.recordToolCall("my_tool", true, 42);
+ * console.log(metrics.toPrometheusFormat());
+ * ```
+ */
+export class ServerMetrics {
+  private startTime = Date.now();
+
+  // Counters
+  private toolCallsTotal = 0;
+  private toolCallsSuccess = 0;
+  private toolCallsFailed = 0;
+  private requestsRateLimited = 0;
+  private requestsRejectedBackpressure = 0;
+  private authSuccess = 0;
+  private authFailed = 0;
+  private authCacheHits = 0;
+  private sessionsCreated = 0;
+  private sessionsExpired = 0;
+
+  // Histogram
+  private toolCallDuration = createHistogram();
+
+  // Per-tool breakdown
+  private perTool = new Map<string, PerToolMetrics>();
+
+  // Gauges (set externally via setGauge)
+  private activeRequests = 0;
+  private queuedRequests = 0;
+  private activeSessions = 0;
+  private sseClients = 0;
+  private rateLimiterKeys = 0;
+
+  /**
+   * Record a completed tool call
+   */
+  recordToolCall(toolName: string, success: boolean, durationMs: number): void {
+    this.toolCallsTotal++;
+    if (success) {
+      this.toolCallsSuccess++;
+    } else {
+      this.toolCallsFailed++;
+    }
+    observeHistogram(this.toolCallDuration, durationMs);
+
+    // Per-tool
+    let pt = this.perTool.get(toolName);
+    if (!pt) {
+      pt = { calls: 0, success: 0, failed: 0, totalDurationMs: 0 };
+      this.perTool.set(toolName, pt);
+    }
+    pt.calls++;
+    if (success) pt.success++;
+    else pt.failed++;
+    pt.totalDurationMs += durationMs;
+  }
+
+  recordRateLimited(): void {
+    this.requestsRateLimited++;
+  }
+
+  recordBackpressureRejected(): void {
+    this.requestsRejectedBackpressure++;
+  }
+
+  recordAuth(success: boolean): void {
+    if (success) this.authSuccess++;
+    else this.authFailed++;
+  }
+
+  recordAuthCacheHit(): void {
+    this.authCacheHits++;
+  }
+
+  recordSessionCreated(): void {
+    this.sessionsCreated++;
+  }
+
+  recordSessionExpired(count: number): void {
+    this.sessionsExpired += count;
+  }
+
+  /**
+   * Update gauge values (called periodically or on-demand)
+   */
+  setGauges(gauges: {
+    activeRequests?: number;
+    queuedRequests?: number;
+    activeSessions?: number;
+    sseClients?: number;
+    rateLimiterKeys?: number;
+  }): void {
+    if (gauges.activeRequests !== undefined) {
+      this.activeRequests = gauges.activeRequests;
+    }
+    if (gauges.queuedRequests !== undefined) {
+      this.queuedRequests = gauges.queuedRequests;
+    }
+    if (gauges.activeSessions !== undefined) {
+      this.activeSessions = gauges.activeSessions;
+    }
+    if (gauges.sseClients !== undefined) this.sseClients = gauges.sseClients;
+    if (gauges.rateLimiterKeys !== undefined) {
+      this.rateLimiterKeys = gauges.rateLimiterKeys;
+    }
+  }
+
+  /**
+   * Get current metrics snapshot
+   */
+  getSnapshot(): ServerMetricsSnapshot {
+    return {
+      counters: {
+        tool_calls_total: this.toolCallsTotal,
+        tool_calls_success: this.toolCallsSuccess,
+        tool_calls_failed: this.toolCallsFailed,
+        requests_rate_limited: this.requestsRateLimited,
+        requests_rejected_backpressure: this.requestsRejectedBackpressure,
+        auth_success: this.authSuccess,
+        auth_failed: this.authFailed,
+        auth_cache_hits: this.authCacheHits,
+        sessions_created: this.sessionsCreated,
+        sessions_expired: this.sessionsExpired,
+      },
+      histograms: {
+        tool_call_duration_ms: { ...this.toolCallDuration },
+      },
+      gauges: {
+        active_requests: this.activeRequests,
+        queued_requests: this.queuedRequests,
+        active_sessions: this.activeSessions,
+        sse_clients: this.sseClients,
+        rate_limiter_keys: this.rateLimiterKeys,
+      },
+      collected_at: Date.now(),
+      uptime_seconds: Math.floor((Date.now() - this.startTime) / 1000),
+    };
+  }
+
+  /**
+   * Prometheus text format export
+   */
+  toPrometheusFormat(prefix = "mcp_server"): string {
+    const m = this.getSnapshot();
+    const lines: string[] = [];
+
+    // --- Counters ---
+    const counter = (name: string, help: string, value: number) => {
+      lines.push(`# HELP ${prefix}_${name} ${help}`);
+      lines.push(`# TYPE ${prefix}_${name} counter`);
+      lines.push(`${prefix}_${name} ${value}`);
+    };
+
+    counter(
+      "tool_calls_total",
+      "Total tool calls",
+      m.counters.tool_calls_total,
+    );
+    counter(
+      "tool_calls_success_total",
+      "Successful tool calls",
+      m.counters.tool_calls_success,
+    );
+    counter(
+      "tool_calls_failed_total",
+      "Failed tool calls",
+      m.counters.tool_calls_failed,
+    );
+    counter(
+      "requests_rate_limited_total",
+      "Requests rejected by rate limiter",
+      m.counters.requests_rate_limited,
+    );
+    counter(
+      "requests_backpressure_total",
+      "Requests rejected by backpressure",
+      m.counters.requests_rejected_backpressure,
+    );
+    counter(
+      "auth_success_total",
+      "Successful auth verifications",
+      m.counters.auth_success,
+    );
+    counter(
+      "auth_failed_total",
+      "Failed auth verifications",
+      m.counters.auth_failed,
+    );
+    counter(
+      "auth_cache_hits_total",
+      "Auth token cache hits",
+      m.counters.auth_cache_hits,
+    );
+    counter(
+      "sessions_created_total",
+      "Sessions created",
+      m.counters.sessions_created,
+    );
+    counter(
+      "sessions_expired_total",
+      "Sessions expired by cleanup",
+      m.counters.sessions_expired,
+    );
+
+    // --- Per-tool counters ---
+    lines.push(`# HELP ${prefix}_tool_calls_by_name Tool calls by tool name`);
+    lines.push(`# TYPE ${prefix}_tool_calls_by_name counter`);
+    for (const [name, pt] of this.perTool) {
+      lines.push(
+        `${prefix}_tool_calls_by_name{tool="${name}",status="success"} ${pt.success}`,
+      );
+      lines.push(
+        `${prefix}_tool_calls_by_name{tool="${name}",status="failed"} ${pt.failed}`,
+      );
+    }
+
+    // --- Histogram ---
+    const h = m.histograms.tool_call_duration_ms;
+    lines.push(
+      `# HELP ${prefix}_tool_call_duration_ms Tool call duration in milliseconds`,
+    );
+    lines.push(`# TYPE ${prefix}_tool_call_duration_ms histogram`);
+    for (const bucket of h.buckets) {
+      lines.push(
+        `${prefix}_tool_call_duration_ms_bucket{le="${bucket.le}"} ${bucket.count}`,
+      );
+    }
+    lines.push(`${prefix}_tool_call_duration_ms_bucket{le="+Inf"} ${h.count}`);
+    lines.push(`${prefix}_tool_call_duration_ms_sum ${h.sum}`);
+    lines.push(`${prefix}_tool_call_duration_ms_count ${h.count}`);
+
+    // --- Gauges ---
+    const gauge = (name: string, help: string, value: number) => {
+      lines.push(`# HELP ${prefix}_${name} ${help}`);
+      lines.push(`# TYPE ${prefix}_${name} gauge`);
+      lines.push(`${prefix}_${name} ${value}`);
+    };
+
+    gauge(
+      "active_requests",
+      "Currently executing requests",
+      m.gauges.active_requests,
+    );
+    gauge(
+      "queued_requests",
+      "Requests waiting in queue",
+      m.gauges.queued_requests,
+    );
+    gauge("active_sessions", "Active HTTP sessions", m.gauges.active_sessions);
+    gauge("sse_clients", "Connected SSE clients", m.gauges.sse_clients);
+    gauge(
+      "rate_limiter_keys",
+      "Tracked rate limiter keys",
+      m.gauges.rate_limiter_keys,
+    );
+    gauge("uptime_seconds", "Server uptime in seconds", m.uptime_seconds);
+
+    return lines.join("\n") + "\n";
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset(): void {
+    this.toolCallsTotal = 0;
+    this.toolCallsSuccess = 0;
+    this.toolCallsFailed = 0;
+    this.requestsRateLimited = 0;
+    this.requestsRejectedBackpressure = 0;
+    this.authSuccess = 0;
+    this.authFailed = 0;
+    this.authCacheHits = 0;
+    this.sessionsCreated = 0;
+    this.sessionsExpired = 0;
+    this.toolCallDuration = createHistogram();
+    this.perTool.clear();
+    this.activeRequests = 0;
+    this.queuedRequests = 0;
+    this.activeSessions = 0;
+    this.sseClients = 0;
+    this.rateLimiterKeys = 0;
+    this.startTime = Date.now();
+  }
+}

package/src/observability/mod.ts

@@ -0,0 +1,20 @@
+/**
+ * Observability module for @casys/mcp-server
+ *
+ * - OTel tracing (spans on tool calls, auth events)
+ * - Metrics collection (counters, histograms, gauges)
+ * - Prometheus text format export
+ *
+ * @module lib/server/observability
+ */
+
+export {
+  endToolCallSpan,
+  getServerTracer,
+  isOtelEnabled,
+  recordAuthEvent,
+  startToolCallSpan,
+  type ToolCallSpanAttributes,
+} from "./otel.js";
+
+export { ServerMetrics, type ServerMetricsSnapshot } from "./metrics.js";