@mcpmesh/sdk 0.8.0-beta.1

package/dist/proxy.js

@@ -0,0 +1,324 @@
+/**
+ * MCP Mesh proxy implementation for dependency injection.
+ *
+ * Provides HTTP client proxies for calling remote MCP agents.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { generateSpanId, publishTraceSpan, createTraceHeaders, } from "./tracing.js";
+/**
+ * AsyncLocalStorage for trace context - provides async-safe context propagation.
+ * Unlike module-level variables, this correctly handles concurrent requests
+ * without trace context bleeding between them.
+ */
+const traceContextStorage = new AsyncLocalStorage();
+/**
+ * Run a function with trace context.
+ * The context is automatically propagated to all async operations within the callback.
+ * This is the preferred way to set trace context for tool execution.
+ */
+export function runWithTraceContext(ctx, fn) {
+    return traceContextStorage.run(ctx, fn);
+}
+/**
+ * Get the current trace context.
+ * Returns the trace context for the current async execution context,
+ * or null if not within a traced context.
+ */
+export function getCurrentTraceContext() {
+    return traceContextStorage.getStore() ?? null;
+}
+/**
+ * @deprecated Use runWithTraceContext() instead for async-safe context propagation.
+ * This function is kept for backward compatibility but does nothing.
+ */
+export function setCurrentTraceContext(_ctx) {
+    // No-op - use runWithTraceContext() instead
+    // This is kept for backward compatibility with any external code
+}
+/**
+ * Create an McpMeshAgent proxy for a resolved dependency.
+ *
+ * The returned object is callable (invokes the bound function)
+ * and also has methods for calling other tools on the agent.
+ */
+export function createProxy(endpoint, capability, functionName, kwargs) {
+    const timeout = (kwargs?.timeout ?? 30) * 1000; // Convert to ms
+    const maxAttempts = kwargs?.maxAttempts ?? 1;
+    // The proxy function that calls the bound tool
+    // Returns parsed object (like Python) or raw string if not JSON
+    const proxyFn = async (args) => {
+        const result = await callMcpTool(endpoint, functionName, args, timeout, maxAttempts, capability);
+        // Parse JSON if possible, otherwise return raw string (matches Python behavior)
+        try {
+            return JSON.parse(result);
+        }
+        catch {
+            return result;
+        }
+    };
+    // Attach properties and methods
+    Object.defineProperties(proxyFn, {
+        endpoint: { value: endpoint, writable: false },
+        capability: { value: capability, writable: false },
+        functionName: { value: functionName, writable: false },
+        isAvailable: { value: true, writable: false },
+        callTool: {
+            value: async (toolName, args) => {
+                const result = await callMcpTool(endpoint, toolName, args, timeout, maxAttempts, capability);
+                try {
+                    return JSON.parse(result);
+                }
+                catch {
+                    return result;
+                }
+            },
+            writable: false,
+        },
+    });
+    return proxyFn;
+}
+/**
+ * Call an MCP tool via HTTP POST.
+ *
+ * Uses the MCP HTTP Streamable protocol:
+ * POST /mcp with JSON-RPC 2.0 payload.
+ * Includes distributed tracing: propagates trace context and publishes spans.
+ */
+async function callMcpTool(endpoint, toolName, args, timeout, maxAttempts, capability) {
+    // Ensure endpoint ends with /mcp
+    const mcpEndpoint = endpoint.endsWith("/mcp")
+        ? endpoint
+        : `${endpoint.replace(/\/$/, "")}/mcp`;
+    // Tracing: create span for this outgoing proxy call
+    // Use AsyncLocalStorage to get trace context for the current async execution
+    const traceCtx = getCurrentTraceContext();
+    const spanId = traceCtx ? generateSpanId() : null;
+    const startTime = Date.now() / 1000;
+    // Build arguments with trace context injection (for downstream agents)
+    // This is the fallback mechanism since fastmcp doesn't expose HTTP headers
+    const argsWithTrace = { ...(args ?? {}) };
+    if (traceCtx && spanId) {
+        // Inject trace context into arguments - downstream agent will extract these
+        // spanId is the proxy span we're about to publish, which becomes child's parent
+        argsWithTrace._trace_id = traceCtx.traceId;
+        argsWithTrace._parent_span = spanId;
+    }
+    const payload = {
+        jsonrpc: "2.0",
+        id: generateRequestId(),
+        method: "tools/call",
+        params: {
+            name: toolName,
+            arguments: argsWithTrace,
+        },
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            // Build headers with trace context propagation
+            const headers = {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+            };
+            // Propagate trace context to downstream agent
+            if (traceCtx && spanId) {
+                Object.assign(headers, createTraceHeaders(traceCtx.traceId, spanId));
+            }
+            const response = await fetch(mcpEndpoint, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new Error(`MCP call failed: ${response.status} ${response.statusText}`);
+            }
+            const contentType = response.headers.get("content-type") ?? "";
+            // Handle SSE streaming response
+            if (contentType.includes("text/event-stream")) {
+                const sseResult = await parseSSEResponse(response);
+                // Publish success span
+                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, true, null, typeof sseResult);
+                return sseResult;
+            }
+            // Handle JSON response
+            const result = (await response.json());
+            if (result.error) {
+                const errorMsg = result.error.message ?? JSON.stringify(result.error);
+                // Publish error span
+                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, errorMsg, "error");
+                throw new Error(`MCP error: ${errorMsg}`);
+            }
+            // Extract content from result
+            const content = extractContent(result.result);
+            // Publish success span
+            publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, true, null, typeof content);
+            return content;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            // Don't retry on abort (timeout)
+            if (lastError.name === "AbortError") {
+                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, "timeout", "error");
+                throw new Error(`MCP call timed out after ${timeout}ms`);
+            }
+            // Retry on network errors
+            if (attempt < maxAttempts - 1) {
+                await sleep(100 * (attempt + 1)); // Exponential backoff
+                continue;
+            }
+        }
+    }
+    // All retries failed
+    publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, lastError?.message ?? "unknown", "error");
+    throw lastError ?? new Error("MCP call failed");
+}
+/**
+ * Helper to publish a proxy call span (fire and forget).
+ */
+function publishProxySpan(traceCtx, spanId, startTime, _toolName, _capability, endpoint, success, error, resultType) {
+    if (!traceCtx || !spanId)
+        return;
+    const endTime = Date.now() / 1000;
+    const durationMs = (endTime - startTime) * 1000;
+    // Fire and forget - don't await
+    publishTraceSpan({
+        traceId: traceCtx.traceId,
+        spanId,
+        parentSpan: traceCtx.parentSpanId,
+        functionName: "proxy_call_wrapper",
+        startTime,
+        endTime,
+        durationMs,
+        success,
+        error,
+        resultType,
+        argsCount: 0,
+        kwargsCount: 0,
+        dependencies: [endpoint],
+        injectedDependencies: 0,
+        meshPositions: [],
+    }).catch(() => {
+        // Silently ignore publish errors
+    });
+}
+/**
+ * Parse SSE response from MCP HTTP Streamable transport.
+ */
+async function parseSSEResponse(response) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        throw new Error("No response body");
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let result = "";
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        // Parse SSE events
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? ""; // Keep incomplete line
+        for (const line of lines) {
+            if (line.startsWith("data: ")) {
+                const data = line.slice(6);
+                if (data === "[DONE]")
+                    continue;
+                try {
+                    const event = JSON.parse(data);
+                    // Handle JSON-RPC response
+                    const jsonRpcEvent = event;
+                    if (jsonRpcEvent.result) {
+                        result = extractContent(jsonRpcEvent.result);
+                    }
+                    else if (jsonRpcEvent.error) {
+                        throw new Error(`MCP error: ${jsonRpcEvent.error.message ?? JSON.stringify(jsonRpcEvent.error)}`);
+                    }
+                }
+                catch (e) {
+                    // Ignore parse errors for non-JSON data events
+                    if (!(e instanceof SyntaxError))
+                        throw e;
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Extract content from MCP CallToolResult.
+ *
+ * Handles various content formats:
+ * - { content: [{ type: "text", text: "..." }] }
+ * - { content: "..." }
+ * - Direct string
+ */
+function extractContent(result) {
+    if (typeof result === "string") {
+        return result;
+    }
+    if (result && typeof result === "object") {
+        const obj = result;
+        // Handle { content: [...] } format
+        if (Array.isArray(obj.content)) {
+            const textParts = [];
+            for (const item of obj.content) {
+                if (item && typeof item === "object" && "text" in item) {
+                    textParts.push(String(item.text));
+                }
+                else if (typeof item === "string") {
+                    textParts.push(item);
+                }
+            }
+            const text = textParts.join("");
+            // Try to parse as JSON if it looks like JSON
+            if (text.startsWith("{") || text.startsWith("[")) {
+                try {
+                    return JSON.stringify(JSON.parse(text));
+                }
+                catch {
+                    return text;
+                }
+            }
+            return text;
+        }
+        // Handle { content: "..." } format
+        if (typeof obj.content === "string") {
+            return obj.content;
+        }
+        // Return JSON stringified
+        return JSON.stringify(result);
+    }
+    return String(result);
+}
+/**
+ * Generate a unique request ID.
+ */
+function generateRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Sleep for a given duration.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Normalize a DependencySpec to canonical form.
+ */
+export function normalizeDependency(dep) {
+    if (typeof dep === "string") {
+        return { capability: dep, tags: [] };
+    }
+    return {
+        capability: dep.capability,
+        tags: dep.tags ?? [],
+        version: dep.version,
+    };
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/response-parser.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Response parser for LLM outputs with Zod schema validation.
+ *
+ * Handles extraction of structured data from LLM responses, including:
+ * - JSON extraction from code blocks or raw text
+ * - Schema validation using Zod
+ * - Error handling with informative messages
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   answer: z.string(),
+ *   confidence: z.number(),
+ * });
+ *
+ * const parser = new ResponseParser(schema);
+ * const result = parser.parse('{"answer": "hello", "confidence": 0.95}');
+ * // => { answer: "hello", confidence: 0.95 }
+ * ```
+ */
+import type { ZodType, ZodError as ZodErrorType } from "zod";
+import { ResponseParseError } from "./errors.js";
+export { ResponseParseError };
+/**
+ * Extract JSON from a string that may contain markdown code blocks.
+ *
+ * Handles:
+ * - ```json ... ``` code blocks
+ * - ``` ... ``` code blocks (no language)
+ * - Raw JSON (object or array) using progressive JSON.parse
+ */
+export declare function extractJson(content: string): string | null;
+/**
+ * Parser for LLM responses with optional Zod schema validation.
+ *
+ * @template T - The output type (inferred from Zod schema)
+ */
+export declare class ResponseParser<T = string> {
+    private schema;
+    /**
+     * Create a new ResponseParser.
+     *
+     * @param schema - Optional Zod schema for validation. If not provided, returns raw string.
+     */
+    constructor(schema?: ZodType<T>);
+    /**
+     * Parse an LLM response string.
+     *
+     * If a schema is provided, attempts to extract and validate JSON.
+     * If no schema, returns the raw string content.
+     *
+     * @param content - Raw LLM response content
+     * @returns Parsed and validated result
+     * @throws ResponseParseError if parsing or validation fails
+     */
+    parse(content: string): T;
+    /**
+     * Try to parse, returning null on failure instead of throwing.
+     *
+     * @param content - Raw LLM response content
+     * @returns Parsed result or null if parsing fails
+     */
+    tryParse(content: string): T | null;
+    /**
+     * Get the Zod schema (if any).
+     */
+    getSchema(): ZodType<T> | null;
+    /**
+     * Check if this parser has a schema.
+     */
+    hasSchema(): boolean;
+}
+/**
+ * Create a response parser with an optional Zod schema.
+ *
+ * @param schema - Optional Zod schema for validation
+ * @returns ResponseParser instance
+ *
+ * @example
+ * ```typescript
+ * // No schema - returns raw string
+ * const stringParser = createResponseParser();
+ * const str = stringParser.parse("Hello world");
+ *
+ * // With schema - validates and returns typed object
+ * const objectParser = createResponseParser(z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * }));
+ * const obj = objectParser.parse('{"name": "John", "age": 30}');
+ * ```
+ */
+export declare function createResponseParser<T = string>(schema?: ZodType<T>): ResponseParser<T>;
+/**
+ * Convert a Zod schema to a human-readable description for LLM prompting.
+ * Uses zod-to-json-schema for forward compatibility with Zod v4.
+ */
+export declare function zodSchemaToPromptDescription(schema: ZodType): string;
+/**
+ * Format a Zod error into a human-readable string.
+ */
+export declare function formatZodError(error: ZodErrorType): string;
+//# sourceMappingURL=response-parser.d.ts.map

package/dist/response-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-parser.d.ts","sourceRoot":"","sources":["../src/response-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,KAAK,CAAC;AAE7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB1D;AA2CD;;;;GAIG;AACH,qBAAa,cAAc,CAAC,CAAC,GAAG,MAAM;IACpC,OAAO,CAAC,MAAM,CAAoB;IAElC;;;;OAIG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAI/B;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC;IA0CzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAQnC;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAI9B;;OAEG;IACH,SAAS,IAAI,OAAO;CAGrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,MAAM,EAC7C,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,cAAc,CAAC,CAAC,CAAC,CAEnB;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CA2BpE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAO1D"}

package/dist/response-parser.js

@@ -0,0 +1,232 @@
+/**
+ * Response parser for LLM outputs with Zod schema validation.
+ *
+ * Handles extraction of structured data from LLM responses, including:
+ * - JSON extraction from code blocks or raw text
+ * - Schema validation using Zod
+ * - Error handling with informative messages
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   answer: z.string(),
+ *   confidence: z.number(),
+ * });
+ *
+ * const parser = new ResponseParser(schema);
+ * const result = parser.parse('{"answer": "hello", "confidence": 0.95}');
+ * // => { answer: "hello", confidence: 0.95 }
+ * ```
+ */
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { ResponseParseError } from "./errors.js";
+// Re-export for backwards compatibility
+export { ResponseParseError };
+/**
+ * Extract JSON from a string that may contain markdown code blocks.
+ *
+ * Handles:
+ * - ```json ... ``` code blocks
+ * - ``` ... ``` code blocks (no language)
+ * - Raw JSON (object or array) using progressive JSON.parse
+ */
+export function extractJson(content) {
+    // Strategy 1: Try to extract from markdown code blocks first
+    const codeBlockMatch = content.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (codeBlockMatch) {
+        return codeBlockMatch[1].trim();
+    }
+    // Strategy 2: Try to find JSON object using progressive JSON.parse
+    // This handles braces inside strings correctly
+    const braceStart = content.indexOf("{");
+    if (braceStart !== -1) {
+        const result = tryProgressiveParse(content, braceStart, "{", "}");
+        if (result)
+            return result;
+    }
+    // Strategy 3: Try to find JSON array using progressive JSON.parse
+    const bracketStart = content.indexOf("[");
+    if (bracketStart !== -1) {
+        const result = tryProgressiveParse(content, bracketStart, "[", "]");
+        if (result)
+            return result;
+    }
+    return null;
+}
+/**
+ * Try to extract valid JSON by progressively extending the end position.
+ * This correctly handles braces/brackets inside string values.
+ */
+function tryProgressiveParse(content, start, openChar, closeChar) {
+    // Quick check: count characters to find potential end positions
+    let depth = 0;
+    const potentialEnds = [];
+    for (let i = start; i < content.length; i++) {
+        const char = content[i];
+        if (char === openChar) {
+            depth++;
+        }
+        else if (char === closeChar) {
+            depth--;
+            if (depth === 0) {
+                potentialEnds.push(i);
+            }
+        }
+    }
+    // Try each potential end position (shortest first for efficiency)
+    for (const end of potentialEnds) {
+        const candidate = content.slice(start, end + 1);
+        try {
+            JSON.parse(candidate);
+            return candidate;
+        }
+        catch {
+            // Not valid JSON, try next potential end
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Parser for LLM responses with optional Zod schema validation.
+ *
+ * @template T - The output type (inferred from Zod schema)
+ */
+export class ResponseParser {
+    schema;
+    /**
+     * Create a new ResponseParser.
+     *
+     * @param schema - Optional Zod schema for validation. If not provided, returns raw string.
+     */
+    constructor(schema) {
+        this.schema = schema ?? null;
+    }
+    /**
+     * Parse an LLM response string.
+     *
+     * If a schema is provided, attempts to extract and validate JSON.
+     * If no schema, returns the raw string content.
+     *
+     * @param content - Raw LLM response content
+     * @returns Parsed and validated result
+     * @throws ResponseParseError if parsing or validation fails
+     */
+    parse(content) {
+        // No schema - return raw string
+        if (!this.schema) {
+            return content;
+        }
+        // Extract JSON from content
+        const jsonStr = extractJson(content);
+        if (!jsonStr) {
+            throw new ResponseParseError("Could not extract JSON from response. Expected JSON object or array.", content);
+        }
+        // Parse JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(jsonStr);
+        }
+        catch (err) {
+            throw new ResponseParseError(`Invalid JSON: ${err instanceof Error ? err.message : String(err)}`, content);
+        }
+        // Validate with Zod schema
+        const result = this.schema.safeParse(parsed);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `${i.path.join(".")}: ${i.message}`)
+                .join("; ");
+            throw new ResponseParseError(`Schema validation failed: ${issues}`, content, result.error);
+        }
+        return result.data;
+    }
+    /**
+     * Try to parse, returning null on failure instead of throwing.
+     *
+     * @param content - Raw LLM response content
+     * @returns Parsed result or null if parsing fails
+     */
+    tryParse(content) {
+        try {
+            return this.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get the Zod schema (if any).
+     */
+    getSchema() {
+        return this.schema;
+    }
+    /**
+     * Check if this parser has a schema.
+     */
+    hasSchema() {
+        return this.schema !== null;
+    }
+}
+/**
+ * Create a response parser with an optional Zod schema.
+ *
+ * @param schema - Optional Zod schema for validation
+ * @returns ResponseParser instance
+ *
+ * @example
+ * ```typescript
+ * // No schema - returns raw string
+ * const stringParser = createResponseParser();
+ * const str = stringParser.parse("Hello world");
+ *
+ * // With schema - validates and returns typed object
+ * const objectParser = createResponseParser(z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * }));
+ * const obj = objectParser.parse('{"name": "John", "age": 30}');
+ * ```
+ */
+export function createResponseParser(schema) {
+    return new ResponseParser(schema);
+}
+/**
+ * Convert a Zod schema to a human-readable description for LLM prompting.
+ * Uses zod-to-json-schema for forward compatibility with Zod v4.
+ */
+export function zodSchemaToPromptDescription(schema) {
+    // Convert to JSON Schema using the public API (Zod v4 compatible)
+    const jsonSchema = zodToJsonSchema(schema, { $refStrategy: "none" });
+    // Check for top-level description
+    if (jsonSchema.description && typeof jsonSchema.description === "string") {
+        return jsonSchema.description;
+    }
+    // If it's an object type, describe the fields
+    if (jsonSchema.type === "object" && jsonSchema.properties) {
+        const properties = jsonSchema.properties;
+        const fields = Object.keys(properties).map((key) => {
+            const prop = properties[key];
+            const fieldType = prop.type || "unknown";
+            const fieldDesc = prop.description ? ` (${prop.description})` : "";
+            return `  - ${key}: ${fieldType}${fieldDesc}`;
+        });
+        return `JSON object with fields:\n${fields.join("\n")}`;
+    }
+    // Fallback for other types
+    if (jsonSchema.type) {
+        return `JSON ${jsonSchema.type}`;
+    }
+    return "JSON";
+}
+/**
+ * Format a Zod error into a human-readable string.
+ */
+export function formatZodError(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") + ": " : "";
+        return `${path}${issue.message}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=response-parser.js.map