fix: show readable titles for MCP tool calls (#1674)

ACP clients use the tool-call `title` for display. The adapter used to
copy the raw Claude tool name into that field, so users saw
`mcp__github__create_issue` on tool calls and permission requests.

Send `github: create_issue` as the `title` and keep
`mcp__github__create_issue` as the programmatic `name`. Both ACP v1 and
v2 use the same parser that supplies AIR's structured MCP metadata. It
preserves any `__` inside the tool portion and leaves incomplete MCP
names as they were.

**Verification:** `npm run build` and `npm run check` passed. The
targeted tool-call, permission, and ACP v1/v2 scenario suites passed
(1,586 tests passed, 11 skipped).
This commit is contained in:
Ben Brandt
2026-11-19 22:13:57 +01:00
committed by GitHub
parent eb4c16f10a
commit 80440d8b82
10 changed files with 64 additions and 44 deletions

View File

@@ -344,11 +344,11 @@ For every tool, a client that is not AIR also gets these upstream fields:
| `Skill` | `kind: other`, `title: "Load skill: <name>"`. | `_meta.jetbrains.air.skill`. | none |
| `TodoWrite`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet` | The stream reports them as a standard `plan` with entries. Only a permission request shows them as a tool call. | A plan that repeats the previous plan is not sent. | Every plan goes out. |
| `ReportFindings` | `kind: think`, `title: "Report <n> findings"`. | With `rawInputRendering`, no copy of the findings in `content`. | none |
| MCP tools (`mcp__*`) and other tools | `kind: other`, `title` is the tool name. The result text goes to `content`. | `_meta.is_mcp_tool_call` for MCP, and `_meta.jetbrains.air.mcp = {server, tool}`. | none |
| MCP tools (`mcp__*`) and other tools | `kind: other`, `title` is `server: tool` for a complete MCP name, otherwise the tool name. Result text goes to `content`. | `_meta.is_mcp_tool_call` for MCP, and `_meta.jetbrains.air.mcp = {server, tool}`. | none |
| Context compaction | `compaction_update` when the client declares `session.compaction`. Otherwise a synthetic tool call. | Both forms carry `_meta.jetbrains.air.contextCompaction`. | See [Context compaction](#context-compaction). |
| Background work that is not a subagent | none | With `asyncTasks`, async task updates. | none |
`_meta.jetbrains.air.mcp` comes from the tool name `mcp__<server>__<tool>`, on `tool_call` and on a `tool_call_update` that changes it.
The standard `name` stays `mcp__<server>__<tool>`. AIR also gets those parts in `_meta.jetbrains.air.mcp` on `tool_call` and on a `tool_call_update` that changes it.
`server` is the part up to the next `__`. `tool` is the whole rest and can contain `__`, as in Claude Code.
A name that does not split (`mcp__x`) gets no `mcp` key, and `_meta.is_mcp_tool_call` still marks it.

View File

@@ -1,9 +1,9 @@
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"claudeCode":{"toolName":"mcp__docs__search"},"is_mcp_tool_call":true,"jetbrains":{"air":{"mcp":{"server":"docs","tool":"search"},"version":1}}},"content":[],"kind":"other","name":"mcp__docs__search","sessionUpdate":"tool_call","status":"pending","title":"mcp__docs__search","toolCallId":"toolu_mcp"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"claudeCode":{"toolName":"mcp__docs__search"},"is_mcp_tool_call":true,"jetbrains":{"air":{"mcp":{"server":"docs","tool":"search"},"version":1}}},"content":[],"kind":"other","name":"mcp__docs__search","sessionUpdate":"tool_call","status":"pending","title":"docs: search","toolCallId":"toolu_mcp"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawInput":{"q":"acp"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_mcp"}}}
{"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"title":"mcp__docs__search","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","toolCall":{"_meta":{"claudeCode":{"mcpServer":{"name":"docs","source":"project"}}},"rawInput":{"q":"acp"},"title":"mcp__docs__search","toolCallId":"toolu_mcp"}}}
{"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"title":"docs: search","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","toolCall":{"_meta":{"claudeCode":{"mcpServer":{"name":"docs","source":"project"}}},"rawInput":{"q":"acp"},"title":"docs: search","toolCallId":"toolu_mcp"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"Found 2 documents.","type":"text"},"type":"content"}],"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_mcp"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
{"kind":"promptResponse","payload":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}

View File

@@ -4,11 +4,11 @@
{"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[],"kind":"other","name":"mcp__docs__search","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"mcp__docs__search","toolCallId":"toolu_mcp"}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[],"kind":"other","name":"mcp__docs__search","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"docs: search","toolCallId":"toolu_mcp"}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"rawInput":{"q":"acp"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_mcp"}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"requires_action"}}}
{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"_meta":{"claudeCode":{"mcpServer":{"name":"docs","source":"project"}}},"content":[],"kind":"other","name":"mcp__docs__search","rawInput":{"q":"acp"},"title":"mcp__docs__search","toolCallId":"toolu_mcp"},"type":"tool_call"},"title":"mcp__docs__search"}}
{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"_meta":{"claudeCode":{"mcpServer":{"name":"docs","source":"project"}}},"content":[],"kind":"other","name":"mcp__docs__search","rawInput":{"q":"acp"},"title":"docs: search","toolCallId":"toolu_mcp"},"type":"tool_call"},"title":"docs: search"}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"Found 2 documents.","type":"text"},"type":"content"}],"rawOutput":[{"text":"Found 2 documents.","type":"text"}],"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_mcp"}}}
{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}

View File

@@ -12,6 +12,8 @@
* change since the previous report of the same tool call. An update with
* nothing new is not sent. ACP does not merge `_meta` keys, so every
* `_meta` key that origin/main sent must still be there.
* - An MCP tool call, including one in a permission request, has title
* `server: tool` where origin/main used the programmatic name as its title.
* - A `compaction_update` leaves out a summary whose text is the same as the
* `compaction_summary_chunk` text that went out before it.
* - A subagent message or thought is not sent again in full when the chunks
@@ -176,6 +178,21 @@ function updateOf(record: Recorded): Json | undefined {
return (record.payload as { update: Json }).update;
}
/** Changes only a baseline tool call's title, not its name or raw input. */
function withMcpToolTitle(record: Recorded): Recorded {
if (record.kind !== "sessionUpdate" && record.kind !== "requestPermission") return record;
const payload = record.payload as Json;
const key = record.kind === "requestPermission" ? "toolCall" : "update";
const call = payload[key] as Json | undefined;
if (!call?.toolCallId || typeof call.title !== "string") return record;
const meta = call._meta as { claudeCode?: { toolName?: string } } | undefined;
if (call.title !== (call.name ?? meta?.claudeCode?.toolName)) return record;
const [prefix, server, ...rest] = call.title.split("__");
const tool = rest.join("__");
if (prefix !== "mcp" || !server || !tool) return record;
return { ...record, payload: { ...payload, [key]: { ...call, title: `${server}: ${tool}` } } };
}
/** The key and the text of a subagent message or thought chunk. */
function subagentChunk(update: Json | undefined): { key: string; text: string } | undefined {
if (
@@ -279,6 +296,7 @@ export function compareWithBaseline(baseline: Recorded[], traffic: Recorded[]):
.map((record) =>
withoutSessionCapabilities(withoutAirOnlyKeys(record) as Recorded, ["subagents"]),
)
.map(withMcpToolTitle)
.filter((record) => {
const update = updateOf(record);
return !(update?.sessionUpdate === "session_info_update" && Object.keys(update).length === 1);

View File

@@ -662,7 +662,7 @@ describe("Claude permission options and response mapping", () => {
})._meta,
).toEqual({
jetbrains: {
air: { version: 1, permission: { version: 1, title: "mcp__computer-use__screenshot" } },
air: { version: 1, permission: { version: 1, title: "computer-use: screenshot" } },
},
});
});

View File

@@ -438,7 +438,7 @@ describe("Claude permission ACP v1 presentation", () => {
]);
});
it("reuses the standard title for an unknown tool", () => {
it("reuses the MCP tool title for the permission request", () => {
const presentation = buildClaudePermissionPresentation({
capabilities: airCapabilities(),
toolName: "mcp__demo__deploy",
@@ -447,11 +447,11 @@ describe("Claude permission ACP v1 presentation", () => {
});
expect(presentation.toolCall).toEqual({
toolCallId: "tool-5",
title: "mcp__demo__deploy",
title: "demo: deploy",
rawInput: { target: "staging" },
});
expect(presentation._meta).toEqual({
jetbrains: { air: { version: 1, permission: { version: 1, title: "mcp__demo__deploy" } } },
jetbrains: { air: { version: 1, permission: { version: 1, title: "demo: deploy" } } },
});
});
});

View File

@@ -30161,7 +30161,7 @@ describe("streamEventToAcpNotifications", () => {
name: "mcp__demo__search",
type: "mcp_tool_use" as const,
partialJson: '{"query":"custom MCP query","options":',
title: "mcp__demo__search",
title: "demo: search",
rawInput: { query: "custom MCP query" },
},
])("refines $case before the full JSON object completes", (testCase) => {

View File

@@ -15,7 +15,7 @@ import {
import { foregroundBashTerminal } from "../../v1/background-work.js";
import { ChangedMetaFilter } from "../../v1/tool-calls/changed-meta-filter.js";
import { ToolCallFieldTracker } from "../../tool-calls/field-tracker.js";
import { AcpToolCallRenderer, mcpToolName } from "../../tool-calls/renderer.js";
import { AcpToolCallRenderer } from "../../tool-calls/renderer.js";
import { changedTaskPlanEntries, createTaskHook, type TaskState } from "../../tools.js";
const logger = { log: () => {}, error: () => {} };
@@ -680,22 +680,20 @@ describe("tool call reports outside the tool_use stream", () => {
});
});
describe("mcpToolName", () => {
/** Splits at the first separator after the prefix; the tool keeps any later separator. */
describe("MCP tool names", () => {
it.each([
["mcp__docs__search", { server: "docs", tool: "search" }],
[
"mcp__plugin_documents_docs__doc_export",
{ server: "plugin_documents_docs", tool: "doc_export" },
"mcp__plugin_documents_docs__doc_export__v2",
{ server: "plugin_documents_docs", tool: "doc_export__v2" },
],
["mcp__srv__a__b", { server: "srv", tool: "a__b" }],
])("parses %s", (name, expected) => {
expect(mcpToolName(name)).toEqual(expected);
});
/** Names that are not a complete mcp__server__tool name give no result. */
it.each(["mcp__x", "mcp____tool", "mcp__srv__", "Bash"])("rejects %s", (name) => {
expect(mcpToolName(name)).toBeUndefined();
["mcp__x", undefined],
["mcp____tool", undefined],
["mcp__srv__", undefined],
["custom__tool", undefined],
] as const)("formats only complete MCP names: %s", (name, mcp) => {
const { call } = report(terminalAir, name, {});
expect(call.title).toBe(mcp ? `${mcp.server}: ${mcp.tool}` : name);
expect(call._meta.jetbrains?.air?.mcp).toEqual(mcp);
});
});

View File

@@ -19,7 +19,7 @@ import { ClientCapabilities } from "./client-capabilities.js";
import { resultText, textContent, toAcpContentUpdate, toolResponseMarkers } from "./content.js";
import type { ToolResultContext, ToolResultFacts, ToolUse, ToolUseFacts } from "./facts.js";
import { reporterFor } from "./reporters/index.js";
import { resolveSkillPath } from "./reporters/interaction.js";
import { mcpToolName, resolveSkillPath } from "./reporters/interaction.js";
import { shellDescription } from "./reporters/bash.js";
import { grepPath } from "./reporters/search.js";
@@ -116,7 +116,7 @@ export type ToolUpdateMeta = {
SKILL.md when it could be located on disk. */
skill?: { name: string; path?: string };
/* For MCP tool calls: the normalized server name and the tool name, so
a client need not parse the `mcp__<server>__<tool>` title. */
a client need not parse the `mcp__<server>__<tool>` name. */
mcp?: { server: string; tool: string };
[key: string]: unknown;
};
@@ -836,22 +836,6 @@ export class AcpToolCallRenderer {
}
}
/**
* Splits `mcp__<server>__<tool>` the way Claude Code does: the server is the
* segment up to the next `__`, the tool is the whole rest. `server` is the
* normalized name, not the config key.
*/
export function mcpToolName(name: string): { server: string; tool: string } | undefined {
const prefix = "mcp__";
if (!name.startsWith(prefix)) return undefined;
const rest = name.slice(prefix.length);
const separator = rest.indexOf("__");
if (separator <= 0) return undefined;
const tool = rest.slice(separator + 2);
if (!tool) return undefined;
return { server: rest.slice(0, separator), tool };
}
/** The input with the path of the plan file in place of the plan text. */
function planFileInput(rawInput: unknown, planFilePath: string): Record<string, unknown> {
const input =

View File

@@ -197,7 +197,11 @@ export class GenericReporter implements ToolReporter {
toolUse(input: unknown): ToolUseFacts {
if (this.toolName !== "Other") {
return { title: this.toolName || "Unknown Tool", kind: "other" };
const mcp = mcpToolName(this.toolName);
return {
title: mcp ? `${mcp.server}: ${mcp.tool}` : this.toolName || "Unknown Tool",
kind: "other",
};
}
let json;
try {
@@ -213,6 +217,22 @@ export class GenericReporter implements ToolReporter {
}
}
/**
* Splits `mcp__<server>__<tool>` the way Claude Code does: the server is the
* segment up to the next `__`, the tool is the whole rest. `server` is the
* normalized name, not the config key.
*/
export function mcpToolName(name: string): { server: string; tool: string } | undefined {
const prefix = "mcp__";
if (!name.startsWith(prefix)) return undefined;
const rest = name.slice(prefix.length);
const separator = rest.indexOf("__");
if (separator <= 0) return undefined;
const tool = rest.slice(separator + 2);
if (!tool) return undefined;
return { server: rest.slice(0, separator), tool };
}
/**
* An agent control tool (SendMessage, TaskStop, ListAgents, Monitor). AIR
* shows the result in its own frame and parses the JSON result of SendMessage