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
feat(mcp): annotate tools and expose structured output (#422)
Alot1zcffd7b5da294
diff --git a/docs/mcp-plugin-consolidation.md b/docs/mcp-plugin-consolidation.mdindex 8b7e410e..b73fcc37 100644--- a/docs/mcp-plugin-consolidation.md+++ b/docs/mcp-plugin-consolidation.md@@ -53,6 +53,47 @@ install even though every call answered "requires Ix Pro".**Net:** codex and cursor can delegate with no change in what an agent can do.gemini, openclaw and opencode lose only `ix_query` and the two composites.+## Structured results and tool annotations++`ix mcp` exposes two protocol conveniences on top of the tool surface:++- **Tool annotations.** Every advertised tool carries a `title`, and every tool+ implemented in this repository also carries `readOnlyHint`, `destructiveHint`,+ `idempotentHint` and `openWorldHint` so a client can present and route it+ correctly. Graph reads are read-only and idempotent; `ix_map` and `ix_ingest`+ are destructive because they mutate backend state; only `ix_ingest` is+ open-world, because its GitHub form reaches an external API.++ The Pro tools — `ix_briefing`, `ix_decisions`, `ix_decide` — carry a title and+ no behavioral hint, for the same reason they carry no `outputSchema`: they are+ implemented in the separate `@ix/pro` package, so nothing here can check a+ claim about them. That asymmetry is deliberate rather than an oversight.+ Clients use `readOnlyHint` to decide whether a call needs the user's approval,+ so a wrong one does not merely mislabel a tool — it removes the prompt in+ front of it. An absent hint costs a confirmation; a wrong one costs the+ confirmation itself.++ Hints describe intent and are not themselves a boundary: the enforcement that+ matters (argv construction, timeouts, output bounds, process cleanup) lives in+ the runner, and what a tool can reach is bounded by the command it runs, not by+ what it is advertised as.++- **Structured content.** `ix_map`, `ix_ingest` and `ix_smells` return their+ parsed JSON object as `structuredContent` (with an `outputSchema`) so agents+ receive typed values instead of a string to re-parse. The schema asserts only+ "an object": the real field shape is backend-defined and versioned, and+ promising specific fields would break tool calls the moment the backend+ renames one. The human-readable text result is preserved for clients that+ prefer it. Most remaining tools return their `llm`-format text, which has no+ stable object shape worth promising.++ The Pro tools are the exception worth naming: they run in JSON too, but get+ neither an `outputSchema` nor `structuredContent`, because their shape cannot+ be checked from this package. Those two go together on purpose — attaching the+ parsed object without the schema would hand clients the unverified value+ anyway, minus the contract that would let them validate it. Their answer is+ still returned, as text.+## Order of work1. **Ship `ix mcp` in a released `@ix/cli`.** Nothing downstream can depend on itdiff --git a/ix-cli/src/cli/__tests__/mcp-annotations.test.ts b/ix-cli/src/cli/__tests__/mcp-annotations.test.tsnew file mode 100644index 00000000..ddf9cc32--- /dev/null+++ b/ix-cli/src/cli/__tests__/mcp-annotations.test.ts@@ -0,0 +1,116 @@+import { Client } from "@modelcontextprotocol/sdk/client/index.js";+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";+import { afterEach, describe, expect, it } from "vitest";++import {+ createIxMcpServer,+ IX_MCP_TOOL_NAMES,+ type IxRunner,+} from "../../mcp/server.js";++const clients: Client[] = [];++afterEach(async () => {+ await Promise.all(clients.splice(0).map((client) => client.close()));+});++async function connect(runIx: IxRunner, proAvailable = false): Promise<Client> {+ const server = createIxMcpServer({ version: "test", runIx, proAvailable });+ const client = new Client({ name: "ix-mcp-annotations-test", version: "1.0.0" });+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();++ await server.connect(serverTransport);+ await client.connect(clientTransport);+ clients.push(client);+ return client;+}++describe("ix mcp tool annotations", () => {+ it("classifies every catalogued tool", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);+ const tools = await client.listTools();++ // The annotation table is keyed by the catalog, so a tool added without a+ // classification is a type error upstream of this test. This guard keeps+ // the runtime behavior honest regardless of how the table evolves.+ for (const name of IX_MCP_TOOL_NAMES) {+ const tool = tools.tools.find((entry) => entry.name === name);+ expect(tool, `tool ${name} not advertised`).toBeDefined();+ expect(tool?.annotations, `tool ${name} has no annotations`).toBeDefined();+ }+ });++ it("marks mutating tools destructive, non-idempotent, and non-read-only", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);+ const byName = new Map((await client.listTools()).tools.map((entry) => [entry.name, entry]));++ // ix_decide is deliberately absent: it lives in @ix/pro, so its behavior+ // cannot be verified from here. See the Pro-tool case below.+ for (const name of ["ix_map", "ix_ingest"]) {+ expect(byName.get(name)?.annotations?.destructiveHint, name).toBe(true);+ expect(byName.get(name)?.annotations?.readOnlyHint, name).toBe(false);+ expect(byName.get(name)?.annotations?.idempotentHint, name).toBe(false);+ }+ });++ it("asserts no behavioral hint for tools implemented outside this repository", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);+ const byName = new Map((await client.listTools()).tools.map((entry) => [entry.name, entry]));++ // Clients use readOnlyHint to decide whether a call needs the user's+ // approval. Claiming it for @ix/pro's code — which this package cannot see —+ // would trade a confirmation prompt for an unverified claim. A title is the+ // most these can honestly carry.+ for (const name of ["ix_briefing", "ix_decisions", "ix_decide"]) {+ const annotations = byName.get(name)?.annotations;+ expect(annotations?.title, name).toBeTruthy();+ expect(annotations?.readOnlyHint, name).toBeUndefined();+ expect(annotations?.destructiveHint, name).toBeUndefined();+ expect(annotations?.idempotentHint, name).toBeUndefined();+ expect(annotations?.openWorldHint, name).toBeUndefined();+ }+ });++ it("does not call ix_read graph-bounded, because it is not", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }));+ const byName = new Map((await client.listTools()).tools.map((entry) => [entry.name, entry]));++ // `ix read` resolves an exact file path before consulting the graph, so a+ // title promising a graph bound describes only part of the command.+ expect(byName.get("ix_read")?.annotations?.title).not.toMatch(/graph-bounded/i);+ });++ it("marks graph reads read-only and idempotent", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);+ const byName = new Map((await client.listTools()).tools.map((entry) => [entry.name, entry]));++ for (const name of ["ix_health", "ix_locate", "ix_text", "ix_read", "ix_history", "ix_stats"]) {+ expect(byName.get(name)?.annotations?.readOnlyHint, name).toBe(true);+ expect(byName.get(name)?.annotations?.idempotentHint, name).toBe(true);+ expect(byName.get(name)?.annotations?.destructiveHint, name).toBe(false);+ }+ });++ it("marks only GitHub ingestion as open-world", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);+ const byName = new Map((await client.listTools()).tools.map((entry) => [entry.name, entry]));++ // ix_ingest is the one tool that reaches outside the host (GitHub API).+ expect(byName.get("ix_ingest")?.annotations?.openWorldHint).toBe(true);+ // Local graph reads and the local map refresh do not.+ expect(byName.get("ix_map")?.annotations?.openWorldHint).toBe(false);+ expect(byName.get("ix_text")?.annotations?.openWorldHint).toBe(false);+ });++ it("advertises a truthful non-empty title for every tool", async () => {+ const client = await connect(async () => ({ ok: true, stdout: "ok", stderr: "" }), true);+ const tools = await client.listTools();+ const byName = new Map(tools.tools.map((entry) => [entry.name, entry]));++ for (const name of IX_MCP_TOOL_NAMES) {+ const title = byName.get(name)?.annotations?.title;+ expect(typeof title, `tool ${name} has no title annotation`).toBe("string");+ expect((title ?? "").length, `tool ${name} title is empty`).toBeGreaterThan(0);+ }+ });+});diff --git a/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts b/ix-cli/src/cli/__tests__/mcp-structured-output.test.tsnew file mode 100644index 00000000..fb4fb998--- /dev/null+++ b/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts@@ -0,0 +1,116 @@+import { Client } from "@modelcontextprotocol/sdk/client/index.js";+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";+import { afterEach, describe, expect, it } from "vitest";++import { createIxMcpServer, type IxRunner } from "../../mcp/server.js";++const clients: Client[] = [];++afterEach(async () => {+ await Promise.all(clients.splice(0).map((client) => client.close()));+});++async function connect(runIx: IxRunner): Promise<Client> {+ const server = createIxMcpServer({ version: "test", runIx });+ const client = new Client({ name: "ix-mcp-structured-test", version: "1.0.0" });+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();++ await server.connect(serverTransport);+ await client.connect(clientTransport);+ clients.push(client);+ return client;+}++describe("ix mcp structured output", () => {+ it("exposes parsed JSON objects as structuredContent", async () => {+ const client = await connect(async () => ({+ ok: true,+ stdout: JSON.stringify({ file_count: 3, outcome: "complete" }),+ stderr: "",+ }));++ const result = (await client.callTool({ name: "ix_map", arguments: {} })) as CallToolResult;++ expect(result.structuredContent).toEqual({ file_count: 3, outcome: "complete" });+ // The human-readable text remains for clients that prefer it.+ expect(result.content[0]?.type).toBe("text");+ });++ it("falls back to an empty object without throwing when output is not JSON", async () => {+ const client = await connect(async () => ({+ ok: true,+ stdout: "not json at all",+ stderr: "",+ }));++ const result = (await client.callTool({ name: "ix_map", arguments: {} })) as CallToolResult;++ // A future backend emitting a non-object shape must not fail the tool call;+ // the raw text still carries the answer.+ expect(result.structuredContent).toEqual({});+ expect(result.content[0]).toEqual({ type: "text", text: "not json at all" });+ });++ it("exposes the filtered smell candidates as structuredContent", async () => {+ const client = await connect(async () => ({+ ok: true,+ stdout: JSON.stringify({+ rev: 1,+ run_at: "now",+ count: 2,+ candidates: [+ { file: "ix-cli/src/a.ts", smell: "orphan", confidence: 0.9, signals: ["x"] },+ { file: "src/b.ts", smell: "god_module", confidence: 0.8, signals: ["y"] },+ ],+ }),+ stderr: "",+ }));++ const result = (await client.callTool({ name: "ix_smells", arguments: { limit: 1 } })) as CallToolResult;++ const structured = result.structuredContent as { count: number; candidates: unknown[] };+ expect(structured.count).toBe(1);+ expect(structured.candidates).toHaveLength(1);+ });++ 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"]) {+ 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();+ });++ it("attaches structuredContent only where an outputSchema was declared", async () => {+ // runJson serves the Pro tools too. They are left out of TOOL_OUTPUT_SCHEMA+ // because their shape cannot be checked from this package — so attaching the+ // parsed object to their results anyway would hand clients exactly the data+ // the omission was meant to withhold, minus the contract to validate it.+ const server = createIxMcpServer({+ version: "test",+ proAvailable: true,+ runIx: async () => ({ ok: true, stdout: JSON.stringify({ shape: "unverified" }), stderr: "" }),+ });+ const client = new Client({ name: "ix-mcp-structured-pro-test", version: "1.0.0" });+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ clients.push(client);++ const declared = (await client.callTool({ name: "ix_map", arguments: {} })) as CallToolResult;+ expect(declared.structuredContent).toEqual({ shape: "unverified" });++ for (const name of ["ix_briefing", "ix_decisions"]) {+ const result = (await client.callTool({ name, arguments: {} })) as CallToolResult;+ expect(result.structuredContent, name).toBeUndefined();+ // The answer is still there, as text.+ expect(result.content[0], name).toEqual({ type: "text", text: JSON.stringify({ shape: "unverified" }) });+ }+ });+});diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.tsindex 730fde22..02b872dd 100644--- a/ix-cli/src/mcp/server.ts+++ b/ix-cli/src/mcp/server.ts@@ -1,6 +1,6 @@import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";+import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";import { z } from "zod";import {@@ -61,6 +61,109 @@ export const IX_MCP_PRO_TOOL_NAMES = ["ix_briefing", "ix_decisions", "ix_decide"/** Every tool this server can serve, across both tiers. */export const IX_MCP_TOOL_NAMES = [...IX_MCP_OSS_TOOL_NAMES, ...IX_MCP_PRO_TOOL_NAMES] as const;+/**+ * Semantic annotations for the tool catalog.+ *+ * These are advisory hints for MCP clients: they describe each tool's intent so+ * a client can present and route it sensibly. They are NOT security controls —+ * the hardening that actually matters (argv construction, timeouts, output+ * bounds, process cleanup) lives in the runner and is unchanged. The table is+ * keyed by {@link IX_MCP_TOOL_NAMES}, so the typechecker rejects any tool+ * added to the catalog without a truthful classification.+ */+const READ_ONLY: ToolAnnotations = {+ readOnlyHint: true,+ destructiveHint: false,+ idempotentHint: true,+ openWorldHint: false,+};++/** Mutates backend state, so it is neither read-only nor idempotent. */+const WRITE: ToolAnnotations = {+ readOnlyHint: false,+ destructiveHint: true,+ idempotentHint: false,+ openWorldHint: false,+};++/** Mutates backend state and reaches outside the host (GitHub): open-world. */+const WRITE_OPEN_WORLD: ToolAnnotations = {+ readOnlyHint: false,+ destructiveHint: true,+ idempotentHint: false,+ openWorldHint: true,+};++/**+ * A title and nothing else — for tools whose behavior cannot be verified from+ * this repository.+ *+ * The Pro tools are implemented in the separate `@ix/pro` package, which is why+ * they are also left out of TOOL_OUTPUT_SCHEMA below. The same reasoning applies+ * with more force to the behavioral hints: clients use `readOnlyHint` to decide+ * whether a call needs the user's approval, so asserting it for code that is not+ * in this tree would trade away a confirmation prompt on an unverified claim. An+ * absent hint costs a prompt; a wrong one costs the prompt itself.+ */+const UNVERIFIED = (title: string): ToolAnnotations => ({ title });++const TOOL_ANNOTATIONS: Record<(typeof IX_MCP_TOOL_NAMES)[number], ToolAnnotations> = {+ ix_health: { ...READ_ONLY, title: "Check Ix backend and graph readiness" },+ ix_locate: { ...READ_ONLY, title: "Resolve a symbol to its canonical target" },+ ix_text: { ...READ_ONLY, title: "Search text across the indexed repository" },+ ix_impact: { ...READ_ONLY, title: "Analyze the blast radius of changing a symbol" },+ ix_map: { ...WRITE, title: "Ingest or refresh the workspace architecture map" },+ ix_overview: { ...READ_ONLY, title: "Show the structural overview of a target" },+ // Not "graph-bounded": `ix read` resolves an exact file path before it+ // consults the graph at all, so the title has to describe the whole command.+ ix_read: { ...READ_ONLY, title: "Read source from the workspace" },+ ix_diff: { ...READ_ONLY, title: "Show the structural diff between revisions" },+ ix_callers: { ...READ_ONLY, title: "List incoming call edges" },+ ix_callees: { ...READ_ONLY, title: "List outgoing call edges" },+ ix_imported_by: { ...READ_ONLY, title: "List incoming import edges" },+ ix_imports: { ...READ_ONLY, title: "List outgoing import edges" },+ ix_depends: { ...READ_ONLY, title: "Show downstream dependencies" },+ ix_trace: { ...READ_ONLY, title: "Trace execution paths through a symbol" },+ ix_explain: { ...READ_ONLY, title: "Explain a symbol using graph evidence" },+ ix_rank: { ...READ_ONLY, title: "Rank graph entities by importance" },+ ix_inventory: { ...READ_ONLY, title: "List graph entities by kind" },+ ix_smells: { ...READ_ONLY, title: "Detect graph-backed architecture smells" },+ ix_stats: { ...READ_ONLY, title: "Return graph-wide statistics" },+ ix_subsystems: { ...READ_ONLY, title: "List graph-derived subsystems" },+ ix_history: { ...READ_ONLY, title: "Show provenance and patch history" },+ ix_ingest: { ...WRITE_OPEN_WORLD, title: "Ingest a path or GitHub repository into the graph" },+ // Implemented in @ix/pro, so nothing here can check these are true.+ ix_briefing: UNVERIFIED("Load the Ix Pro session briefing"),+ ix_decisions: UNVERIFIED("List Ix Pro architecture decisions"),+ ix_decide: UNVERIFIED("Record an architecture decision"),+};++/**+ * The output schema for tools that return a stable JSON object whose field+ * shape is backend- and version-defined.+ *+ * `z.object({}).passthrough()` accepts any object without promising specific+ * fields, so a backend addition or rename cannot turn a formatting surprise+ * into a failed tool call. It is deliberately not `z.record(...)`: the MCP SDK+ * only recognizes object schemas as output schemas, and a record schema is+ * silently dropped from tools/list.+ */+const JSON_OBJECT_SCHEMA = z.object({}).passthrough();++/**+ * Tools whose `--format=json` output is a stable object, exposed as MCP+ * structured content.+ *+ * The Pro tools are omitted because their command implementations live in the+ * separate `@ix/pro` package, so their output shape cannot be verified from+ * this repository.+ */+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,+};+interface CreateServerOptions {version?: string;runIx?: IxRunner;@@ -371,8 +474,15 @@ function registerTool(inputSchema: z.ZodRawShape,handler: (input: ToolInput) => Promise<CallToolResult>,): void {- server.registerTool(name, { description, inputSchema }, async (input) =>- handler(input as ToolInput),+ server.registerTool(+ name,+ {+ description,+ inputSchema,+ annotations: TOOL_ANNOTATIONS[name as keyof typeof TOOL_ANNOTATIONS],+ outputSchema: TOOL_OUTPUT_SCHEMA[name as keyof typeof TOOL_OUTPUT_SCHEMA],+ },+ async (input) => handler(input as ToolInput),);}@@ -403,7 +513,17 @@ async function runJson(argv: IxArgv,timeoutMs = DEFAULT_TIMEOUT_MS,): Promise<CallToolResult> {- return runCommand(runIx, tool, toArgv(argv, "json"), timeoutMs);+ const result = await runCommand(runIx, tool, toArgv(argv, "json"), timeoutMs);+ // Only for tools that declared an outputSchema. runJson also serves the three+ // Pro tools, whose shape cannot be checked from this package — which is the+ // stated reason they have no schema. Attaching structuredContent to them+ // anyway would hand clients the unverified object regardless, just without the+ // contract that would let them validate it.+ return declaresOutputSchema(tool) ? withStructuredContent(result) : result;+}++function declaresOutputSchema(tool: string): boolean {+ return tool in TOOL_OUTPUT_SCHEMA;}async function runCommand(@@ -424,6 +544,23 @@ async function runCommand(return textResult(result.stdout.trim() || "{}");}+/**+ * Expose the parsed JSON object as structuredContent so clients receive a typed+ * value instead of a string to re-parse.+ *+ * Falls back to `{}` — never throws — when the output is not a JSON object; the+ * human-readable text content is always preserved. The fallback keeps tools+ * with an outputSchema valid even if a future backend returns an unexpected+ * shape, rather than turning a formatting surprise into a failed tool call.+ */+function withStructuredContent(result: CallToolResult): CallToolResult {+ if (result.isError) return result;+ const first = result.content?.[0];+ const text = first?.type === "text" ? first.text : "";+ const parsed = parseJsonOutput(text);+ return { ...result, structuredContent: isRecord(parsed) ? parsed : {} };+}+async function runSmells(runIx: IxRunner, input: ToolInput): Promise<CallToolResult> {const result = await runIx(toArgv(ix("smells"), "json"), DEFAULT_TIMEOUT_MS);if (!result.ok) {@@ -433,7 +570,7 @@ async function runSmells(runIx: IxRunner, input: ToolInput): Promise<CallToolResconst parsed = parseJsonOutput(result.stdout);if (!isRecord(parsed) || !Array.isArray(parsed.candidates)) {- return textResult(result.stdout.trim() || "{}");+ return withStructuredContent(textResult(result.stdout.trim() || "{}"));}const path = typeof input.path === "string" ? normalizePath(input.path) : null;@@ -452,7 +589,11 @@ async function runSmells(runIx: IxRunner, input: ToolInput): Promise<CallToolRes}).slice(0, limit);- return textResult(JSON.stringify({ ...parsed, count: candidates.length, candidates }, null, 2));+ const payload = { ...parsed, count: candidates.length, candidates };+ return {+ content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],+ structuredContent: payload,+ };}function textResult(text: string, isError = false): CallToolResult {