Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
index 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.ts
index 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.ts
index 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 = {}): McpServer
options.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<CallToolRes
const 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 {