@zauso-ai/capstan-agent 0.2.0 → 0.3.0

package/dist/registry.js

@@ -1,7 +1,10 @@
 import { generateAgentManifest } from "./manifest.js";
 import { generateOpenApiSpec } from "./openapi.js";
-import { createMcpServer } from "./mcp.js";
+import { createMcpServer, createMcpHttpHandler } from "./mcp.js";
 import { createA2AHandler } from "./a2a.js";
+import { withSpan } from "./telemetry.js";
+import { createMcpClient } from "./mcp-client.js";
+import { toLangChainTools } from "./langchain.js";
 /**
  * Unified capability registry — the central abstraction for Capstan's
  * multi-protocol adapter layer.
@@ -27,6 +30,10 @@ export class CapabilityRegistry {
     /** Register a single route entry. */
     register(route) {
         this.routes.push(route);
+        void withSpan("capstan.capability.register", {
+            "capstan.route.path": route.path,
+            "capstan.route.method": route.method,
+        }, async () => { });
     }
     /** Register multiple route entries at once. */
     registerAll(routes) {
@@ -51,6 +58,10 @@ export class CapabilityRegistry {
     }
     /** Project to OpenAPI 3.1 specification. */
     toOpenApi() {
+        // Fire-and-forget span — synchronous return is not blocked.
+        void withSpan("capstan.openapi.generate", {
+            "capstan.route.count": this.routes.length,
+        }, async () => { });
         return generateOpenApiSpec(this.config, this.routes);
     }
     /**
@@ -63,6 +74,20 @@ export class CapabilityRegistry {
     toMcp(executeRoute) {
         return createMcpServer(this.config, this.routes, executeRoute);
     }
+    /**
+     * Project to MCP Streamable HTTP handler.
+     *
+     * Returns a web-standard `(req: Request) => Promise<Response>` handler
+     * implementing the MCP Streamable HTTP transport (2025-03-26 spec).
+     * Mount it on any route (e.g. `/mcp`) to serve MCP over HTTP.
+     *
+     * @param executeRoute - Callback that invokes the actual route handler
+     *   given an HTTP method, path, and input payload.
+     * @returns A web-standard request handler.
+     */
+    toMcpHttp(executeRoute) {
+        return createMcpHttpHandler(this.config, this.routes, executeRoute);
+    }
     /**
      * Project to A2A agent card and JSON-RPC handler.
      *
@@ -73,5 +98,27 @@ export class CapabilityRegistry {
     toA2A(executeRoute) {
         return createA2AHandler(this.config, this.routes, executeRoute);
     }
+    // -------------------------------------------------------------------------
+    // MCP Client — consume external MCP servers
+    // -------------------------------------------------------------------------
+    mcpClients = [];
+    /** Connect to an external MCP server and import its tools. */
+    async connectMcp(options) {
+        const client = await createMcpClient(options);
+        this.mcpClients.push(client);
+        return client;
+    }
+    /** Close all MCP client connections. */
+    async closeMcpClients() {
+        await Promise.allSettled(this.mcpClients.map((c) => c.close()));
+        this.mcpClients = [];
+    }
+    // -------------------------------------------------------------------------
+    // LangChain — project to LangChain-compatible tools
+    // -------------------------------------------------------------------------
+    /** Project to LangChain-compatible tool definitions. */
+    toLangChain(options) {
+        return toLangChainTools(this, options);
+    }
 }
 //# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,kBAAkB;IACrB,MAAM,GAAyB,EAAE,CAAC;IAClC,MAAM,CAAc;IAE5B,YAAY,MAAmB;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,4EAA4E;IAC5E,eAAe;IACf,4EAA4E;IAE5E,qCAAqC;IACrC,QAAQ,CAAC,KAAyB;QAChC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,+CAA+C;IAC/C,WAAW,CAAC,MAA4B;QACtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,mCAAmC;IACnC,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,4EAA4E;IAC5E,cAAc;IACd,4EAA4E;IAE5E,gDAAgD;IAChD,UAAU;QACR,OAAO,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;IAED,4CAA4C;IAC5C,SAAS;QACP,OAAO,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CACH,YAIqB;QASrB,OAAO,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CACH,YAIqB;QAKrB,OAAO,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAClE,CAAC;CACF"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Execute an async function inside an OpenTelemetry span.
+ *
+ * When `@opentelemetry/api` is not installed the function is called directly
+ * without any tracing overhead — graceful degradation by design.
+ */
+export declare function withSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: (span?: any) => Promise<T>): Promise<T>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAqBA;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACrD,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/telemetry.js

@@ -0,0 +1,48 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Thin OpenTelemetry wrapper that gracefully degrades when
+ * `@opentelemetry/api` is not installed — zero overhead, no hard dep.
+ */
+let _tracer = null;
+async function getTracer() {
+    if (_tracer)
+        return _tracer;
+    try {
+        const moduleName = "@opentelemetry/api";
+        const { trace } = await import(/* webpackIgnore: true */ moduleName);
+        _tracer = trace.getTracer("@zauso-ai/capstan-agent", "1.0.0");
+        return _tracer;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Execute an async function inside an OpenTelemetry span.
+ *
+ * When `@opentelemetry/api` is not installed the function is called directly
+ * without any tracing overhead — graceful degradation by design.
+ */
+export async function withSpan(name, attributes, fn) {
+    const tracer = await getTracer();
+    if (!tracer)
+        return fn();
+    return tracer.startActiveSpan(name, { attributes }, async (span) => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: 1 }); // SpanStatusCode.OK
+            return result;
+        }
+        catch (err) {
+            span.setStatus({
+                code: 2, // SpanStatusCode.ERROR
+                message: err instanceof Error ? err.message : "unknown",
+            });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD;;;GAGG;AAEH,IAAI,OAAO,GAAQ,IAAI,CAAC;AAExB,KAAK,UAAU,SAAS;IACtB,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,oBAAoB,CAAC;QACxC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC;QACrE,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,yBAAyB,EAAE,OAAO,CAAC,CAAC;QAC9D,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,UAAqD,EACrD,EAA8B;IAE9B,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;IACjC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,EAAE,CAAC;IACzB,OAAO,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAS,EAAE,EAAE;QACtE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB;YACjD,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,SAAS,CAAC;gBACb,IAAI,EAAE,CAAC,EAAE,uBAAuB;gBAChC,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;aACxD,CAAC,CAAC;YACH,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,84 @@
+import type { CapabilityRegistry } from "./registry.js";
+/**
+ * Result of a single MCP test check.
+ */
+export interface McpTestResult {
+    pass: boolean;
+    tool: string;
+    check: string;
+    message?: string;
+}
+/**
+ * Test harness for validating MCP tool discovery and invocation.
+ * Uses the Capstan MCP server in-process (no network needed).
+ */
+export declare class McpTestHarness {
+    private registry;
+    constructor(registry: CapabilityRegistry);
+    /**
+     * Validate that all registered routes with a `capability` field appear as
+     * MCP tools, and that every MCP tool maps back to a registered route.
+     */
+    validateToolDiscovery(): Promise<McpTestResult[]>;
+    /**
+     * Validate that MCP tool input schemas match the Zod shapes derived from
+     * each route's `inputSchema`.
+     */
+    validateToolSchemas(): Promise<McpTestResult[]>;
+    /**
+     * Call a tool with test input and validate the response format.
+     *
+     * The `executeRoute` callback simulates the actual route handler. The
+     * harness verifies that the MCP server wraps the response correctly
+     * (content array with text entries).
+     */
+    validateToolInvocation(toolName: string, input: Record<string, unknown>, executeRoute: (method: string, path: string, input: unknown) => Promise<unknown>): Promise<McpTestResult[]>;
+    /**
+     * Run all validations: discovery, schemas, and invocation for every tool.
+     */
+    runAll(executeRoute: (method: string, path: string, input: unknown) => Promise<unknown>): Promise<{
+        results: McpTestResult[];
+        passed: number;
+        failed: number;
+    }>;
+}
+/**
+ * HTTP-based test client for testing the Streamable HTTP MCP endpoint.
+ *
+ * Sends JSON-RPC 2.0 POST requests to a running MCP HTTP endpoint and
+ * manages session lifecycle via the `Mcp-Session-Id` header.
+ */
+export declare class McpHttpTestClient {
+    private baseUrl;
+    private sessionId;
+    private nextId;
+    constructor(baseUrl: string);
+    /**
+     * Send a JSON-RPC 2.0 request to the MCP endpoint.
+     */
+    private sendRequest;
+    /**
+     * Send an initialize request to establish a session.
+     */
+    initialize(): Promise<{
+        serverInfo: unknown;
+        capabilities: unknown;
+    }>;
+    /**
+     * List all available MCP tools.
+     */
+    listTools(): Promise<Array<{
+        name: string;
+        description?: string;
+        inputSchema?: unknown;
+    }>>;
+    /**
+     * Call a specific MCP tool by name.
+     */
+    callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Close the current session by sending an HTTP DELETE.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAIxD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAqB;gBAEzB,QAAQ,EAAE,kBAAkB;IAIxC;;;OAGG;IACG,qBAAqB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IA2DvD;;;OAGG;IACG,mBAAmB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAiGrD;;;;;;OAMG;IACG,sBAAsB,CAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,GACpB,OAAO,CAAC,aAAa,EAAE,CAAC;IAiI3B;;OAEG;IACG,MAAM,CACV,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,GACpB,OAAO,CAAC;QAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CA0BzE;AAcD;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,EAAE,MAAM;IAI3B;;OAEG;YACW,WAAW;IAqEzB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC;QAC1B,UAAU,EAAE,OAAO,CAAC;QACpB,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IA8CF;;OAEG;IACG,SAAS,IAAI,OAAO,CACxB,KAAK,CAAC;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC,CACH;IAqCD;;OAEG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC;IAiBnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB7B"}