agentfootprint 2.1.0 → 2.2.0

package/dist/types/lib/mcp/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * MCP — Model Context Protocol client integration.
+ *
+ * MCP (https://modelcontextprotocol.io) is an open standard for
+ * connecting LLMs to external tools and data sources. agentfootprint's
+ * MCP adapter is **client-only** — it consumes MCP servers and exposes
+ * their tools as agentfootprint `Tool[]` so consumers can plug them
+ * straight into `agent.tool(...)`.
+ *
+ * Pattern: Adapter (GoF) — translates MCP wire format ↔ agentfootprint
+ *          `Tool` interface. The MCP SDK does the protocol work; we
+ *          just bridge.
+ * Role:    Layer-3 tool integration. Pairs with `defineTool` (the
+ *          inline alternative for non-MCP tools).
+ * Emits:   N/A directly — wrapped tools emit the standard
+ *          `agentfootprint.stream.tool_start` / `tool_end` events
+ *          when the agent calls them.
+ *
+ * Server-side support (exposing an agent or LLMCall as an MCP tool)
+ * is a separate concern not yet shipped. This module covers the
+ * 80% case: pulling an existing MCP server's tools INTO an agent.
+ */
+import type { Tool } from '../../core/tools.js';
+/**
+ * `stdio` transport — spawns a local subprocess and speaks MCP over
+ * its stdin/stdout. Best for development, single-user scenarios, and
+ * testing against locally-installed MCP servers.
+ */
+export interface McpStdioTransport {
+    readonly transport: 'stdio';
+    /** Executable to spawn (e.g., `'npx'`, `'node'`, `'python'`). */
+    readonly command: string;
+    /** CLI args passed to the executable. */
+    readonly args?: readonly string[];
+    /** Optional env vars set on the subprocess. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Working directory for the subprocess. */
+    readonly cwd?: string;
+}
+/**
+ * `http` transport — speaks MCP over Streamable HTTP. Best for remote
+ * servers, web environments, and multi-user scenarios.
+ */
+export interface McpHttpTransport {
+    readonly transport: 'http';
+    /** MCP server endpoint URL. */
+    readonly url: string;
+    /** Optional auth headers (e.g., `Authorization: Bearer ...`). */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export type McpTransport = McpStdioTransport | McpHttpTransport;
+export interface McpClientOptions {
+    /**
+     * Logical name for observability + tool-call routing. Surfaces in
+     * Lens chips and event payloads. Defaults to `'mcp'`. Recommend
+     * setting per-server (`'slack-mcp'`, `'github-mcp'`) when you
+     * connect to multiple servers.
+     */
+    readonly name?: string;
+    /** Transport configuration — stdio or http. */
+    readonly transport: McpTransport;
+    /**
+     * Optional client identity sent on connect. Default:
+     * `{ name: 'agentfootprint', version: <package version> }`.
+     */
+    readonly clientInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Abort the connection / list / call paths. Honored by the SDK. */
+    readonly signal?: AbortSignal;
+    /**
+     * @internal Pre-built SDK client for tests. Skips SDK import +
+     * transport construction. Same convention as `AnthropicProvider._client`.
+     */
+    readonly _client?: McpSdkClient;
+}
+/**
+ * What `mcpClient(opts)` returns. Connect once; call `.tools()` to
+ * snapshot the tool list, `.refresh()` to re-list after the server's
+ * tools change, `.close()` when done.
+ */
+export interface McpClient {
+    /** Logical name from options (or default `'mcp'`). */
+    readonly name: string;
+    /**
+     * List the server's tools as agentfootprint `Tool[]`. First call
+     * after `mcpClient(...)` is the snapshot used to register on the
+     * agent; subsequent calls re-fetch (cheap, in-memory cached by the
+     * SDK between fetches).
+     */
+    tools(): Promise<readonly Tool[]>;
+    /**
+     * Force a refresh from the server. Use when you suspect the server
+     * has dynamically added/removed tools mid-session (e.g., after the
+     * server processes a config update).
+     */
+    refresh(): Promise<readonly Tool[]>;
+    /** Close the underlying transport. After `close()` the client is unusable. */
+    close(): Promise<void>;
+}
+/**
+ * Minimal structural type capturing the parts of the MCP SDK client
+ * we touch. Defined locally so we can:
+ *   1. Inject a mock for tests (`McpClientOptions._client`)
+ *   2. Avoid a hard import on `@modelcontextprotocol/sdk` (which is
+ *      a lazy peer-dep)
+ *
+ * The real SDK exports a richer surface; we narrow to what's needed.
+ */
+export interface McpSdkClient {
+    connect(transport: unknown): Promise<void>;
+    listTools(): Promise<{
+        readonly tools: ReadonlyArray<{
+            readonly name: string;
+            readonly description?: string;
+            readonly inputSchema: Readonly<Record<string, unknown>>;
+        }>;
+    }>;
+    callTool(args: {
+        readonly name: string;
+        readonly arguments?: Readonly<Record<string, unknown>>;
+    }): Promise<{
+        readonly content: ReadonlyArray<{
+            readonly type: string;
+            readonly text?: string;
+        }>;
+        readonly isError?: boolean;
+    }>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/mcp/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",