@revealui/ai 0.3.0 → 0.4.0

package/dist/tools/mcp-adapter.d.ts

@@ -1,9 +1,27 @@
 /**
  * MCP Tool Adapter
  *
- * Bridges MCP (Model Context Protocol) servers to the tool system
+ * Bridges MCP (Model Context Protocol) servers to the tool system.
+ *
+ * Two paths:
+ *
+ *   1. **Standard MCP client** (Stage 5.1a, preferred) — consumers construct an
+ *      `McpClient` from `@revealui/mcp/client` against stdio or Streamable HTTP,
+ *      and pass it to `createToolsFromMcpClient()` (or to `AgentRuntime` via
+ *      `mcpClients`). This is the full-protocol path: future stages will extend
+ *      this to resources, prompts, sampling, elicitation, etc.
+ *
+ *   2. **Hypervisor** (legacy, pre-5.1a) — consumers pass an `MCPHypervisor` (or
+ *      any `MCPToolSource`) to `discoverMCPTools()`. Kept for backwards compat;
+ *      deprecated in favor of path (1). The hypervisor still owns server-side
+ *      subprocess + tenant-scoping concerns and isn't going away.
+ *
+ * Both paths are deliberately **structurally typed** — `@revealui/ai` has no
+ * runtime dependency on `@revealui/mcp`. Consumers satisfy the shapes
+ * `McpClientLike` / `MCPToolSource` with whichever client they construct.
  */
 import type { Tool } from './base.js';
+import { type McpEventSink } from './mcp-events.js';
 export interface MCPTool {
     name: string;
     description: string;
@@ -20,6 +38,10 @@ export interface MCPClient {
 /**
  * Interface for an MCP tool source (e.g. MCPHypervisor from @revealui/mcp).
  * Using an interface here keeps @revealui/ai decoupled from @revealui/mcp.
+ *
+ * @deprecated Prefer `McpClientLike` + `createToolsFromMcpClient()` (Stage 5.1a).
+ *   The hypervisor path doesn't expose the full MCP protocol surface (resources,
+ *   prompts, sampling, elicitation). The typed-client path does.
  */
 export interface MCPToolSource {
     getAllTools(): Array<{
@@ -29,6 +51,175 @@ export interface MCPToolSource {
     }>;
     callTool(serverName: string, toolName: string, args: unknown): Promise<unknown>;
 }
+/**
+ * Structural shape of an `McpClient` from `@revealui/mcp/client`. Declared
+ * here (rather than imported) to keep `@revealui/ai` decoupled from
+ * `@revealui/mcp` at the type level. Consumers pass any object whose
+ * `listTools()` + `callTool()` methods match — the real `McpClient`
+ * structurally satisfies this shape.
+ *
+ * Returns / options are loose-typed to the spec-relevant bits; the real
+ * `McpClient` returns richer SDK types which we don't need for tool dispatch.
+ */
+export interface McpClientLike {
+    listTools(options?: unknown): Promise<ReadonlyArray<McpToolDescriptor>>;
+    callTool(name: string, args?: Record<string, unknown>, options?: unknown): Promise<McpCallToolResultLike>;
+    /**
+     * Resources (Stage 5.1b). Optional: when absent on the client, the
+     * adapter skips emitting resource meta-tools for the server regardless
+     * of `include.resources`.
+     */
+    listResources?(options?: unknown): Promise<ReadonlyArray<McpResourceDescriptor>>;
+    readResource?(uri: string, options?: unknown): Promise<ReadonlyArray<McpResourceContentLike>>;
+    /**
+     * Prompts (Stage 5.1b). Optional: when absent, prompt meta-tools are
+     * skipped for the server.
+     */
+    listPrompts?(options?: unknown): Promise<ReadonlyArray<McpPromptDescriptor>>;
+    getPrompt?(name: string, args?: Record<string, string>, options?: unknown): Promise<McpGetPromptResultLike>;
+}
+/** Subset of the spec `Tool` shape needed for agent-side discovery. */
+export interface McpToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+}
+/** Subset of the spec `CallToolResult` shape. */
+export interface McpCallToolResultLike {
+    content: ReadonlyArray<unknown>;
+    isError?: boolean;
+    structuredContent?: unknown;
+}
+/** Subset of the spec `Resource` shape needed for listing. */
+export interface McpResourceDescriptor {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}
+/** One element of `readResource`'s response — either a text or a blob content part. */
+export interface McpResourceContentLike {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+}
+/** Subset of the spec `Prompt` shape needed for listing. */
+export interface McpPromptDescriptor {
+    name: string;
+    description?: string;
+    arguments?: ReadonlyArray<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+/** Subset of the spec `GetPromptResult` shape. */
+export interface McpGetPromptResultLike {
+    description?: string;
+    messages: ReadonlyArray<{
+        role: 'user' | 'assistant' | string;
+        content: unknown;
+    }>;
+}
+export interface CreateToolsFromMcpClientOptions {
+    /**
+     * Namespace (typically the server's identifier) prepended to each tool
+     * name so collisions across multiple MCP clients are impossible.
+     * Output tool name: `mcp_<namespace>__<toolName>`.
+     */
+    namespace: string;
+    /**
+     * Optional category tag used for tool-level telemetry + UI grouping.
+     * Defaults to `'mcp'`.
+     */
+    category?: string;
+    /**
+     * Which MCP primitives to expose to the agent as tools (Stage 5.1b).
+     *
+     * - `tools` (default `true`): wrap every server tool.
+     * - `resources` (default `true`): emit two meta-tools per namespace —
+     *   `mcp_<ns>__list_resources` and `mcp_<ns>__read_resource({ uri })`.
+     *   Skipped silently when the client doesn't expose `listResources` /
+     *   `readResource`.
+     * - `prompts` (default `true`): emit two meta-tools per namespace —
+     *   `mcp_<ns>__list_prompts` and `mcp_<ns>__get_prompt({ name, args? })`.
+     *   Skipped silently when the client doesn't expose `listPrompts` /
+     *   `getPrompt`.
+     */
+    include?: {
+        tools?: boolean;
+        resources?: boolean;
+        prompts?: boolean;
+    };
+    /**
+     * Progress observability hook (Stage 5.3). Every server tool call made
+     * through the wrapped `Tool.execute()` forwards per-request progress
+     * notifications here. Resource + prompt meta-tools don't emit
+     * progress (they're single-shot lookups).
+     */
+    onProgress?: (event: McpProgressEvent) => void;
+    /**
+     * Optional `AbortSignal` forwarded to every server tool call (Stage
+     * 5.3). When the signal aborts, in-flight MCP RPC calls are
+     * cancelled via `notifications/cancelled` per the MCP spec. Useful
+     * for wiring a consumer-facing cancel button into an active
+     * agent run. Resource/prompt meta-tools also receive the signal.
+     */
+    signal?: AbortSignal;
+    /**
+     * Protocol-level observability sink (Stage 6.1). Fires exactly once
+     * per tool / resource / prompt call with a structured summary
+     * (`namespace`, operation, `duration_ms`, `success`, `error?`). See
+     * `./mcp-events.ts` for the event shapes and `createCoreLoggerSink()`
+     * for the default routing to `@revealui/core/observability/logger`.
+     * Safe to pass a throwing sink — adapter swallows sink errors.
+     */
+    onEvent?: McpEventSink;
+}
+/** Spec-shaped `Progress` notification subset. */
+export interface McpProgressLike {
+    /** Monotonically increasing progress token value. */
+    progress: number;
+    /** Total expected units of work, when the server knows it. */
+    total?: number;
+    /** Human-readable status message. */
+    message?: string;
+}
+/** Event payload forwarded to `onProgress`. */
+export interface McpProgressEvent {
+    /** Namespace the tool belongs to (for multi-client agents). */
+    namespace: string;
+    /** Wrapped tool name that emitted the event (without the `mcp_<ns>__` prefix). */
+    toolName: string;
+    /** Progress payload as reported by the server. */
+    progress: McpProgressLike;
+}
+/**
+ * Connect the agent's tool registry to a standard MCP client. Lists tools
+ * from the MCP server and returns agent-side `Tool` instances that dispatch
+ * calls back through the client. Safe to call multiple times per server —
+ * each invocation re-reads the current tool list.
+ *
+ * @example
+ * ```typescript
+ * import { McpClient } from '@revealui/mcp/client';
+ * import { createToolsFromMcpClient } from '@revealui/ai';
+ *
+ * const client = new McpClient({
+ *   clientInfo: { name: 'my-agent', version: '1.0.0' },
+ *   transport: { kind: 'streamable-http', url: 'https://example.com/mcp' },
+ * });
+ * await client.connect();
+ *
+ * const tools = await createToolsFromMcpClient(client, {
+ *   namespace: 'example-server',
+ * });
+ *
+ * agent.tools.push(...tools);
+ * ```
+ */
+export declare function createToolsFromMcpClient(client: McpClientLike, options: CreateToolsFromMcpClientOptions): Promise<Tool[]>;
 /**
  * Create a Tool from an MCP tool definition
  */

package/dist/tools/mcp-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-adapter.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-adapter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,IAAI,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAuB9E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAa1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,CAkC9D"}
+{"version":3,"file":"mcp-adapter.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-adapter.ts"],"names":[],"mappings":"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"}

package/dist/tools/mcp-adapter.js

@@ -1,9 +1,418 @@
 /**
  * MCP Tool Adapter
  *
- * Bridges MCP (Model Context Protocol) servers to the tool system
+ * Bridges MCP (Model Context Protocol) servers to the tool system.
+ *
+ * Two paths:
+ *
+ *   1. **Standard MCP client** (Stage 5.1a, preferred) — consumers construct an
+ *      `McpClient` from `@revealui/mcp/client` against stdio or Streamable HTTP,
+ *      and pass it to `createToolsFromMcpClient()` (or to `AgentRuntime` via
+ *      `mcpClients`). This is the full-protocol path: future stages will extend
+ *      this to resources, prompts, sampling, elicitation, etc.
+ *
+ *   2. **Hypervisor** (legacy, pre-5.1a) — consumers pass an `MCPHypervisor` (or
+ *      any `MCPToolSource`) to `discoverMCPTools()`. Kept for backwards compat;
+ *      deprecated in favor of path (1). The hypervisor still owns server-side
+ *      subprocess + tenant-scoping concerns and isn't going away.
+ *
+ * Both paths are deliberately **structurally typed** — `@revealui/ai` has no
+ * runtime dependency on `@revealui/mcp`. Consumers satisfy the shapes
+ * `McpClientLike` / `MCPToolSource` with whichever client they construct.
  */
 import { z } from 'zod/v4';
+import { emitMcpEvent } from './mcp-events.js';
+/**
+ * Connect the agent's tool registry to a standard MCP client. Lists tools
+ * from the MCP server and returns agent-side `Tool` instances that dispatch
+ * calls back through the client. Safe to call multiple times per server —
+ * each invocation re-reads the current tool list.
+ *
+ * @example
+ * ```typescript
+ * import { McpClient } from '@revealui/mcp/client';
+ * import { createToolsFromMcpClient } from '@revealui/ai';
+ *
+ * const client = new McpClient({
+ *   clientInfo: { name: 'my-agent', version: '1.0.0' },
+ *   transport: { kind: 'streamable-http', url: 'https://example.com/mcp' },
+ * });
+ * await client.connect();
+ *
+ * const tools = await createToolsFromMcpClient(client, {
+ *   namespace: 'example-server',
+ * });
+ *
+ * agent.tools.push(...tools);
+ * ```
+ */
+export async function createToolsFromMcpClient(client, options) {
+    if (!(options.namespace && /^[a-zA-Z0-9_-]+$/.test(options.namespace))) {
+        throw new Error(`createToolsFromMcpClient: namespace must be a non-empty string of [a-zA-Z0-9_-], got ${JSON.stringify(options.namespace)}`);
+    }
+    const category = options.category ?? 'mcp';
+    const includeTools = options.include?.tools !== false;
+    const includeResources = options.include?.resources !== false;
+    const includePrompts = options.include?.prompts !== false;
+    const ctx = {
+        namespace: options.namespace,
+        category,
+        ...(options.onProgress !== undefined ? { onProgress: options.onProgress } : {}),
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(options.onEvent !== undefined ? { onEvent: options.onEvent } : {}),
+    };
+    const tools = [];
+    // --- Server tools (Stage 5.1a) -----------------------------------------
+    if (includeTools) {
+        const descriptors = await client.listTools();
+        for (const descriptor of descriptors) {
+            tools.push(buildServerTool(client, descriptor, ctx));
+        }
+    }
+    // --- Resource meta-tools (Stage 5.1b) ----------------------------------
+    if (includeResources && client.listResources && client.readResource) {
+        tools.push(buildListResourcesTool(client, ctx));
+        tools.push(buildReadResourceTool(client, ctx));
+    }
+    // --- Prompt meta-tools (Stage 5.1b) ------------------------------------
+    if (includePrompts && client.listPrompts && client.getPrompt) {
+        tools.push(buildListPromptsTool(client, ctx));
+        tools.push(buildGetPromptTool(client, ctx));
+    }
+    return tools;
+}
+/**
+ * Build the request-options object passed to `client.callTool()` /
+ * `readResource()` / etc. Wraps the ctx's `onProgress` with the
+ * specific tool name + namespace so every emitted event is attributable.
+ */
+function buildRequestOptions(ctx, toolName) {
+    const opts = {};
+    if (ctx.onProgress) {
+        const emit = ctx.onProgress;
+        opts.onProgress = (progress) => emit({ namespace: ctx.namespace, toolName, progress });
+    }
+    if (ctx.signal)
+        opts.signal = ctx.signal;
+    return opts.onProgress || opts.signal ? opts : undefined;
+}
+function buildServerTool(client, descriptor, ctx) {
+    const zodSchema = jsonSchemaObjectToZod(descriptor.inputSchema);
+    const namespacedName = `mcp_${ctx.namespace}__${descriptor.name}`;
+    return {
+        name: namespacedName,
+        label: descriptor.name,
+        description: descriptor.description ?? `${ctx.namespace}: ${descriptor.name}`,
+        parameters: zodSchema,
+        async execute(params) {
+            const validated = zodSchema.parse(params);
+            const started = Date.now();
+            try {
+                const result = await client.callTool(descriptor.name, validated, buildRequestOptions(ctx, descriptor.name));
+                if (result.isError) {
+                    const errorText = extractErrorText(result);
+                    emitMcpEvent(ctx.onEvent, {
+                        kind: 'mcp.tool.call',
+                        namespace: ctx.namespace,
+                        toolName: descriptor.name,
+                        duration_ms: Date.now() - started,
+                        success: false,
+                        error: errorText,
+                    });
+                    return { success: false, error: errorText };
+                }
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.tool.call',
+                    namespace: ctx.namespace,
+                    toolName: descriptor.name,
+                    duration_ms: Date.now() - started,
+                    success: true,
+                });
+                const payload = result.structuredContent ?? result.content;
+                return { success: true, data: serializeMCPResult(payload) };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.tool.call',
+                    namespace: ctx.namespace,
+                    toolName: descriptor.name,
+                    duration_ms: Date.now() - started,
+                    success: false,
+                    error: message,
+                });
+                return { success: false, error: message };
+            }
+        },
+        getMetadata() {
+            return { category: ctx.category, version: '1.0.0', mcpNamespace: ctx.namespace };
+        },
+    };
+}
+function buildListResourcesTool(client, ctx) {
+    return {
+        name: `mcp_${ctx.namespace}__list_resources`,
+        label: 'list_resources',
+        description: `List resources exposed by the ${ctx.namespace} MCP server. Returns an array of { uri, name, description?, mimeType? }.`,
+        parameters: z.object({}),
+        async execute() {
+            const started = Date.now();
+            try {
+                const resources = (await client.listResources?.(buildRequestOptions(ctx, 'list_resources'))) ?? [];
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.resource.list',
+                    namespace: ctx.namespace,
+                    duration_ms: Date.now() - started,
+                    success: true,
+                    resourceCount: resources.length,
+                });
+                return { success: true, data: serializeMCPResult(resources) };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.resource.list',
+                    namespace: ctx.namespace,
+                    duration_ms: Date.now() - started,
+                    success: false,
+                    error: message,
+                });
+                return { success: false, error: message };
+            }
+        },
+        getMetadata() {
+            return {
+                category: ctx.category,
+                version: '1.0.0',
+                mcpNamespace: ctx.namespace,
+                kind: 'resources',
+            };
+        },
+    };
+}
+function buildReadResourceTool(client, ctx) {
+    const paramsSchema = z.object({
+        uri: z.string().min(1).describe('Resource URI to read (e.g. revealui-content://posts/abc)'),
+    });
+    return {
+        name: `mcp_${ctx.namespace}__read_resource`,
+        label: 'read_resource',
+        description: `Read a resource by URI from the ${ctx.namespace} MCP server. Returns the resource contents (text parts flattened to a joined string when possible).`,
+        parameters: paramsSchema,
+        async execute(params) {
+            const { uri } = paramsSchema.parse(params);
+            const started = Date.now();
+            try {
+                const contents = (await client.readResource?.(uri, buildRequestOptions(ctx, 'read_resource'))) ?? [];
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.resource.read',
+                    namespace: ctx.namespace,
+                    uri,
+                    duration_ms: Date.now() - started,
+                    success: true,
+                });
+                const joinedText = flattenResourceText(contents);
+                const base = {
+                    success: true,
+                    data: serializeMCPResult(contents),
+                };
+                return joinedText !== undefined ? { ...base, content: joinedText } : base;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.resource.read',
+                    namespace: ctx.namespace,
+                    uri,
+                    duration_ms: Date.now() - started,
+                    success: false,
+                    error: message,
+                });
+                return { success: false, error: message };
+            }
+        },
+        getMetadata() {
+            return {
+                category: ctx.category,
+                version: '1.0.0',
+                mcpNamespace: ctx.namespace,
+                kind: 'resources',
+            };
+        },
+    };
+}
+function buildListPromptsTool(client, ctx) {
+    return {
+        name: `mcp_${ctx.namespace}__list_prompts`,
+        label: 'list_prompts',
+        description: `List prompts exposed by the ${ctx.namespace} MCP server. Returns an array of { name, description?, arguments? }.`,
+        parameters: z.object({}),
+        async execute() {
+            const started = Date.now();
+            try {
+                const prompts = (await client.listPrompts?.(buildRequestOptions(ctx, 'list_prompts'))) ?? [];
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.prompt.list',
+                    namespace: ctx.namespace,
+                    duration_ms: Date.now() - started,
+                    success: true,
+                    promptCount: prompts.length,
+                });
+                return { success: true, data: serializeMCPResult(prompts) };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.prompt.list',
+                    namespace: ctx.namespace,
+                    duration_ms: Date.now() - started,
+                    success: false,
+                    error: message,
+                });
+                return { success: false, error: message };
+            }
+        },
+        getMetadata() {
+            return {
+                category: ctx.category,
+                version: '1.0.0',
+                mcpNamespace: ctx.namespace,
+                kind: 'prompts',
+            };
+        },
+    };
+}
+function buildGetPromptTool(client, ctx) {
+    const paramsSchema = z.object({
+        name: z.string().min(1).describe('Prompt name to retrieve'),
+        args: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Prompt arguments as a string-valued map (per MCP spec)'),
+    });
+    return {
+        name: `mcp_${ctx.namespace}__get_prompt`,
+        label: 'get_prompt',
+        description: `Get a resolved prompt from the ${ctx.namespace} MCP server. Returns { description?, messages } — messages is an array of { role, content }.`,
+        parameters: paramsSchema,
+        async execute(params) {
+            const { name, args } = paramsSchema.parse(params);
+            const started = Date.now();
+            try {
+                const result = await client.getPrompt?.(name, args, buildRequestOptions(ctx, 'get_prompt'));
+                if (!result) {
+                    const msg = 'client does not implement getPrompt';
+                    emitMcpEvent(ctx.onEvent, {
+                        kind: 'mcp.prompt.get',
+                        namespace: ctx.namespace,
+                        promptName: name,
+                        duration_ms: Date.now() - started,
+                        success: false,
+                        error: msg,
+                    });
+                    return { success: false, error: msg };
+                }
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.prompt.get',
+                    namespace: ctx.namespace,
+                    promptName: name,
+                    duration_ms: Date.now() - started,
+                    success: true,
+                });
+                const joinedText = flattenPromptMessages(result.messages);
+                const base = {
+                    success: true,
+                    data: serializeMCPResult(result),
+                };
+                return joinedText !== undefined ? { ...base, content: joinedText } : base;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                emitMcpEvent(ctx.onEvent, {
+                    kind: 'mcp.prompt.get',
+                    namespace: ctx.namespace,
+                    promptName: name,
+                    duration_ms: Date.now() - started,
+                    success: false,
+                    error: message,
+                });
+                return { success: false, error: message };
+            }
+        },
+        getMetadata() {
+            return {
+                category: ctx.category,
+                version: '1.0.0',
+                mcpNamespace: ctx.namespace,
+                kind: 'prompts',
+            };
+        },
+    };
+}
+/**
+ * Collapse an array of resource contents to a single text string when every
+ * part carries text. Returns `undefined` if any part is binary (blob) or has
+ * no text, signaling the caller that a token-efficient summary isn't
+ * available — in which case the full `data` array still carries everything.
+ */
+function flattenResourceText(contents) {
+    if (contents.length === 0)
+        return undefined;
+    const parts = [];
+    for (const part of contents) {
+        if (typeof part.text === 'string') {
+            parts.push(part.text);
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Collapse a prompt's message array to a single text summary in
+ * `<role>: <text>` format. Returns `undefined` when any message has a
+ * non-text content shape (image, resource reference, …).
+ */
+function flattenPromptMessages(messages) {
+    if (messages.length === 0)
+        return undefined;
+    const lines = [];
+    for (const msg of messages) {
+        const text = extractMessageText(msg.content);
+        if (text === undefined)
+            return undefined;
+        lines.push(`${msg.role}: ${text}`);
+    }
+    return lines.join('\n\n');
+}
+function extractMessageText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content && typeof content === 'object') {
+        const c = content;
+        if (c.type === 'text' && typeof c.text === 'string')
+            return c.text;
+    }
+    return undefined;
+}
+/**
+ * Extract a human-readable error string from an MCP `CallToolResult` that
+ * came back with `isError: true`. Servers put the error detail in `content`
+ * per spec; we concatenate any text parts.
+ */
+function extractErrorText(result) {
+    const texts = [];
+    for (const part of result.content) {
+        if (part && typeof part === 'object') {
+            const p = part;
+            if (p.type === 'text' && typeof p.text === 'string') {
+                texts.push(p.text);
+            }
+        }
+    }
+    return texts.length > 0 ? texts.join('\n') : 'Tool reported error (no detail)';
+}
 /**
  * Create a Tool from an MCP tool definition
  */
@@ -108,6 +517,30 @@ export function discoverMCPTools(source) {
         return agentTool;
     });
 }
+/**
+ * Narrow an untyped `inputSchema` from a spec `Tool` into the shape
+ * `jsonSchemaToZod` understands, then delegate. Falls back to a permissive
+ * `z.object({})` when the input is malformed so tool discovery never hard-fails
+ * on a misbehaving server.
+ */
+function jsonSchemaObjectToZod(raw) {
+    if (!(raw && typeof raw === 'object'))
+        return z.object({});
+    const s = raw;
+    if (s.type !== 'object')
+        return z.object({});
+    const properties = s.properties && typeof s.properties === 'object'
+        ? s.properties
+        : undefined;
+    const required = Array.isArray(s.required)
+        ? s.required.filter((r) => typeof r === 'string')
+        : undefined;
+    return jsonSchemaToZod({
+        type: 'object',
+        ...(properties !== undefined ? { properties } : {}),
+        ...(required !== undefined ? { required } : {}),
+    });
+}
 /**
  * Convert JSON Schema to Zod schema (simplified version)
  * For production, use a proper library like json-schema-to-zod