@livx.cc/agentx 0.94.38

package/dist/mcp-CnzmQ8JE.d.ts

@@ -0,0 +1,101 @@
+import { A as AgentTool } from './tools-DtpN8Agv.js';
+
+/**
+ * MCP bridge — adapt a Model Context Protocol tool list into the agent's AgentTool[],
+ * so any MCP server's tools become first-class agent tools (edge-safe: you supply the
+ * transport via `callTool`; this module has no node/network dependency of its own).
+ *
+ * Pass the server's advertised tools + a `callTool(name, args)` that performs the call
+ * (over stdio/HTTP/whatever you wire up); each becomes an AgentTool the Agent can use.
+ */
+interface McpToolSpec {
+    name: string;
+    description?: string;
+    /** JSON Schema for the tool's arguments (MCP's `inputSchema`). */
+    inputSchema?: object;
+}
+/** Perform an MCP tool call; return its textual result. Throw to surface an error to the model. */
+type McpCall = (name: string, args: any) => Promise<unknown>;
+interface McpImage {
+    mimeType: string;
+    data: string;
+}
+interface McpToolResult {
+    text: string;
+    images?: McpImage[];
+}
+/** Adapt one MCP tool spec into an AgentTool backed by `callTool`. */
+declare function mcpToolToAgentTool(spec: McpToolSpec, callTool: McpCall, prefix?: string): AgentTool;
+/** Adapt a whole MCP tool list into AgentTool[] (names prefixed to avoid collisions).
+ *  Optional `filter` pre-narrows the set at mount time (host allowlist), so a server with
+ *  hundreds of tools needn't mount them all eagerly. */
+declare function mcpToolsToAgentTools(specs: McpToolSpec[], callTool: McpCall, prefix?: string, filter?: (spec: McpToolSpec) => boolean): AgentTool[];
+interface McpToolSearchOptions {
+    /** Prefix stripped from / shown on tool names (cosmetic; mirrors the adapter prefix). Default 'mcp__'. */
+    prefix?: string;
+    /** Max tools returned per `ToolSearch` query. Default 10. */
+    maxResults?: number;
+}
+/**
+ * Deferred-mount mode (ToolSearch-equivalent) for large MCP tool sets. Instead of mounting N
+ * tools into the wire schema (cost + latency + model confusion past a few dozen), mount exactly
+ * TWO bounded tools regardless of N:
+ *   - `ToolSearch({ query })` — ranks the catalog by relevance and returns the top matches with
+ *      their argument schemas, so the model discovers what's available on demand.
+ *   - `McpCall({ name, args })` — invokes any catalog tool by name through the same transport.
+ * Keep `mcpToolsToAgentTools` (eager) as the default for small sets.
+ */
+declare function makeMcpToolSearch(specs: McpToolSpec[], callTool: McpCall, options?: McpToolSearchOptions): AgentTool[];
+/** Minimal shape of a mounted MCP server this module needs — structurally satisfied by
+ *  `MountedMcp` from `mcp.client.ts`, kept local so `mcp.ts` stays node-free/edge-safe. */
+interface MountedMcpLike {
+    name: string;
+    specs: McpToolSpec[];
+    client: {
+        callTool(name: string, args: unknown): Promise<unknown>;
+    };
+}
+/** A flattened catalog entry's origin: which server owns it + the un-prefixed raw tool name. */
+interface McpRoute {
+    server: string;
+    rawName: string;
+}
+/** Flatten servers' specs into one `mcp__<server>__<tool>` namespace + a display→origin map.
+ *  Sanitizing/truncating to provider name rules can MERGE distinct names (`a/b` & `a:b` → `a_b`),
+ *  so dedupe with a numeric suffix — a silent overwrite would orphan a tool. */
+declare function buildMcpCatalog(servers: {
+    name: string;
+    specs: McpToolSpec[];
+}[]): {
+    specs: McpToolSpec[];
+    routes: Map<string, McpRoute>;
+};
+/** Resolve a routed MCP call to its result. Throw to surface an error to the model. */
+type McpRouteResolver = (server: string, rawName: string, args: any) => Promise<unknown>;
+/**
+ * Ergonomic deferred-mount over already-mounted MCP servers: flattens their specs into one
+ * `mcp__<server>__<tool>` namespace and wires a single `ToolSearch`/`McpCall` pair that routes
+ * each call to the owning server's RAW `callTool` (so result normalization happens exactly once —
+ * double-normalizing corrupts image blocks).
+ */
+declare function makeMcpToolSearchFromMounted(mounted: MountedMcpLike[], options?: McpToolSearchOptions): {
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+};
+/**
+ * Lazy variant: same `ToolSearch`/`McpCall` surface, but the server isn't required to be connected.
+ * Each `McpCall` resolves the owning server from the catalog and `resolve(server, rawName, args)`
+ * connects-on-demand — so a turn that calls no MCP tool opens ZERO connections. Edge-safe: the
+ * caller (`mountMcpCatalog` in `mcp.client.ts`) supplies the node-side connect/pool logic.
+ */
+declare function makeLazyMcpToolSearch(servers: {
+    name: string;
+    specs: McpToolSpec[];
+}[], resolve: McpRouteResolver, options?: McpToolSearchOptions): {
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+};
+
+export { type McpCall as M, type McpImage as a, type McpRoute as b, type McpRouteResolver as c, type McpToolResult as d, type McpToolSearchOptions as e, type McpToolSpec as f, type MountedMcpLike as g, buildMcpCatalog as h, makeMcpToolSearch as i, makeMcpToolSearchFromMounted as j, mcpToolToAgentTool as k, mcpToolsToAgentTools as l, makeLazyMcpToolSearch as m };

package/dist/mcp.client.d.ts

@@ -0,0 +1,228 @@
+import { e as McpToolSearchOptions, f as McpToolSpec } from './mcp-CnzmQ8JE.js';
+import { A as AgentTool } from './tools-DtpN8Agv.js';
+import '@livx.cc/wcli/core';
+
+/** A JSON-RPC 2.0 transport: request (awaits a result), notify (fire-and-forget), close. */
+interface McpTransport {
+    start(): Promise<void>;
+    request(method: string, params?: unknown): Promise<any>;
+    notify(method: string, params?: unknown): Promise<void>;
+    close(): Promise<void>;
+}
+interface StdioServerSpec {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    timeoutMs?: number;
+}
+declare class StdioTransport implements McpTransport {
+    private spec;
+    private proc?;
+    private buf;
+    private nextId;
+    private pending;
+    constructor(spec: StdioServerSpec);
+    start(): Promise<void>;
+    private onData;
+    private dispatch;
+    private failAll;
+    private write;
+    request(method: string, params?: unknown): Promise<any>;
+    notify(method: string, params?: unknown): Promise<void>;
+    close(): Promise<void>;
+}
+interface HttpServerSpec {
+    url: string;
+    headers?: Record<string, string>;
+    /** Sugar over `headers` → `Authorization: Bearer <token>`. The headless-friendly path (no OAuth loopback);
+     *  inject a static token (from env / VFS secret) per our CLAUDE.md rule preferring API keys for cron/edge. */
+    bearerToken?: string;
+    timeoutMs?: number;
+}
+/** Thrown when an HTTP MCP server rejects auth (401/403). Carries `needsAuth` so callers can surface a hint
+ *  ("set bearerToken / headers") instead of a generic mount failure — without attempting an interactive flow. */
+declare class McpAuthError extends Error {
+    status: number;
+    serverName?: string | undefined;
+    needsAuth: boolean;
+    constructor(status: number, serverName?: string | undefined);
+}
+declare class HttpTransport implements McpTransport {
+    private spec;
+    private nextId;
+    private sessionId?;
+    private fetchImpl;
+    constructor(spec: HttpServerSpec, fetchImpl?: typeof fetch);
+    start(): Promise<void>;
+    request(method: string, params?: unknown): Promise<any>;
+    notify(method: string, params?: unknown): Promise<void>;
+    private post;
+    close(): Promise<void>;
+}
+declare class McpClient {
+    transport: McpTransport;
+    private clientInfo;
+    constructor(transport: McpTransport, clientInfo?: {
+        name: string;
+        version: string;
+    });
+    /** `initialize` handshake → `notifications/initialized`. Returns the server's init result. */
+    connect(): Promise<{
+        serverInfo?: {
+            name?: string;
+            version?: string;
+        };
+        capabilities?: any;
+    }>;
+    listTools(): Promise<McpToolSpec[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+    listResources(): Promise<Array<{
+        uri: string;
+        name?: string;
+        mimeType?: string;
+    }>>;
+    readResource(uri: string): Promise<any>;
+    close(): Promise<void>;
+}
+/** One server: stdio (`command`+`args`+`env`) OR http (`url`+`headers`). `disabled` skips it. */
+interface McpServerConfig {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    /** `Authorization: Bearer <token>` sugar for http servers (headless-friendly; no OAuth flow). */
+    bearerToken?: string;
+    /** Auth strategy for http servers. `'oauth'` → the CLI resolves a token via the attended OAuth flow
+     *  (cli/mcpOAuth.ts) and injects it as `bearerToken` at mount; the core never runs the flow. Default none. */
+    auth?: 'oauth' | 'none';
+    timeoutMs?: number;
+    disabled?: boolean;
+}
+interface MountedMcp {
+    name: string;
+    client: McpClient;
+    tools: AgentTool[];
+    /** Raw tool specs discovered at mount (already fetched internally) — exposed so deferred-mount
+     *  glue (`makeMcpToolSearchFromMounted`) needn't re-call `tools/list`. */
+    specs: McpToolSpec[];
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    /** The config this server was mounted with — lets a host remount it (`/mcp reconnect`). */
+    config: McpServerConfig;
+}
+/** Connect one server, discover its tools, and adapt them to prefixed AgentTools (`mcp__<name>__`). */
+declare function mountMcpServer(name: string, cfg: McpServerConfig): Promise<MountedMcp>;
+/**
+ * Mount every configured server in PARALLEL (one slow/dead server no longer serializes the rest);
+ * each may carry a `mountTimeoutMs` deadline. A server that fails is logged and skipped.
+ */
+declare function mountMcpServers(servers?: Record<string, McpServerConfig>, opts?: {
+    mountTimeoutMs?: number;
+}): Promise<MountedMcp[]>;
+/**
+ * One-shot deferred MCP mount: connect every entry (failures dropped, never block startup) and
+ * fold the survivors into a single `ToolSearch`/`McpCall` pair via `makeMcpToolSearchFromMounted`.
+ * The node-only counterpart to that edge-safe helper — returns `mounted` too so callers can close
+ * the clients on shutdown. Eager: it connects all servers up front. For lazy connect + a cached
+ * catalog (zero connections on a turn that uses no MCP tool), use `mountMcpCatalog`.
+ */
+declare function mountMcpDeferred(servers?: Record<string, McpServerConfig>, options?: McpToolSearchOptions & {
+    mountTimeoutMs?: number;
+}): Promise<{
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+    mounted: MountedMcp[];
+}>;
+/** A persistent tool catalog: lets `mountMcpCatalog` build `ToolSearch` WITHOUT connecting when a
+ *  fresh entry exists. The lib defines the interface; the consumer supplies the store (RAM/disk).
+ *  Key = a hash of the server's resolved config (see `mcpConfigKey`). TTL/versioning is the store's. */
+interface McpCatalogStore {
+    get(key: string): McpToolSpec[] | null;
+    set(key: string, specs: McpToolSpec[]): void;
+}
+/** Stable cache key for a server config — command/args/cwd + env NAMES (not secret values), or
+ *  url + header names. Changing any of these invalidates the cached catalog; rotating a secret does not. */
+declare function mcpConfigKey(cfg: McpServerConfig): string;
+/** Default in-memory catalog: process-lifetime, hash-keyed, TTL-expiring (so a server that gains
+ *  tools is picked up after the TTL without a restart). Shared module singleton → cross-turn reuse. */
+declare class MemMcpCatalog implements McpCatalogStore {
+    private ttlMs;
+    private m;
+    constructor(ttlMs?: number);
+    get(key: string): McpToolSpec[] | null;
+    set(key: string, specs: McpToolSpec[]): void;
+}
+/** Opt-in warm pool: keeps stdio MCP clients connected across turns, reaping each after `ttlMs`
+ *  idle. Most stdio MCPs are per-turn by design, so this is off by default; HTTP servers are
+ *  stateless and never pooled. */
+declare class McpPool {
+    private ttlMs;
+    private warm;
+    constructor(ttlMs?: number);
+    get(key: string): McpClient | null;
+    put(key: string, client: McpClient): void;
+    private arm;
+    private evict;
+    closeAll(): Promise<void>;
+}
+interface McpCatalogOptions extends McpToolSearchOptions {
+    /** Where to read/write discovered specs. Default: a shared process-lifetime `MemMcpCatalog`. */
+    catalog?: McpCatalogStore;
+    /** Per-server deadline for the connect+list on a cache MISS. A hung server is skipped, not blocking. */
+    mountTimeoutMs?: number;
+    /** Opt-in: keep stdio clients warm across turns (see `McpPool`). HTTP servers are never pooled. */
+    keepWarm?: boolean;
+    /** Warm-client pool. Default: a shared process-lifetime `McpPool` (only used when `keepWarm`). */
+    pool?: McpPool;
+    /** Negative cache: after a server fails/times out discovery, skip it for this long so it never
+     *  re-floors a turn at the deadline. Default 60s; the server is re-probed once the cooldown lapses. */
+    failureCooldownMs?: number;
+    /** Shared failure-cooldown map (configKey → until-epoch-ms). Default: a process-lifetime singleton. */
+    failures?: Map<string, number>;
+    /** Discovery policy on a cache MISS:
+     *  - `'connect'` (default): synchronously connect+list (deadline-bounded) — blocks until ready.
+     *  - `'cache-only'`: NEVER block the turn — serve only cached servers, and kick uncached discovery
+     *    to the background (so it's warm next turn). Pair with a boot/timer `warmMcpCatalog` so the
+     *    first turn is already a cache hit. */
+    discover?: 'connect' | 'cache-only';
+}
+/**
+ * Lazy + cached MCP mount. Builds the `ToolSearch`/`McpCall` pair from the CACHED catalog when one
+ * exists — connecting NOTHING. On a cache miss it (by default) connects once (parallel, deadline-
+ * bounded), lists, caches, then disconnects (or keeps warm if `keepWarm`). A server is connected only
+ * when one of its tools is actually invoked via `McpCall` (memoized per turn; reused from the warm
+ * pool if enabled). A server that fails/times out is negative-cached (`failureCooldownMs`) so it
+ * never re-floors a later turn.
+ *
+ * For zero turn-path latency even on a cold process, set `discover: 'cache-only'` and call
+ * `warmMcpCatalog` at boot + on a timer: the turn then NEVER synchronously connects — it serves
+ * cached servers and warms the rest in the background.
+ *
+ * Per-turn cost: a turn using NO MCP tool → 0 connections; a turn using one → exactly one.
+ */
+declare function mountMcpCatalog(servers?: Record<string, McpServerConfig>, opts?: McpCatalogOptions): Promise<{
+    tools: AgentTool[];
+    serverNames: string[];
+    toolCount: number;
+    connect(name: string): Promise<McpClient>;
+    close(): Promise<void>;
+}>;
+/**
+ * Off-turn catalog warm-up: do the one cold discovery pass (connect + list, parallel, deadline-
+ * bounded) so a later `mountMcpCatalog(..., { discover: 'cache-only' })` is a cache HIT. Call at
+ * server boot and on a timer (cadence < the catalog TTL). Cache hits cost nothing; down servers are
+ * negative-cached so turns never touch them. Returns which servers warmed vs failed.
+ */
+declare function warmMcpCatalog(servers?: Record<string, McpServerConfig>, opts?: McpCatalogOptions): Promise<{
+    warmed: string[];
+    failed: string[];
+    toolCount: number;
+}>;
+
+export { type HttpServerSpec, HttpTransport, McpAuthError, type McpCatalogOptions, type McpCatalogStore, McpClient, McpPool, type McpServerConfig, type McpTransport, MemMcpCatalog, type MountedMcp, type StdioServerSpec, StdioTransport, mcpConfigKey, mountMcpCatalog, mountMcpDeferred, mountMcpServer, mountMcpServers, warmMcpCatalog };