Skip to content

armgit / Ix

Public Imported from GitHub
0

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

feat(mcp): annotate tools and expose structured output (#422)

Alot1zcffd7b5da294
diff --git a/docs/mcp-plugin-consolidation.md b/docs/mcp-plugin-consolidation.md
index 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 work
1. **Ship `ix mcp` in a released `@ix/cli`.** Nothing downstream can depend on it
diff --git a/ix-cli/src/cli/__tests__/mcp-annotations.test.ts b/ix-cli/src/cli/__tests__/mcp-annotations.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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<CallToolRes
const 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 {