@casys/mcp-server 0.2.1

package/src/observability/otel.ts

@@ -0,0 +1,109 @@
+/**
+ * OpenTelemetry Integration for @casys/mcp-server
+ *
+ * Provides tracing for tool calls, auth, and middleware pipeline.
+ *
+ * Enable with:
+ * - Deno: OTEL_DENO=true deno run --unstable-otel ...
+ * - Node.js: OTEL_ENABLED=true node ...
+ *
+ * @module lib/server/observability/otel
+ */
+
+import {
+  type Span,
+  SpanStatusCode,
+  trace,
+  type Tracer,
+} from "@opentelemetry/api";
+import { env } from "../runtime/runtime.js";
+
+let serverTracer: Tracer | null = null;
+
+/**
+ * Get or create the MCP server tracer
+ */
+export function getServerTracer(): Tracer {
+  if (!serverTracer) {
+    serverTracer = trace.getTracer("mcp.server", "0.8.0");
+  }
+  return serverTracer;
+}
+
+/**
+ * Span attributes for MCP tool calls
+ */
+export interface ToolCallSpanAttributes {
+  "mcp.tool.name": string;
+  "mcp.server.name"?: string;
+  "mcp.transport"?: string;
+  "mcp.session.id"?: string;
+  "mcp.auth.subject"?: string;
+  "mcp.auth.client_id"?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * Start a span for a tool call.
+ * Caller MUST call span.end() when done.
+ */
+export function startToolCallSpan(
+  toolName: string,
+  attributes: ToolCallSpanAttributes,
+): Span {
+  const tracer = getServerTracer();
+  return tracer.startSpan(`mcp.tool.call ${toolName}`, { attributes });
+}
+
+/**
+ * Record a tool call result on a span and end it.
+ */
+export function endToolCallSpan(
+  span: Span,
+  success: boolean,
+  durationMs: number,
+  error?: string,
+): void {
+  span.setAttribute("mcp.tool.duration_ms", durationMs);
+  span.setAttribute("mcp.tool.success", success);
+
+  if (error) {
+    span.setAttribute("mcp.tool.error", error);
+    span.recordException(new Error(error));
+  }
+
+  span.setStatus({
+    code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR,
+    message: error,
+  });
+  span.end();
+}
+
+/**
+ * Record an auth event as a fire-and-forget span.
+ */
+export function recordAuthEvent(
+  event: "verify" | "reject" | "cache_hit",
+  attributes: Record<string, string | number | boolean | undefined>,
+): void {
+  const tracer = getServerTracer();
+  tracer.startActiveSpan(`mcp.auth.${event}`, { attributes }, (span) => {
+    span.setStatus({
+      code: event === "reject" ? SpanStatusCode.ERROR : SpanStatusCode.OK,
+    });
+    span.end();
+  });
+}
+
+/**
+ * Check if OTEL is enabled.
+ * Deno: OTEL_DENO=true  |  Node.js: OTEL_ENABLED=true
+ */
+export function isOtelEnabled(): boolean {
+  try {
+    return env("OTEL_DENO") === "true" || env("OTEL_ENABLED") === "true";
+  } catch {
+    // Deno without --allow-env throws NotCapable
+    return false;
+  }
+}

package/src/runtime/runtime.ts

@@ -0,0 +1,220 @@
+// deno-lint-ignore-file no-process-global no-node-globals
+/**
+ * Runtime adapter — Node.js implementation
+ *
+ * Implements the RuntimePort contract for Node.js.
+ * Drop-in replacement for runtime.ts (Deno) — swapped by build script.
+ *
+ * @see runtime-types.ts for the port contract
+ * @module lib/server/runtime.node
+ */
+
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import type {
+  FetchHandler,
+  RuntimePort,
+  ServeHandle,
+  ServeOptions,
+} from "./types.js";
+
+// Re-export types so consumers import from a single module
+export type { FetchHandler, ServeHandle, ServeOptions } from "./types.js";
+
+class PayloadTooLargeError extends Error {
+  constructor(maxBytes: number) {
+    super(`Payload too large. Max ${maxBytes} bytes.`);
+    this.name = "PayloadTooLargeError";
+  }
+}
+
+/**
+ * Get an environment variable.
+ */
+export function env(key: string): string | undefined {
+  return process.env[key];
+}
+
+/**
+ * Read a UTF-8 text file.
+ * Returns null if the file does not exist.
+ */
+export async function readTextFile(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch (err: unknown) {
+    if (
+      err && typeof err === "object" && "code" in err && err.code === "ENOENT"
+    ) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Start an HTTP server with a fetch-style handler.
+ * Uses node:http with a Request/Response adapter (compatible with Hono).
+ */
+export function serve(
+  options: ServeOptions,
+  handler: FetchHandler,
+): ServeHandle {
+  const hostname = options.hostname ?? "0.0.0.0";
+  const maxBodyBytes = options.maxBodyBytes ?? null;
+
+  const server = createServer(async (nodeReq, nodeRes) => {
+    try {
+      const contentLength = nodeReq.headers["content-length"];
+      if (maxBodyBytes !== null && contentLength) {
+        const length = Array.isArray(contentLength)
+          ? Number(contentLength[0])
+          : Number(contentLength);
+        if (!Number.isNaN(length) && length > maxBodyBytes) {
+          nodeRes.writeHead(413);
+          nodeRes.end(`Payload too large. Max ${maxBodyBytes} bytes.`);
+          return;
+        }
+      }
+
+      // Convert Node.js IncomingMessage → Web Request
+      // Prefer Host header (correct behind reverse proxy) over bound hostname
+      const host = nodeReq.headers.host ?? `${hostname}:${options.port}`;
+      const url = `http://${host}${nodeReq.url ?? "/"}`;
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(nodeReq.headers)) {
+        if (value) {
+          if (Array.isArray(value)) {
+            for (const v of value) headers.append(key, v);
+          } else {
+            headers.set(key, value);
+          }
+        }
+      }
+
+      const body = nodeReq.method !== "GET" && nodeReq.method !== "HEAD"
+        ? await collectBody(nodeReq, maxBodyBytes)
+        : undefined;
+
+      const request = new Request(url, {
+        method: nodeReq.method ?? "GET",
+        headers,
+        body,
+        // @ts-ignore: duplex needed for streaming requests in Node 20+
+        duplex: body ? "half" : undefined,
+      });
+
+      // Call the fetch handler (Hono, etc.)
+      const response = await handler(request);
+
+      // Convert Web Response → Node.js ServerResponse
+      // Use raw header entries to preserve duplicate Set-Cookie headers
+      const resHeaders: Record<string, string | string[]> = {};
+      response.headers.forEach((value, key) => {
+        const existing = resHeaders[key];
+        if (existing !== undefined) {
+          resHeaders[key] = Array.isArray(existing)
+            ? [...existing, value]
+            : [existing, value];
+        } else {
+          resHeaders[key] = value;
+        }
+      });
+      nodeRes.writeHead(response.status, resHeaders);
+
+      if (response.body) {
+        const reader = response.body.getReader();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          nodeRes.write(value);
+        }
+        nodeRes.end();
+      } else {
+        nodeRes.end();
+      }
+    } catch (err) {
+      if (err instanceof PayloadTooLargeError) {
+        if (!nodeRes.headersSent) {
+          nodeRes.writeHead(413);
+          nodeRes.end(err.message);
+        }
+        return;
+      }
+      console.error("[runtime.node] Request handler error:", err);
+      if (!nodeRes.headersSent) {
+        nodeRes.writeHead(500);
+        nodeRes.end("Internal Server Error");
+      }
+    }
+  });
+
+  server.listen(options.port, hostname, () => {
+    if (options.onListen) {
+      options.onListen({ hostname, port: options.port });
+    }
+  });
+
+  return {
+    shutdown: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}
+
+/**
+ * Unref a timer so it doesn't block process exit.
+ */
+export function unrefTimer(id: number): void {
+  // In Node.js, setTimeout returns a Timeout object (not a numeric ID).
+  // The caller passes it as `number` for Deno compat — we cast back.
+  try {
+    const timer = id as unknown as { unref?: () => void };
+    if (
+      typeof timer === "object" && timer && typeof timer.unref === "function"
+    ) {
+      timer.unref();
+    }
+  } catch (err) {
+    console.warn("[runtime.node] Failed to unref timer:", err);
+  }
+}
+
+/** Compile-time contract check — ensures this module satisfies RuntimePort */
+void ({ env, readTextFile, serve, unrefTimer } satisfies RuntimePort);
+
+// ─── Internal helpers ────────────────────────────────────
+
+/** Collect request body from Node.js IncomingMessage */
+function collectBody(
+  req: import("node:http").IncomingMessage,
+  maxBytes: number | null,
+): Promise<Uint8Array> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    let rejected = false;
+    req.on("data", (chunk: Buffer) => {
+      if (rejected) return;
+      total += chunk.length;
+      if (maxBytes !== null && total > maxBytes) {
+        rejected = true;
+        req.destroy();
+        reject(new PayloadTooLargeError(maxBytes));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (!rejected) {
+        resolve(new Uint8Array(Buffer.concat(chunks)));
+      }
+    });
+    req.on("error", (err) => {
+      if (!rejected) {
+        reject(err);
+      }
+    });
+  });
+}

package/src/runtime/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Runtime Port — platform-agnostic contract
+ *
+ * Defines the interface that both Deno (runtime.ts) and Node.js (runtime.node.ts)
+ * must implement. This is the only file consumers need to understand the API shape.
+ *
+ * Pattern: each runtime file exports module-level functions that satisfy this port.
+ * The build script swaps runtime.ts → runtime.node.ts for Node.js distribution.
+ *
+ * @module lib/server/runtime-types
+ */
+
+// ─── Environment ─────────────────────────────────────────
+
+/**
+ * Get an environment variable.
+ * Returns undefined if not set (never throws).
+ */
+export type EnvFn = (key: string) => string | undefined;
+
+// ─── File System ─────────────────────────────────────────
+
+/**
+ * Read a UTF-8 text file.
+ * Returns null if the file does not exist (no throw on ENOENT/NotFound).
+ * Throws on other errors (permission denied, etc.).
+ */
+export type ReadTextFileFn = (path: string) => Promise<string | null>;
+
+// ─── HTTP Server ─────────────────────────────────────────
+
+/** Fetch-style request handler (Web standard) */
+export type FetchHandler = (req: Request) => Response | Promise<Response>;
+
+/** Options for starting an HTTP server */
+export interface ServeOptions {
+  port: number;
+  hostname?: string;
+  onListen?: (info: { hostname: string; port: number }) => void;
+  /** Maximum request body size in bytes (optional, adapter-specific). */
+  maxBodyBytes?: number | null;
+}
+
+/** Handle returned by serve(), used to shut down the server */
+export interface ServeHandle {
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Start an HTTP server with a fetch-style handler.
+ *
+ * Deno: wraps Deno.serve()
+ * Node.js: wraps node:http.createServer() with Request/Response adapter
+ */
+export type ServeFn = (
+  options: ServeOptions,
+  handler: FetchHandler,
+) => ServeHandle;
+
+// ─── Timers ──────────────────────────────────────────────
+
+/**
+ * Unref a timer so it doesn't prevent process exit.
+ *
+ * Deno: Deno.unrefTimer(id)
+ * Node.js: timer.unref() on the Timeout object
+ */
+export type UnrefTimerFn = (id: number) => void;
+
+// ─── Port interface ──────────────────────────────────────
+
+/**
+ * Complete runtime port contract.
+ *
+ * Both runtime.ts (Deno) and runtime.node.ts (Node.js) must export
+ * functions matching these signatures. Use `satisfies RuntimePort`
+ * at the bottom of each implementation to enforce at compile time.
+ *
+ * @example
+ * ```typescript
+ * // At the bottom of runtime.ts / runtime.node.ts:
+ * export const _port = { env, readTextFile, serve, unrefTimer } satisfies RuntimePort;
+ * ```
+ */
+export interface RuntimePort {
+  env: EnvFn;
+  readTextFile: ReadTextFileFn;
+  serve: ServeFn;
+  unrefTimer: UnrefTimerFn;
+}

package/src/sampling/sampling-bridge.ts

@@ -0,0 +1,191 @@
+/**
+ * Sampling Bridge for Bidirectional LLM Communication
+ *
+ * Enables MCP servers to delegate complex tasks back to the client's LLM
+ * via the sampling protocol. Manages pending requests with timeout and
+ * response routing.
+ *
+ * @module lib/server/sampling-bridge
+ */
+
+import type {
+  PromiseResolver,
+  SamplingClient,
+  SamplingParams,
+  SamplingResult,
+} from "../types.js";
+
+/**
+ * SamplingBridge manages bidirectional sampling requests
+ *
+ * Features:
+ * - Request/response correlation via unique IDs
+ * - Automatic timeout for pending requests (60s default)
+ * - Promise-based async/await API
+ * - Support for both Anthropic and OpenAI sampling
+ *
+ * @example
+ * ```typescript
+ * const bridge = new SamplingBridge(samplingClient);
+ *
+ * // Delegate task to LLM
+ * const result = await bridge.requestSampling({
+ *   messages: [{ role: 'user', content: 'Analyze this data...' }]
+ * });
+ * ```
+ */
+export class SamplingBridge {
+  private pendingRequests = new Map<number, PromiseResolver<SamplingResult>>();
+  private nextId = 1;
+  private samplingClient: SamplingClient;
+  private defaultTimeout = 60000; // 60 seconds
+
+  constructor(client: SamplingClient, options?: { timeout?: number }) {
+    this.samplingClient = client;
+    if (options?.timeout) {
+      this.defaultTimeout = options.timeout;
+    }
+  }
+
+  /**
+   * Request sampling from the client's LLM
+   *
+   * @param params - Sampling parameters (messages, model preferences, etc.)
+   * @param timeout - Override default timeout (ms)
+   * @returns Promise that resolves with sampling result
+   * @throws {Error} If request times out or client fails
+   */
+  async requestSampling(
+    params: SamplingParams,
+    timeout?: number,
+  ): Promise<SamplingResult> {
+    const id = this.nextId++;
+    const timeoutMs = timeout ?? this.defaultTimeout;
+
+    // Create timeout promise for race condition
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(
+          new Error(`Sampling request ${id} timed out after ${timeoutMs}ms`),
+        );
+      }, timeoutMs);
+    });
+
+    // Track pending request for potential external response handling
+    const resultPromise = new Promise<SamplingResult>((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject });
+    });
+
+    try {
+      // Race between client response and timeout
+      // Also race with external response via handleResponse()
+      const clientPromise = this.samplingClient.createMessage(params);
+      const result = await Promise.race([
+        clientPromise.then((r) => {
+          // Resolve the pending request tracker as well
+          const pending = this.pendingRequests.get(id);
+          if (pending) {
+            pending.resolve(r);
+          }
+          return r;
+        }),
+        timeoutPromise,
+        resultPromise, // Allow external handleResponse() to resolve
+      ]);
+      return result;
+    } catch (error) {
+      // Clean up pending request on error
+      this.pendingRequests.delete(id);
+      throw error;
+    } finally {
+      // Always clear timeout to prevent memory leak
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      // Clean up pending request
+      this.pendingRequests.delete(id);
+    }
+  }
+
+  /**
+   * Handle sampling response from client (for bidirectional stdio)
+   *
+   * Used when MCP server receives sampling responses via stdin.
+   * Resolves the corresponding pending promise.
+   *
+   * @param id - Request ID from original sampling request
+   * @param result - Sampling result from client
+   */
+  handleResponse(id: number, result: SamplingResult): void {
+    const pending = this.pendingRequests.get(id);
+
+    if (!pending) {
+      console.error(
+        `[SamplingBridge] Received response for unknown request: ${id}`,
+      );
+      return;
+    }
+
+    this.pendingRequests.delete(id);
+    pending.resolve(result);
+  }
+
+  /**
+   * Handle sampling error from client
+   *
+   * @param id - Request ID
+   * @param error - Error from client
+   */
+  handleError(id: number, error: Error): void {
+    const pending = this.pendingRequests.get(id);
+
+    if (!pending) {
+      console.error(
+        `[SamplingBridge] Received error for unknown request: ${id}`,
+      );
+      return;
+    }
+
+    this.pendingRequests.delete(id);
+    pending.reject(error);
+  }
+
+  /**
+   * Get count of pending sampling requests
+   */
+  getPendingCount(): number {
+    return this.pendingRequests.size;
+  }
+
+  /**
+   * Cancel all pending requests (useful for shutdown)
+   */
+  cancelAll(): void {
+    for (const [id, pending] of this.pendingRequests.entries()) {
+      pending.reject(
+        new Error(`Sampling request ${id} cancelled (server shutdown)`),
+      );
+    }
+    this.pendingRequests.clear();
+  }
+
+  /**
+   * Get sampling client for direct access
+   */
+  getClient(): SamplingClient {
+    return this.samplingClient;
+  }
+
+  /**
+   * Alias for requestSampling() - implements SamplingClient interface
+   * This allows the bridge to be used as a drop-in replacement for SamplingClient
+   *
+   * @param params - Sampling parameters
+   * @returns Sampling result
+   */
+  createMessage(params: SamplingParams): Promise<SamplingResult> {
+    return this.requestSampling(params);
+  }
+}