Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
perf(mcp): send the context bundle once, in the format its reader uses
KageBinarya33d68c29564
diff --git a/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts b/ix-cli/src/cli/__tests__/mcp-structured-output.test.tsindex 5580cfa7..7643e72b 100644--- a/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts+++ b/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts@@ -126,24 +126,50 @@ describe("ix mcp structured output", () => {stderr: "",}));- const result = (await client.callTool({ name: "ix_smells", arguments: { limit: 1 } })) as CallToolResult;+ const asked = (await client.callTool({+ name: "ix_smells",+ arguments: { limit: 1, structured: true },+ })) as CallToolResult;- const structured = result.structuredContent as { count: number; candidates: unknown[] };+ const structured = asked.structuredContent as { count: number; candidates: unknown[] };expect(structured.count).toBe(1);expect(structured.candidates).toHaveLength(1);++ // And not otherwise: the structured copy is the same bytes as the text.+ const plain = (await client.callTool({ name: "ix_smells", arguments: { limit: 1 } })) as CallToolResult;+ expect(plain.structuredContent).toBeUndefined();+ const text = plain.content?.[0];+ expect(text?.type === "text" && text.text.includes("\n ")).toBe(false);});it("advertises outputSchema only for the verified JSON tools", async () => {const client = await connect(async () => ({ ok: true, stdout: "{}", stderr: "" }));const byName = new Map((await client.listTools()).tools.map((tool) => [tool.name, tool]));- for (const name of ["ix_map", "ix_ingest", "ix_smells"]) {+ for (const name of ["ix_map", "ix_ingest"]) {expect(byName.get(name)?.outputSchema, name).toBeDefined();}// Tools whose `--format llm` output is human-oriented text have no stable// object schema to promise.expect(byName.get("ix_locate")?.outputSchema).toBeUndefined();expect(byName.get("ix_stats")?.outputSchema).toBeUndefined();+ // And neither do the two whose structured copy is opt-in: an outputSchema+ // is a promise that EVERY result carries one.+ expect(byName.get("ix_context")?.outputSchema).toBeUndefined();+ expect(byName.get("ix_smells")?.outputSchema).toBeUndefined();+ });++ it("does not spend a third of tools/list on one tool's output schema", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "{}", stderr: "" }));+ const tools = (await client.listTools()).tools;+ const total = JSON.stringify(tools).length;+ const context = JSON.stringify(tools.find((t) => t.name === "ix_context"))!.length;++ // Measured: the bundle schema was 4,671 of 15,365 bytes — 30% of what+ // every session pays to connect to this server, for a shape only a caller+ // passing `structured: true` receives.+ expect(context).toBeLessThan(1500);+ expect(total).toBeLessThan(12_500);});it("attaches structuredContent only where an outputSchema was declared", async () => {diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.tsindex b611b968..eaf0da4a 100644--- a/ix-cli/src/cli/__tests__/mcp.test.ts+++ b/ix-cli/src/cli/__tests__/mcp.test.ts@@ -200,15 +200,11 @@ describe("ix mcp", () => {expect(result.content).toEqual([{ type: "text", text: output }]);});- it("forwards ix_context target and bounded budgets as the CLI contract", async () => {+ it("asks the CLI for records, and sends the bundle once", async () => {const calls: string[][] = [];const client = await connect(async (args) => {calls.push(args);- // A whole bundle, not `{schema}` alone: ix_context declares an- // outputSchema, and the SDK rejects structuredContent that does not match- // it. Stubbing a partial bundle made this pass on a tool call that had- // actually returned isError with an output-validation failure.- return { ok: true, stdout: JSON.stringify(contextBundle()), stderr: "" };+ return { ok: true, stdout: "context target=Widget entities=2\nevidence score=0 kind=target title=Widget", stderr: "" };});const result = await client.callTool({@@ -218,68 +214,77 @@ describe("ix mcp", () => {expect(result.isError).toBeFalsy();expect(calls).toEqual([- ["context", "--max-entities=20", "--max-evidence=5", "--format=json", "--", "Widget"],+ ["context", "--max-entities=20", "--max-evidence=5", "--format=llm", "--", "Widget"],+ ]);+ // Once. The JSON text plus the same object again as structuredContent was+ // two copies of a bundle that can run to 20 KB.+ expect(result.structuredContent).toBeUndefined();+ expect(result.content).toEqual([+ { type: "text", text: "context target=Widget entities=2\nevidence score=0 kind=target title=Widget" },]);- });-- it("surfaces an output-schema violation instead of passing it off as a result", async () => {- // The guard the test above used to lack: a bundle missing required fields- // must not reach the caller looking like a successful call.- const client = await connect(async () => ({- ok: true,- stdout: JSON.stringify({ schema: "ix-context-bundle/1" }),- stderr: "",- }));-- const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget" } });-- expect(result.isError).toBe(true);});it("forwards ix_context max_chars to the CLI contract", async () => {const calls: string[][] = [];const client = await connect(async (args) => {calls.push(args);- return { ok: true, stdout: JSON.stringify(contextBundle()), stderr: "" };+ return { ok: true, stdout: "context target=Widget", stderr: "" };});const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget", max_evidence: 3, max_chars: 5000 } });expect(result.isError).toBeFalsy();- expect(calls).toEqual([["context", "--max-evidence=3", "--max-chars=5000", "--format=json", "--", "Widget"]]);+ expect(calls).toEqual([["context", "--max-evidence=3", "--max-chars=5000", "--format=llm", "--", "Widget"]]);});- it("returns ix_context structuredContent with the parsed bundle", async () => {+ it("returns the JSON bundle as structuredContent when asked for it", async () => {const bundle = contextBundle();- const client = await connect(async () => ({ ok: true, stdout: JSON.stringify(bundle), stderr: "" }));+ const calls: string[][] = [];+ const client = await connect(async (args) => {+ calls.push(args);+ return { ok: true, stdout: JSON.stringify(bundle), stderr: "" };+ });- const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget" } });+ const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget", structured: true } });+ expect(calls).toEqual([["context", "--format=json", "--", "Widget"]]);expect(result.structuredContent).toEqual(bundle);expect(result.content).toEqual([{ type: "text", text: JSON.stringify(bundle) }]);});- it("marks an unparseable bundle output as an MCP error", async () => {+ it("marks an unparseable bundle as an MCP error, on the structured path", async () => {const client = await connect(async () => ({ ok: true, stdout: "not json at all", stderr: "" }));- const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget" } });+ const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget", structured: true } });expect(result.isError).toBe(true);expect(result.structuredContent).toBeUndefined();expect(result.content).toEqual([{ type: "text", text: "not json at all" }]);});+ it("surfaces a CLI error record from the records path", async () => {+ const client = await connect(async () => ({+ ok: true,+ stdout: 'error code=unresolved_target message="No entity found matching \\"Widget\\"."',+ stderr: "",+ }));++ const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget" } });++ expect(result.isError).toBe(true);+ });+it("omits unset context budgets rather than sending empty flags", async () => {const calls: string[][] = [];const client = await connect(async (args) => {calls.push(args);- return { ok: true, stdout: JSON.stringify(contextBundle()), stderr: "" };+ return { ok: true, stdout: "context target=main.ts", stderr: "" };});const result = await client.callTool({ name: "ix_context", arguments: { target: "src/main.ts" } });expect(result.isError).toBeFalsy();- expect(calls).toEqual([["context", "--format=json", "--", "src/main.ts"]]);+ expect(calls).toEqual([["context", "--format=llm", "--", "src/main.ts"]]);});it("marks Ix command failures as MCP errors", async () => {diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.tsindex a6c3664c..35f07aa3 100644--- a/ix-cli/src/mcp/server.ts+++ b/ix-cli/src/mcp/server.ts@@ -4,7 +4,6 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";import { z } from "zod";-import { contextBundleSchema } from "../cli/context-bundle-schema.js";import {createProtocolStdout,@@ -168,7 +167,12 @@ const JSON_OBJECT_SCHEMA = z.object({}).passthrough();const TOOL_OUTPUT_SCHEMA: Partial<Record<(typeof IX_MCP_TOOL_NAMES)[number], z.ZodTypeAny>> = {ix_map: JSON_OBJECT_SCHEMA,ix_ingest: JSON_OBJECT_SCHEMA,- ix_smells: JSON_OBJECT_SCHEMA,+ // `ix_smells` is not here any more, and neither is `ix_context`'s bundle+ // schema. An outputSchema is a promise that EVERY result carries structured+ // content, so a tool whose structured copy is opt-in cannot declare one.+ // `ix_context`'s was 4,671 of the 15,365 bytes of tools/list — 30% of the+ // always-on cost of connecting to this server, for a shape only a caller+ // passing `structured: true` receives.};interface CreateServerOptions {@@ -384,6 +388,10 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer{path: z.string().min(1).optional(),limit: z.number().int().min(1).max(500).default(50),+ structured: z+ .boolean()+ .optional()+ .describe("also return the payload as structuredContent"),},async (input) => runSmells(runIx, input),);@@ -417,6 +425,10 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer.max(1_000_000).optional().describe("exact serialized-character budget for the evidence list"),+ structured: z+ .boolean()+ .optional()+ .describe("return the JSON bundle as structuredContent instead of llm records"),},async (input) => {const options: string[] = [];@@ -426,9 +438,15 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServeroptions.push(`--max-relationships=${numberArg(input, "max_relationships")}`);if (typeof input.max_evidence === "number") options.push(`--max-evidence=${numberArg(input, "max_evidence")}`);if (typeof input.max_chars === "number") options.push(`--max-chars=${numberArg(input, "max_chars")}`);- return runJsonStructured(runIx, "ix_context", ix("context", [stringArg(input, "target")], options));+ const argv = ix("context", [stringArg(input, "target")], options);+ // Once, in the format the reader is: an agent. The bundle used to go out+ // twice on every call — the JSON text AND the same object again as+ // structuredContent — so a 20 KB bundle cost 40 KB, and the copy a model+ // actually reads is the smaller `llm` one that was not being sent at all.+ return input.structured === true+ ? runJsonStructured(runIx, "ix_context", argv)+ : runFormatted(runIx, "ix_context", argv);},- contextBundleSchema,);registerTool(server,@@ -656,6 +674,7 @@ function withStructuredContent(result: CallToolResult): CallToolResult {}async function runSmells(runIx: IxRunner, input: ToolInput): Promise<CallToolResult> {+ const structured = input.structured === true;const result = await runIx(toArgv(ix("smells"), "json"), DEFAULT_TIMEOUT_MS);if (!result.ok) {const detail = result.stderr.trim() || result.stdout.trim() || "smells failed without output";@@ -664,7 +683,8 @@ async function runSmells(runIx: IxRunner, input: ToolInput): Promise<CallToolResconst parsed = parseJsonOutput(result.stdout);if (!isRecord(parsed) || !Array.isArray(parsed.candidates)) {- return withStructuredContent(textResult(result.stdout.trim() || "{}"));+ const text = textResult(result.stdout.trim() || "{}");+ return structured ? withStructuredContent(text) : text;}const path = typeof input.path === "string" ? normalizePath(input.path) : null;@@ -684,10 +704,11 @@ async function runSmells(runIx: IxRunner, input: ToolInput): Promise<CallToolRes.slice(0, limit);const payload = { ...parsed, count: candidates.length, candidates };- return {- content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],- structuredContent: payload,- };+ // Compact, and the object once rather than twice. The indent was two spaces+ // per level of a list of smell candidates, and the structured copy was the+ // same bytes again.+ const text = textResult(JSON.stringify(payload));+ return structured ? { ...text, structuredContent: payload } : text;}function textResult(text: string, isError = false): CallToolResult {