@musashishao/agent-kit 1.8.2 → 1.9.1

package/.agent/mcp-gateway/src/observability/otel.ts

@@ -0,0 +1,405 @@
+/**
+ * OpenTelemetry Integration for MCP Gateway
+ * 
+ * Provides distributed tracing and metrics for MCP operations.
+ * 
+ * This is a lightweight implementation that works without external dependencies.
+ * For production, install @opentelemetry/api and configure exporters.
+ * 
+ * @see https://opentelemetry.io
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OtelConfig {
+    /** Service name for tracing */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** OTLP endpoint (e.g., http://localhost:4318) */
+    otlpEndpoint?: string;
+    /** Enable console exporter for debugging */
+    debugMode?: boolean;
+    /** Sampling ratio (0.0 - 1.0) */
+    samplingRatio?: number;
+}
+
+export interface SpanConfig {
+    /** Span name */
+    name: string;
+    /** Custom attributes */
+    attributes?: Record<string, string | number | boolean>;
+}
+
+export interface ToolCallMetrics {
+    toolName: string;
+    duration: number;
+    success: boolean;
+    inputTokens?: number;
+    outputTokens?: number;
+    errorType?: string;
+}
+
+interface SpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+
+interface Span {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: { code: number; message?: string }): void;
+    recordException(error: Error): void;
+    end(): void;
+    spanContext(): SpanContext;
+}
+
+// ============================================================================
+// Simple Span Implementation
+// ============================================================================
+
+class SimpleSpan implements Span {
+    private name: string;
+    private attributes: Record<string, string | number | boolean> = {};
+    private status: { code: number; message?: string } = { code: 0 };
+    private startTime: number;
+    private endTime?: number;
+    private error?: Error;
+    private _spanContext: SpanContext;
+    private debug: boolean;
+
+    constructor(name: string, debug: boolean = false) {
+        this.name = name;
+        this.debug = debug;
+        this.startTime = Date.now();
+        this._spanContext = {
+            traceId: this.generateId(32),
+            spanId: this.generateId(16),
+            traceFlags: 1,
+        };
+    }
+
+    private generateId(length: number): string {
+        const chars = "0123456789abcdef";
+        let result = "";
+        for (let i = 0; i < length; i++) {
+            result += chars[Math.floor(Math.random() * chars.length)];
+        }
+        return result;
+    }
+
+    setAttribute(key: string, value: string | number | boolean): void {
+        this.attributes[key] = value;
+    }
+
+    setStatus(status: { code: number; message?: string }): void {
+        this.status = status;
+    }
+
+    recordException(error: Error): void {
+        this.error = error;
+    }
+
+    end(): void {
+        this.endTime = Date.now();
+        if (this.debug) {
+            console.log(`[TRACE] ${this.name}`, {
+                duration: this.endTime - this.startTime,
+                attributes: this.attributes,
+                status: this.status,
+                error: this.error?.message,
+            });
+        }
+    }
+
+    spanContext(): SpanContext {
+        return this._spanContext;
+    }
+}
+
+// ============================================================================
+// Tracer Management
+// ============================================================================
+
+let tracerConfig: OtelConfig = {
+    serviceName: "mcp-gateway",
+    serviceVersion: "2.0.0",
+};
+
+/**
+ * Initialize tracing configuration
+ */
+export function initializeTracing(config: OtelConfig): void {
+    tracerConfig = config;
+    console.error(`[OTel] Tracing initialized for ${config.serviceName}`);
+}
+
+/**
+ * Start a new span
+ */
+export function startSpan(config: SpanConfig): Span {
+    const span = new SimpleSpan(config.name, tracerConfig.debugMode);
+
+    if (config.attributes) {
+        for (const [key, value] of Object.entries(config.attributes)) {
+            span.setAttribute(key, value);
+        }
+    }
+
+    return span;
+}
+
+/**
+ * Execute function within a span context
+ */
+export async function withSpan<T>(
+    config: SpanConfig,
+    fn: (span: Span) => Promise<T>
+): Promise<T> {
+    const span = startSpan(config);
+
+    try {
+        const result = await fn(span);
+        span.setStatus({ code: 0 }); // OK
+        return result;
+    } catch (error) {
+        span.setStatus({
+            code: 2, // ERROR
+            message: error instanceof Error ? error.message : "Unknown error",
+        });
+        span.recordException(error as Error);
+        throw error;
+    } finally {
+        span.end();
+    }
+}
+
+/**
+ * Trace an MCP tool call
+ */
+export async function traceToolCall<T>(
+    toolName: string,
+    input: unknown,
+    fn: () => Promise<T>
+): Promise<T> {
+    return withSpan(
+        {
+            name: `mcp.tool.${toolName}`,
+            attributes: {
+                "mcp.tool.name": toolName,
+                "mcp.tool.input_size": JSON.stringify(input).length,
+            },
+        },
+        async (span) => {
+            const startTime = Date.now();
+
+            try {
+                const result = await fn();
+
+                const duration = Date.now() - startTime;
+                span.setAttribute("mcp.tool.duration_ms", duration);
+                span.setAttribute("mcp.tool.success", true);
+
+                // Record metrics
+                recordToolMetrics({
+                    toolName,
+                    duration,
+                    success: true,
+                });
+
+                return result;
+            } catch (error) {
+                const duration = Date.now() - startTime;
+                span.setAttribute("mcp.tool.duration_ms", duration);
+                span.setAttribute("mcp.tool.success", false);
+                span.setAttribute("mcp.tool.error_type", (error as Error).name);
+
+                recordToolMetrics({
+                    toolName,
+                    duration,
+                    success: false,
+                    errorType: (error as Error).name,
+                });
+
+                throw error;
+            }
+        }
+    );
+}
+
+/**
+ * Trace an MCP request (session-level)
+ */
+export async function traceRequest<T>(
+    requestId: string,
+    fn: () => Promise<T>
+): Promise<T> {
+    return withSpan(
+        {
+            name: "mcp.request",
+            attributes: {
+                "mcp.request.id": requestId,
+                "mcp.request.timestamp": new Date().toISOString(),
+            },
+        },
+        async (span) => fn()
+    );
+}
+
+// ============================================================================
+// Metrics Collection
+// ============================================================================
+
+// In-memory metrics store
+const metricsStore = {
+    toolCalls: new Map<string, number>(),
+    toolDurations: new Map<string, number[]>(),
+    toolErrors: new Map<string, number>(),
+    requestCount: 0,
+    totalDuration: 0,
+};
+
+/**
+ * Record tool call metrics
+ */
+export function recordToolMetrics(metrics: ToolCallMetrics): void {
+    const { toolName, duration, success, errorType } = metrics;
+
+    // Increment call count
+    metricsStore.toolCalls.set(
+        toolName,
+        (metricsStore.toolCalls.get(toolName) || 0) + 1
+    );
+
+    // Record duration
+    const durations = metricsStore.toolDurations.get(toolName) || [];
+    durations.push(duration);
+    // Keep last 1000 samples
+    if (durations.length > 1000) durations.shift();
+    metricsStore.toolDurations.set(toolName, durations);
+
+    // Record errors
+    if (!success) {
+        const errorKey = `${toolName}:${errorType || "unknown"}`;
+        metricsStore.toolErrors.set(
+            errorKey,
+            (metricsStore.toolErrors.get(errorKey) || 0) + 1
+        );
+    }
+
+    metricsStore.requestCount++;
+    metricsStore.totalDuration += duration;
+}
+
+/**
+ * Get aggregated metrics
+ */
+export function getMetrics(): {
+    tools: Record<string, {
+        calls: number;
+        avgDuration: number;
+        p95Duration: number;
+        errorRate: number;
+    }>;
+    summary: {
+        totalRequests: number;
+        avgDuration: number;
+        uptime: number;
+    };
+} {
+    const tools: Record<string, {
+        calls: number;
+        avgDuration: number;
+        p95Duration: number;
+        errorRate: number;
+    }> = {};
+
+    for (const [toolName, calls] of metricsStore.toolCalls) {
+        const durations = metricsStore.toolDurations.get(toolName) || [];
+        const errors = Array.from(metricsStore.toolErrors.entries())
+            .filter(([key]) => key.startsWith(toolName))
+            .reduce((sum, [, count]) => sum + count, 0);
+
+        const sortedDurations = [...durations].sort((a, b) => a - b);
+        const p95Index = Math.floor(sortedDurations.length * 0.95);
+
+        tools[toolName] = {
+            calls,
+            avgDuration: durations.length > 0
+                ? durations.reduce((a, b) => a + b, 0) / durations.length
+                : 0,
+            p95Duration: sortedDurations[p95Index] || 0,
+            errorRate: calls > 0 ? errors / calls : 0,
+        };
+    }
+
+    return {
+        tools,
+        summary: {
+            totalRequests: metricsStore.requestCount,
+            avgDuration: metricsStore.requestCount > 0
+                ? metricsStore.totalDuration / metricsStore.requestCount
+                : 0,
+            uptime: process.uptime(),
+        },
+    };
+}
+
+/**
+ * Reset metrics (for testing)
+ */
+export function resetMetrics(): void {
+    metricsStore.toolCalls.clear();
+    metricsStore.toolDurations.clear();
+    metricsStore.toolErrors.clear();
+    metricsStore.requestCount = 0;
+    metricsStore.totalDuration = 0;
+}
+
+// ============================================================================
+// Context Propagation
+// ============================================================================
+
+/**
+ * Extract trace context from HTTP headers (W3C format)
+ */
+export function extractTraceContext(headers: Record<string, string | string[] | undefined>): SpanContext | null {
+    const traceparent = headers["traceparent"];
+    if (!traceparent || typeof traceparent !== "string") {
+        return null;
+    }
+
+    // Format: version-traceid-parentid-flags
+    const parts = traceparent.split("-");
+    if (parts.length !== 4) {
+        return null;
+    }
+
+    return {
+        traceId: parts[1],
+        spanId: parts[2],
+        traceFlags: parseInt(parts[3], 16),
+    };
+}
+
+/**
+ * Inject trace context into HTTP headers
+ */
+export function injectTraceContext(headers: Record<string, string>, context: SpanContext): void {
+    headers["traceparent"] = `00-${context.traceId}-${context.spanId}-0${context.traceFlags}`;
+}
+
+export default {
+    initializeTracing,
+    startSpan,
+    withSpan,
+    traceToolCall,
+    traceRequest,
+    recordToolMetrics,
+    getMetrics,
+    resetMetrics,
+    extractTraceContext,
+    injectTraceContext,
+};

package/.agent/mcp-gateway/src/transports/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Transport module exports
+ */
+
+export * from "./streamableHttp.js";

package/.agent/mcp-gateway/src/transports/streamableHttp.ts

@@ -0,0 +1,235 @@
+/**
+ * Streamable HTTP Transport for MCP Gateway
+ * 
+ * Modern transport layer supporting:
+ * - HTTP POST/GET for request/response
+ * - Optional SSE for server-initiated streaming
+ * - Stateless operation mode
+ * - Multiple concurrent clients
+ * 
+ * @see https://modelcontextprotocol.io/docs/transports
+ */
+
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import type { IncomingMessage, ServerResponse } from "http";
+import { createServer, Server } from "http";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StreamableHttpOptions {
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to (default: 0.0.0.0) */
+    host?: string;
+    /** Enable SSE for server-initiated streaming */
+    enableSSE?: boolean;
+    /** Enable stateless mode for horizontal scaling */
+    stateless?: boolean;
+    /** Session timeout in milliseconds */
+    sessionTimeout?: number;
+    /** Enable OAuth 2.1 authentication */
+    enableAuth?: boolean;
+    /** CORS origins (default: none) */
+    corsOrigins?: string[];
+}
+
+export interface TransportResult {
+    transport: StreamableHTTPServerTransport;
+    server: Server;
+    close: () => Promise<void>;
+}
+
+// ============================================================================
+// CORS Middleware
+// ============================================================================
+
+function handleCors(
+    req: IncomingMessage,
+    res: ServerResponse,
+    allowedOrigins: string[]
+): boolean {
+    const origin = req.headers.origin;
+
+    if (origin && allowedOrigins.includes(origin)) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Session-ID");
+        res.setHeader("Access-Control-Expose-Headers", "X-Session-ID");
+        res.setHeader("Access-Control-Max-Age", "86400");
+    }
+
+    // Handle preflight
+    if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return true;
+    }
+
+    return false;
+}
+
+// ============================================================================
+// Health Check Endpoint
+// ============================================================================
+
+function handleHealthCheck(req: IncomingMessage, res: ServerResponse): boolean {
+    if (req.url === "/health" && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            status: "healthy",
+            timestamp: new Date().toISOString(),
+            version: "2.0.0",
+            transport: "streamable-http"
+        }));
+        return true;
+    }
+    return false;
+}
+
+// ============================================================================
+// Create Streamable HTTP Transport
+// ============================================================================
+
+export async function createStreamableHttpTransport(
+    options: StreamableHttpOptions
+): Promise<TransportResult> {
+    const {
+        port,
+        host = "0.0.0.0",
+        enableSSE = true,
+        stateless = true,
+        corsOrigins = [],
+    } = options;
+
+    // Session management for stateful mode
+    const sessions = new Map<string, StreamableHTTPServerTransport>();
+
+    // Create HTTP server
+    const httpServer = createServer(async (req, res) => {
+        // CORS handling
+        if (corsOrigins.length > 0 && handleCors(req, res, corsOrigins)) {
+            return;
+        }
+
+        // Health check
+        if (handleHealthCheck(req, res)) {
+            return;
+        }
+
+        // MCP endpoint
+        if (req.url === "/mcp" || req.url === "/") {
+            try {
+                // Get or create session
+                let sessionId = req.headers["x-session-id"] as string;
+                let transport: StreamableHTTPServerTransport;
+
+                if (stateless || !sessionId) {
+                    // Stateless mode: new transport per request
+                    transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => crypto.randomUUID(),
+                    });
+                } else {
+                    // Stateful mode: reuse transport
+                    transport = sessions.get(sessionId) || new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => sessionId,
+                    });
+                    sessions.set(sessionId, transport);
+                }
+
+                // Handle the request
+                await transport.handleRequest(req, res);
+
+                // Return session ID in response header
+                if (!stateless && transport.sessionId) {
+                    res.setHeader("X-Session-ID", transport.sessionId);
+                }
+
+            } catch (error) {
+                console.error("[MCP] Request handling error:", error);
+                if (!res.headersSent) {
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Internal server error" }));
+                }
+            }
+            return;
+        }
+
+        // SSE endpoint for server-initiated streaming
+        if (enableSSE && req.url === "/sse" && req.method === "GET") {
+            const sseTransport = new SSEServerTransport("/sse", res);
+            await sseTransport.start();
+            return;
+        }
+
+        // 404 for unknown paths
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+    });
+
+    // Start listening
+    await new Promise<void>((resolve) => {
+        httpServer.listen(port, host, () => {
+            console.log(`[MCP] Streamable HTTP transport listening on http://${host}:${port}`);
+            console.log(`[MCP] Endpoints: /mcp (main), /health (status)${enableSSE ? ", /sse (streaming)" : ""}`);
+            resolve();
+        });
+    });
+
+    // Create main transport for server connection
+    const mainTransport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+    });
+
+    return {
+        transport: mainTransport,
+        server: httpServer,
+        close: async () => {
+            sessions.clear();
+            await new Promise<void>((resolve, reject) => {
+                httpServer.close((err) => {
+                    if (err) reject(err);
+                    else resolve();
+                });
+            });
+        },
+    };
+}
+
+// ============================================================================
+// Dual Transport (stdio + HTTP)
+// ============================================================================
+
+export interface DualTransportOptions {
+    /** Enable stdio transport for local development */
+    enableStdio?: boolean;
+    /** HTTP transport options */
+    http?: StreamableHttpOptions;
+}
+
+export async function createDualTransport(options: DualTransportOptions) {
+    const transports: {
+        stdio?: any;
+        http?: TransportResult;
+    } = {};
+
+    // Create HTTP transport if configured
+    if (options.http) {
+        transports.http = await createStreamableHttpTransport(options.http);
+    }
+
+    // stdio is handled separately in main entry
+
+    return {
+        transports,
+        closeAll: async () => {
+            if (transports.http) {
+                await transports.http.close();
+            }
+        },
+    };
+}
+
+export default createStreamableHttpTransport;