Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
feat(mcp): pass MCP images to the model through a helper shared with plugins
Asyfdzaky5d01559df993
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1f7d930b..29147eb9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,7 @@### MCP servers (ADR-029)- **MCP servers: Mercury can use tools from Model Context Protocol servers.** Add a local server (`mercury mcp add files --stdio npx -- -y @modelcontextprotocol/server-filesystem ~/Documents`) or a remote one (`--http <url>`), allow the tools you want (`mercury mcp allow`), and the agent can call them next to its built-in tools. Every MCP call asks first in Ask Me mode, and Allow All does not cover MCP tools; only tools you list in `autoApprove` run without a prompt, and only those run when nobody can be asked. Secrets stay in `.env` as `${env:NAME}` references and are masked everywhere they could appear. Local servers get a minimal environment, never Mercury's API keys, and remote servers go through the SSRF guard. Check health with `mercury mcp test`, `mercury doctor --mcp`, `/mcp` in chat, or the new read-only **MCP** dashboard page. The agent's file tools now always ask before writing `mercury.yaml`, `permissions.yaml` or `.env`, even under Allow All. See [MCP Servers](https://mercuryagent.sh/docs/integrations/mcp) and ADR-029.- **Allow All in the terminal, the web dashboard and Mercury Cloud no longer skips MCP prompts.** The terminal attached to the background service (what `mercury` opens), the dashboard and Cloud sessions share one web channel, and in Allow All it answered every approval with yes on its own. So MCP tool calls, shell commands that change MCP setup, and writes to `mercury.yaml`, `permissions.yaml` or `.env` ran without asking there. They now ask in every channel, as documented. Other prompts still follow the session's mode.+- **MCP tools can show the model pictures.** Up to 4 images per call (PNG, JPEG, WebP or GIF) from an MCP server now reach the model as images, the same way plugin screenshots do, when the model and provider can take images in tool results (Anthropic, and OpenAI's Responses API). Elsewhere the model is told an image was left out. Chat history and logs keep only the text, never the base64.### Plugins- **Plugin images reach the model only where the provider can take them.** On Chat Completions providers (Mercury Cloud, GitHub Copilot, Ollama, LM Studio, LiteLLM, AI/ML API and other OpenAI-compatible endpoints) the AI SDK sent a plugin's screenshot as JSON text, so the model got megabytes of base64 instead of a picture. Images in tool results now go only to Anthropic and to OpenAI's Responses API; every other provider, Grok and ChatGPT Web included until they are verified, gets the usual "this model can't view images" note.diff --git a/DECISIONS.md b/DECISIONS.mdindex 0f55481a..1f1927c0 100644--- a/DECISIONS.md+++ b/DECISIONS.md@@ -273,7 +273,7 @@- **Process and secrets.** A stdio server starts from the SDK's `getDefaultEnvironment()` plus its own configured `env`, never the daemon's environment, so provider keys loaded from `.env` never reach a third-party process. `${env:NAME}` references are resolved at connect time only, never in `loadConfig`, because `saveConfig` rewrites the whole file and would otherwise write secrets into YAML. Resolved values are registered with the redaction layer.- **HTTP.** Requests go through the SSRF guard. Private and loopback targets need a per-server `allowPrivate: true`, which only the owner can set.- **Lifecycle.** The process that runs the Agent owns the connections: the daemon (ADR-024), or the terminal where no daemon runs. Servers connect in the background at boot with a timeout, so one broken server never blocks startup or other tools.- - **Results.** Converted to strings, so the existing compaction can shrink them. Results are capped, and image and audio blocks become placeholders for now.+ - **Results.** Converted to strings, so the existing compaction can shrink them. Results are capped. Up to 4 supported images per call are held by tool call id and attached in `toModelOutput` through the helper the plugin bridge also uses (`src/capabilities/tool-images.ts`), only when the model and provider can take images in tool results; audio and other media become placeholders.- **Configuration.** Adding or enabling a server is an owner action through `mercury.yaml` or `mercury mcp …`. The agent has no tool for it.- **Spike results** (Windows x64, Node 22.12, Bun 1.3.8):- The v2 client connects, lists tools, calls them and receives `tools/list_changed` over stdio. Over Streamable HTTP it uses a caller-supplied `fetch` with static headers. These are covered by `src/capabilities/mcp/sdk-smoke.test.ts` against a dependency-free fixture server.@@ -289,9 +289,9 @@- **Consequence**: Owners can use the MCP ecosystem without a hand-written capability per integration. Every third-party call is visible in Ask Me mode unless the owner named the tool in `autoApprove`. The cost is a prompt per call for servers the owner hasn't pre-approved, even under Allow All. That is deliberate. Maintenance owned by Mercury:- Any new place that filters tools by name (plan mode, members, bots, sub-agents) must decide how it treats the `mcp__` prefix.- Text from an MCP server (descriptions, results, errors) is untrusted input and must never be used to make a permission decision.- - Resources, prompts, sampling, OAuth, images in results, bot access and the 2026-07-28 protocol (`versionNegotiation: 'auto'`) are follow-ups.+ - Resources, prompts, sampling, OAuth, bot access and the 2026-07-28 protocol (`versionNegotiation: 'auto'`) are follow-ups.- **Follow-up after the #207 review**:- **One approval rule for plugin and MCP tools: trust follows origin.** Allow All, internal-turn grants and a tool's own "read-only" claim apply only to code Mercury vouches for: built-in tools and plugins installed from the catalog with a matching checksum (`verified`). Tools from code the owner brings in from elsewhere (every MCP server, and plugins installed from a path, URL or GitHub) always ask, and skip the prompt only when the owner named them exactly (`tools.autoApprove` for MCP, or a scheduled task's `allow_tools`, which the owner approves when the task is created) or answered **Always** for that tool in that chat. MCP tools and verified plugins already follow this rule; unverified plugins still follow the normal modes until the plugin tool path enforces it.- **Owner prompts can't be answered by a channel's own Allow All.** MCP tool calls, shell commands that change MCP setup, and writes to `mercury.yaml`, `permissions.yaml` and `.env` ask with `alwaysAsk`. The web channel, which serves the terminal attached to the background service, the web dashboard and Mercury Cloud, used to answer every prompt itself in an Allow All session; it now shows these.- **Mercury Cloud: configuration stays local.** Cloud relays chats to the owner's own Mercury (they arrive through `WebChannel`), so Cloud chats can use MCP tools with the same prompts. Cloud has no command to add, enable or change servers, and `${env:}` secrets never leave the local `.env`. Configuring servers from Cloud would let a remote control start local processes, so it needs its own trust design and issue.- - **Shared call wrapper: yes, in stages.** The plugin runtime is also an MCP-over-stdio client, and the two keep separate copies of the same steps, which have drifted. The approval preview shows plugin arguments cut to 400 characters without redaction, and MCP arguments redacted, start and end, up to 4,000. Results are capped at 100,000 characters for plugins and 32 KB for MCP, and plugin results aren't redacted. One module will own the approval preview, timeouts, the result cap, redaction, image handling and error text for both. Image handling moves first; the rest follows once those differences are settled.+ - **Shared call wrapper: yes, in stages.** The plugin runtime is also an MCP-over-stdio client, and the two keep separate copies of the same steps, which have drifted. The approval preview shows plugin arguments cut to 400 characters without redaction, and MCP arguments redacted, start and end, up to 4,000. Results are capped at 100,000 characters for plugins and 32 KB for MCP, and plugin results aren't redacted. One module will own the approval preview, timeouts, the result cap, redaction, image handling and error text for both. Image handling is already shared (`src/capabilities/tool-images.ts`); the rest follows once those differences are settled.diff --git a/src/capabilities/mcp/manager.test.ts b/src/capabilities/mcp/manager.test.tsindex b06f0bde..cafdac32 100644--- a/src/capabilities/mcp/manager.test.ts+++ b/src/capabilities/mcp/manager.test.ts@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';import type { Tool } from 'ai';import { McpManager, probeMcpServer, type McpManagerOptions } from './manager.js';import type { McpGate, McpServerConfig } from './types.js';+import { setToolImagesAllowed } from '../tool-images.js';const FIXTURE = fileURLToPath(new URL('./fixtures/mcp-fixture-server.mjs', import.meta.url));const allowAll: McpGate = async () => ({ allowed: true });@@ -81,6 +82,29 @@ describe('McpManager', () => {expect(m.isAutoApproved('mcp__fx__echo')).toBe(false);}, 20_000);+ it('passes MCP images to the model but keeps base64 out of the result text', async () => {+ const m = manager({ fx: fixture({ tools: { allow: ['image'] } }) });+ await m.connectAll();+ const tool = m.getTools().mcp__fx__image;+ const text = await run(tool, {});+ expect(text).toBe('a pixel\n[1 image attached]');++ const shown = await tool!.toModelOutput!({ toolCallId: 'call-1', input: {}, output: text });+ expect(shown).toMatchObject({+ type: 'content',+ value: [{ type: 'text', text }, { type: 'image-data', mediaType: 'image/png' }],+ });++ setToolImagesAllowed(false);+ try {+ const noted = await tool!.toModelOutput!({ toolCallId: 'call-1', input: {}, output: text });+ expect(noted).toMatchObject({ type: 'text' });+ expect(JSON.stringify(noted)).toMatch(/can't view images/);+ } finally {+ setToolImagesAllowed(true);+ }+ }, 20_000);+it('returns an error string when the gate throws', async () => {const m = manager({ fx: fixture({ tools: { allow: ['echo'] } }) },diff --git a/src/capabilities/mcp/result.test.ts b/src/capabilities/mcp/result.test.tsindex 2dcc2086..8e194842 100644--- a/src/capabilities/mcp/result.test.ts+++ b/src/capabilities/mcp/result.test.ts@@ -1,6 +1,6 @@import { describe, expect, it } from 'vitest';import { registerSecretValue } from '../../utils/redact.js';-import { callResultToText, MAX_RESULT_CHARS } from './result.js';+import { callResultToContent, callResultToText, MAX_RESULT_CHARS } from './result.js';describe('callResultToText', () => {it('joins text blocks', () => {@@ -59,3 +59,46 @@ describe('callResultToText', () => {expect(callResultToText({ content: [{ type: 'text', text: `value=${secret}` }] })).toBe('value=****');});});++describe('callResultToContent', () => {+ const png = { type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' };++ it('returns supported images separately and notes them in the text', () => {+ const content = callResultToContent({ content: [{ type: 'text', text: 'a pixel' }, png] });+ expect(content.images).toEqual([{ data: png.data, mimeType: 'image/png' }]);+ expect(content.text).toBe('a pixel\n[1 image attached]');+ });++ it('keeps a placeholder for media it cannot pass on', () => {+ const content = callResultToContent({+ content: [+ { type: 'image', data: 'AAAA', mimeType: 'image/tiff' },+ { type: 'audio', data: 'AAAA', mimeType: 'audio/wav' },+ ],+ });+ expect(content.images).toEqual([]);+ expect(content.text).toBe('[image/tiff, 3 B — not shown]\n[audio/wav, 3 B — not shown]');+ });++ it('passes at most four images and keeps a placeholder for the rest', () => {+ const content = callResultToContent({ content: Array.from({ length: 6 }, () => ({ ...png })) });+ expect(content.images).toHaveLength(4);+ expect(content.text.split('\n').filter((line) => line.endsWith('— not shown]'))).toHaveLength(2);+ expect(content.text.endsWith('[4 images attached]')).toBe(true);+ });++ it('notes an image-only result without an empty line', () => {+ expect(callResultToContent({ content: [png] }).text).toBe('[1 image attached]');+ });++ it('passes no images with an error result', () => {+ const content = callResultToContent({ content: [{ type: 'text', text: 'boom' }, png], isError: true });+ expect(content.images).toEqual([]);+ expect(content.text).toBe('Error: boom\n[image/png, 8 B — not shown]');+ });++ it('never puts base64 in the text', () => {+ const content = callResultToContent({ content: [{ type: 'text', text: 'shot' }, png] });+ expect(content.text).not.toContain(png.data);+ });+});diff --git a/src/capabilities/mcp/result.ts b/src/capabilities/mcp/result.tsindex 5a022a80..f5bfefbb 100644--- a/src/capabilities/mcp/result.ts+++ b/src/capabilities/mcp/result.ts@@ -1,4 +1,5 @@import { redactSecrets } from '../../utils/redact.js';+import { attachedImagesNote, usableImages, type ToolImage } from '../tool-images.js';export const MAX_RESULT_CHARS = 32 * 1024;@@ -55,15 +56,45 @@ function truncate(text: string): string {return `${text.slice(0, MAX_RESULT_CHARS)}\n… (truncated, ${omitted} chars omitted)`;}-export function callResultToText(result: McpCallResultLike): string {+export interface McpResultContent {+ text: string;+ images: ToolImage[];+}++function convert(result: McpCallResultLike, withImages: boolean): McpResultContent {const blocks = Array.isArray(result.content) ? (result.content as ContentBlock[]) : [];- let text = blocks.map(blockToText).filter((part) => part.length > 0).join('\n');+ const imageOf = new Map<ContentBlock, ToolImage>();+ if (withImages && !result.isError) {+ for (const block of blocks) {+ if (block.type === 'image' && typeof block.data === 'string' && typeof block.mimeType === 'string') {+ imageOf.set(block, { data: block.data, mimeType: block.mimeType });+ }+ }+ }+ const images = usableImages([...imageOf.values()]);+ const kept = new Set(images);+ let text = blocks+ .map((block) => {+ const image = imageOf.get(block);+ return image && kept.has(image) ? '' : blockToText(block);+ })+ .filter((part) => part.length > 0)+ .join('\n');if (!text && result.structuredContent !== undefined) {text = JSON.stringify(result.structuredContent, null, 2) ?? '';}- if (!text) {+ if (!text && !images.length) {text = result.isError ? 'the server reported an error without details' : '(no content)';}if (result.isError) text = `Error: ${text}`;- return truncate(redactSecrets(text));+ const note = attachedImagesNote(images.length);+ return { text: text ? `${truncate(redactSecrets(text))}${note}` : note.trimStart(), images };+}++export function callResultToText(result: McpCallResultLike): string {+ return convert(result, false).text;+}++export function callResultToContent(result: McpCallResultLike): McpResultContent {+ return convert(result, true);}diff --git a/src/capabilities/mcp/tool.ts b/src/capabilities/mcp/tool.tsindex f0222537..12b4c779 100644--- a/src/capabilities/mcp/tool.ts+++ b/src/capabilities/mcp/tool.ts@@ -1,6 +1,7 @@import { tool, type Schema, type Tool } from 'ai';import { redactSecrets } from '../../utils/redact.js';-import { callResultToText, type McpCallResultLike } from './result.js';+import { holdImages, toolOutputWithImages } from '../tool-images.js';+import { callResultToContent, type McpCallResultLike } from './result.js';import type { McpGate } from './types.js';export const MAX_DESCRIPTION_CHARS = 1024;@@ -36,7 +37,8 @@ export function buildMcpTool(options: BuildMcpToolOptions): Tool {return tool({description: describeMcpTool(serverId, options.description),inputSchema: options.inputSchema,- execute: async (args: Record<string, unknown>, { abortSignal }): Promise<string> => {+ toModelOutput: ({ toolCallId, output }) => toolOutputWithImages(toolCallId, String(output)),+ execute: async (args: Record<string, unknown>, { abortSignal, toolCallId }): Promise<string> => {let verdict;try {verdict = await gate({ serverId, toolName, exposedName, args, autoApprove });@@ -47,7 +49,9 @@ export function buildMcpTool(options: BuildMcpToolOptions): Tool {return `Error: ${verdict.reason ?? `MCP ${serverId}/${toolName} is not permitted`}`;}try {- return callResultToText(await call(toolName, args ?? {}, abortSignal));+ const content = callResultToContent(await call(toolName, args ?? {}, abortSignal));+ holdImages(toolCallId, content.images);+ return content.text;} catch (err) {return `Error: MCP ${serverId}/${toolName} failed: ${redactSecrets(errorMessage(err))}`;}diff --git a/src/capabilities/tool-images.test.ts b/src/capabilities/tool-images.test.tsnew file mode 100644index 00000000..7edfe14f--- /dev/null+++ b/src/capabilities/tool-images.test.ts@@ -0,0 +1,57 @@+import { afterEach, describe, expect, it } from 'vitest';+import {+ MAX_TOOL_IMAGES,+ holdImages,+ resetToolImages,+ setToolImagesAllowed,+ toolOutputWithImages,+ usableImages,+} from './tool-images.js';++const png = { data: 'iVBORw0KGgo=', mimeType: 'image/png' };++afterEach(() => {+ resetToolImages();+ setToolImagesAllowed(true);+});++describe('tool images', () => {+ it('keeps supported types, within the size limit, up to the maximum count', () => {+ const images = usableImages([+ { data: 'x', mimeType: 'image/tiff' },+ { data: 'x'.repeat(8_000_001), mimeType: 'image/png' },+ ...Array.from({ length: 6 }, () => ({ ...png })),+ ]);+ expect(images).toHaveLength(MAX_TOOL_IMAGES);+ expect(images.every((image) => image.mimeType === 'image/png' && image.data === png.data)).toBe(true);+ });++ it('sends held images to the model as image parts', () => {+ holdImages('call-1', [png]);+ expect(toolOutputWithImages('call-1', 'shot')).toEqual({+ type: 'content',+ value: [{ type: 'text', text: 'shot' }, { type: 'image-data', data: png.data, mediaType: 'image/png' }],+ });+ });++ it('sends a note instead when the model cannot take images', () => {+ holdImages('call-1', [png]);+ setToolImagesAllowed(false);+ const output = toolOutputWithImages('call-1', 'shot');+ expect(output.type).toBe('text');+ expect(output.value).toMatch(/^shot\n\(The current model can't view images/);+ });++ it('returns plain text when nothing was held for the call', () => {+ holdImages(undefined, [png]);+ holdImages('call-2', []);+ expect(toolOutputWithImages('call-1', 'plain')).toEqual({ type: 'text', value: 'plain' });+ expect(toolOutputWithImages('call-2', 'plain')).toEqual({ type: 'text', value: 'plain' });+ });++ it('holds at most 32 calls, dropping the oldest', () => {+ for (let i = 0; i < 33; i++) holdImages(`call-${i}`, [png]);+ expect(toolOutputWithImages('call-0', 'old').type).toBe('text');+ expect(toolOutputWithImages('call-32', 'new').type).toBe('content');+ });+});diff --git a/src/capabilities/tool-images.ts b/src/capabilities/tool-images.tsnew file mode 100644index 00000000..90816a4c--- /dev/null+++ b/src/capabilities/tool-images.ts@@ -0,0 +1,55 @@+export interface ToolImage {+ data: string;+ mimeType: string;+}++export type ToolImageOutput =+ | { type: 'text'; value: string }+ | {+ type: 'content';+ value: Array<{ type: 'text'; text: string } | { type: 'image-data'; data: string; mediaType: string }>;+ };++export const TOOL_IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']);+export const MAX_TOOL_IMAGES = 4;+export const MAX_TOOL_IMAGE_CHARS = 8_000_000;+const MAX_PENDING = 32;++const pendingImages = new Map<string, ToolImage[]>();+let imagesAllowed = true;++export function setToolImagesAllowed(allowed: boolean): void {+ imagesAllowed = allowed;+}++export function usableImages(images: ToolImage[]): ToolImage[] {+ return images+ .filter((image) => TOOL_IMAGE_TYPES.has(image.mimeType) && image.data.length <= MAX_TOOL_IMAGE_CHARS)+ .slice(0, MAX_TOOL_IMAGES);+}++export function holdImages(toolCallId: string | undefined, images: ToolImage[]): void {+ if (!toolCallId || !images.length) return;+ pendingImages.set(toolCallId, images);+ while (pendingImages.size > MAX_PENDING) pendingImages.delete(pendingImages.keys().next().value as string);+}++export function attachedImagesNote(count: number): string {+ return count ? `\n[${count} image${count > 1 ? 's' : ''} attached]` : '';+}++export function toolOutputWithImages(toolCallId: string, text: string): ToolImageOutput {+ const images = pendingImages.get(toolCallId);+ if (!images?.length) return { type: 'text', value: text };+ if (!imagesAllowed) {+ return { type: 'text', value: `${text}\n(The current model can't view images, so the attached image was left out. Say so if it matters.)` };+ }+ return {+ type: 'content',+ value: [{ type: 'text', text }, ...images.map((image) => ({ type: 'image-data' as const, data: image.data, mediaType: image.mimeType }))],+ };+}++export function resetToolImages(): void {+ pendingImages.clear();+}diff --git a/src/plugins/tool-bridge.ts b/src/plugins/tool-bridge.tsindex aefdf265..1e011abc 100644--- a/src/plugins/tool-bridge.ts+++ b/src/plugins/tool-bridge.ts@@ -13,6 +13,16 @@import { jsonSchema, tool, type Tool } from 'ai';import { isMcpToolName } from '../capabilities/mcp/naming.js';import type { PermissionManager } from '../capabilities/permissions.js';+import {+ TOOL_IMAGE_TYPES,+ attachedImagesNote,+ holdImages,+ resetToolImages,+ setToolImagesAllowed,+ toolOutputWithImages,+ usableImages,+ type ToolImage,+} from '../capabilities/tool-images.js';import { logger } from '../utils/logger.js';export interface LiveTool {@@ -37,16 +47,9 @@ export interface PluginCommandHandler {const MAX_RESULT_CHARS = 100_000;-/** Image types a plugin tool may return (plugin API 1.2), e.g. screenshots. */-export const PLUGIN_IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']);-/** Images per result, and base64 characters per image (~6 MB decoded). */-const MAX_IMAGES = 4;-const MAX_IMAGE_CHARS = 8_000_000;+export const PLUGIN_IMAGE_TYPES = TOOL_IMAGE_TYPES;-export interface PluginImage {- data: string;- mimeType: string;-}+export type PluginImage = ToolImage;const CONTENT = Symbol('mercury.pluginToolContent');@@ -65,24 +68,8 @@ function isToolContent(v: unknown): v is PluginToolContent {return !!v && typeof v === 'object' && (v as Record<symbol, unknown>)[CONTENT] === true;}-/**- * Images waiting to be attached to their tool result, by tool call id.- * execute() returns text only (so logs, history and learning never carry- * base64); toModelOutput() adds the images when the result goes to the model.- * Bounded: a result the SDK never converts can't leak memory.- */-const pendingImages = new Map<string, PluginImage[]>();-/** Whether the model in use can take images (set by the agent before each provider call). */-let imagesAllowed = true;-export function setPluginImagesAllowed(allowed: boolean): void {- imagesAllowed = allowed;-}-const MAX_PENDING = 32;--function holdImages(callId: string, images: PluginImage[]): void {- pendingImages.set(callId, images);- while (pendingImages.size > MAX_PENDING) pendingImages.delete(pendingImages.keys().next().value as string);+ setToolImagesAllowed(allowed);}const TOOL_NAME_RE = /^([a-z][a-z0-9-]{1,30}[a-z0-9])__([a-z][a-z0-9_]{0,29})$/;@@ -180,16 +167,8 @@ function wrap(t: LiveTool, permissions: PermissionManager): Tool {return tool<Record<string, unknown>, string>({description: `[Plugin: ${t.pluginName}] ${t.description}`,inputSchema: jsonSchema<Record<string, unknown>>(t.inputSchema as Parameters<typeof jsonSchema>[0]),- toModelOutput: ({ toolCallId, output }) => {- const text = typeof output === 'string' ? output : stringifyResult(output);- const images = pendingImages.get(toolCallId);- if (!images?.length) return { type: 'text', value: text };- if (!imagesAllowed) return { type: 'text', value: `${text}\n(The current model can't view images, so the attached image was left out. Say so if it matters.)` };- return {- type: 'content',- value: [{ type: 'text', text }, ...images.map((i) => ({ type: 'image-data' as const, data: i.data, mediaType: i.mimeType }))],- };- },+ toModelOutput: ({ toolCallId, output }) =>+ toolOutputWithImages(toolCallId, typeof output === 'string' ? output : stringifyResult(output)),execute: async (input, options) => {const args = (input && typeof input === 'object' ? input : {}) as Record<string, unknown>;if (!t.readOnly) {@@ -212,10 +191,9 @@ function wrap(t: LiveTool, permissions: PermissionManager): Tool {const result = await Promise.race([Promise.resolve().then(() => t.invoke(args, ac.signal)), timeout]);outcomeSink(t.pluginId, { ok: true });if (isToolContent(result)) {- const images = result.images.filter((i) => PLUGIN_IMAGE_TYPES.has(i.mimeType) && i.data.length <= MAX_IMAGE_CHARS).slice(0, MAX_IMAGES);- if (images.length && options?.toolCallId) holdImages(options.toolCallId, images);- const note = images.length ? `\n[${images.length} image${images.length > 1 ? 's' : ''} attached]` : '';- return stringifyResult(`${result.text || 'Done.'}${note}`);+ const images = usableImages(result.images);+ holdImages(options?.toolCallId, images);+ return stringifyResult(`${result.text || 'Done.'}${attachedImagesNote(images.length)}`);}return stringifyResult(result);} catch (err) {@@ -247,7 +225,7 @@ export function getPluginTools(permissions: PermissionManager, opts: { readOnlyO/** Test hook. */export function resetToolBridge(): void {- pendingImages.clear();+ resetToolImages();liveTools.clear();liveCommands.clear();outcomeSink = () => {};diff --git a/website/docs/integrations/mcp.mdx b/website/docs/integrations/mcp.mdxindex adfdfc6e..d85faa76 100644--- a/website/docs/integrations/mcp.mdx+++ b/website/docs/integrations/mcp.mdx@@ -148,7 +148,7 @@ An invalid server entry is skipped with a warning in the log and in `mercury doc- **Tool changes.** If a server announces that its tool list changed (`tools/list_changed`), Mercury refreshes it. New tools are hidden unless your `allow` list covers them, and run without asking only if their exact name is in `autoApprove`.- **Tool names.** Tools are exposed as `mcp__<server>__<tool>`. Characters outside `A-Z a-z 0-9 _ -` become `_`, and names are capped at 64 characters (some model providers reject longer names); a shortened or clashing name gets a short hash suffix. `mercury mcp test` shows the exact names.- **Unusable tools.** A tool whose input schema can't be passed to the model (not an object, larger than 16 KB, or referencing a remote `$ref`) is skipped and reported with the reason. Descriptions inside a schema are shortened to 300 characters, since the model reads them on every turn.-- **Results.** Text is passed to the model, capped at 32 KB per call. Images and audio are replaced by a short placeholder such as `[image/png, 12.3 KB — not shown]`. An error result from the server reaches the agent as `Error: …`.+- **Results.** Text is passed to the model, capped at 32 KB per call. Up to 4 images per call (PNG, JPEG, WebP or GIF, about 6 MB each) reach the model as pictures when the model and its provider can take images in tool results (today Anthropic, and OpenAI's Responses API); elsewhere the model gets a note that an image was left out. Other media, and images beyond those limits, are replaced by a short placeholder such as `[image/png, 12.3 KB — not shown]`. Chat history and logs keep only the text. An error result from the server reaches the agent as `Error: …`.## Permissions