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): ten tools instead of twenty-six, and descriptions that say when to use them
KageBinaryca6e9c39b0a3
diff --git a/ix-cli/src/cli/__tests__/mcp-annotations.test.ts b/ix-cli/src/cli/__tests__/mcp-annotations.test.tsindex 76384bca..17f6c62e 100644--- a/ix-cli/src/cli/__tests__/mcp-annotations.test.ts+++ b/ix-cli/src/cli/__tests__/mcp-annotations.test.ts@@ -17,7 +17,9 @@ afterEach(async () => {});async function connect(runIx: IxRunner, proAvailable = false): Promise<Client> {- const server = createIxMcpServer({ version: "test", runIx, proAvailable });+ const server = createIxMcpServer({ version: "test", runIx, proAvailable, tools: "all" });+ // `all`, because these assertions are about the whole catalog. The core+ // default has its own tests in mcp-toolset.test.ts.const client = new Client({ name: "ix-mcp-annotations-test", version: "1.0.0" });const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();diff --git a/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts b/ix-cli/src/cli/__tests__/mcp-structured-output.test.tsindex 7643e72b..6555c06a 100644--- a/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts+++ b/ix-cli/src/cli/__tests__/mcp-structured-output.test.ts@@ -16,7 +16,7 @@ afterEach(async () => {});async function connect(runIx: IxRunner): Promise<Client> {- const server = createIxMcpServer({ version: "test", runIx });+ const server = createIxMcpServer({ version: "test", runIx, tools: "all" });const client = new Client({ name: "ix-mcp-structured-test", version: "1.0.0" });const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();@@ -169,7 +169,10 @@ describe("ix mcp structured output", () => {// 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);+ // Against the full catalog, which is what `connect` builds here. What a+ // session actually pays is the core set, and `mcp-toolset.test.ts` holds+ // that number.+ expect(total).toBeLessThan(16_000);});it("attaches structuredContent only where an outputSchema was declared", async () => {@@ -180,6 +183,7 @@ describe("ix mcp structured output", () => {const server = createIxMcpServer({version: "test",proAvailable: true,+ tools: "all",runIx: async () => ({ ok: true, stdout: JSON.stringify({ shape: "unverified" }), stderr: "" }),});const client = new Client({ name: "ix-mcp-structured-pro-test", version: "1.0.0" });diff --git a/ix-cli/src/cli/__tests__/mcp-tool-params.test.ts b/ix-cli/src/cli/__tests__/mcp-tool-params.test.tsindex 470c5101..db5ca174 100644--- a/ix-cli/src/cli/__tests__/mcp-tool-params.test.ts+++ b/ix-cli/src/cli/__tests__/mcp-tool-params.test.ts@@ -13,7 +13,9 @@ afterEach(async () => {});async function connect(runIx: IxRunner): Promise<Client> {- const server = createIxMcpServer({ version: "test", runIx });+ // `all`: the four single-relation tools are what these cases are about, and+ // `--tools=core` advertises `ix_neighbors` in their place.+ const server = createIxMcpServer({ version: "test", runIx, tools: "all" });const client = new Client({ name: "ix-mcp-params-test", version: "1.0.0" });const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();await server.connect(serverTransport);diff --git a/ix-cli/src/cli/__tests__/mcp-toolset.test.ts b/ix-cli/src/cli/__tests__/mcp-toolset.test.tsnew file mode 100644index 00000000..f74cebe0--- /dev/null+++ b/ix-cli/src/cli/__tests__/mcp-toolset.test.ts@@ -0,0 +1,168 @@+// Copyright 2026 Ix Infrastructure Inc.++import { Client } from "@modelcontextprotocol/sdk/client/index.js";+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";+import { Command } from "commander";+import { afterEach, describe, expect, it } from "vitest";++import {+ createIxMcpServer,+ IX_MCP_CORE_TOOL_NAMES,+ IX_MCP_OSS_TOOL_NAMES,+ IX_MCP_PRO_TOOL_NAMES,+ type IxRunner,+ type ToolsetName,+} from "../../mcp/server.js";+import { registerMcpCommand } from "../commands/mcp.js";++const clients: Client[] = [];+afterEach(async () => {+ await Promise.all(clients.splice(0).map((client) => client.close()));+});++async function connect(opts: { tools?: ToolsetName; proAvailable?: boolean } = {}): Promise<Client> {+ const runIx: IxRunner = async () => ({ ok: true, stdout: "ok", stderr: "" });+ const server = createIxMcpServer({ version: "test", runIx, ...opts });+ const client = new Client({ name: "ix-mcp-toolset-test", version: "1.0.0" });+ const [ct, st] = InMemoryTransport.createLinkedPair();+ await server.connect(st);+ await client.connect(ct);+ clients.push(client);+ return client;+}++async function names(opts: Parameters<typeof connect>[0] = {}): Promise<string[]> {+ return (await (await connect(opts)).listTools()).tools.map((t) => t.name);+}++describe("the core toolset", () => {+ it("is what a session gets without asking", async () => {+ expect(await names()).toEqual([...IX_MCP_CORE_TOOL_NAMES]);+ });++ it("is ten tools, not twenty-six", async () => {+ // `tools/list` is paid on every session before a single call is made, and a+ // model choosing between 26 near-identical names picks worse than one+ // choosing between ten.+ expect(IX_MCP_CORE_TOOL_NAMES.length).toBe(10);+ expect((await names({ tools: "all" })).length).toBeGreaterThan(20);+ });++ it("costs a fraction of what the full catalog costs", async () => {+ const client = await connect();+ const core = JSON.stringify((await client.listTools()).tools).length;+ const full = JSON.stringify((await (await connect({ tools: "all" })).listTools()).tools).length;++ // Measured: 6,437 bytes for ten tools against 15,365 for today's catalog,+ // a 58% cut. The spec asked for 5 KB, which is not reachable: a tool with+ // no parameters at all is 412 bytes of name, description and annotations,+ // so ten of them are 4.1 KB before a single input is declared. Getting to+ // 5 KB would mean giving back the disambiguation parameters that make an+ // ambiguous symbol resolvable at all.+ expect(core).toBeLessThan(6_600);+ expect(core).toBeLessThan(full / 2);+ });++ it("keeps every tool reachable under --tools=all", async () => {+ expect(await names({ tools: "all" })).toEqual([...IX_MCP_OSS_TOOL_NAMES]);+ });++ it("still offers the Pro tools when Pro is installed, whichever set is asked for", async () => {+ // "Pro is installed, so its tools are offered" is not a contract a toolset+ // choice has any business silently reversing.+ for (const tools of ["core", "all"] as const) {+ const listed = await names({ tools, proAvailable: true });+ for (const pro of IX_MCP_PRO_TOOL_NAMES) expect(listed, tools).toContain(pro);+ }+ });++ it("does not register what it does not advertise", async () => {+ // A tool a client cannot see but can still call is a surface with no+ // documentation.+ const client = await connect();+ const result = await client.callTool({ name: "ix_rank", arguments: {} });+ expect(result.isError).toBe(true);+ });+});++describe("ix_neighbors", () => {+ it("replaces four tools whose schemas differed by one word", async () => {+ const listed = await names();+ expect(listed).toContain("ix_neighbors");+ for (const merged of ["ix_callers", "ix_callees", "ix_imports", "ix_imported_by"]) {+ expect(listed).not.toContain(merged);+ }+ });++ it("routes each relation to its command, dash and all", async () => {+ const calls: string[][] = [];+ const server = createIxMcpServer({+ version: "test",+ runIx: async (args) => {+ calls.push(args);+ return { ok: true, stdout: "ok", stderr: "" };+ },+ });+ const client = new Client({ name: "neighbors", version: "1.0.0" });+ const [ct, st] = InMemoryTransport.createLinkedPair();+ await server.connect(st);+ await client.connect(ct);+ clients.push(client);++ for (const relation of ["callers", "callees", "imports", "imported_by"] as const) {+ await client.callTool({ name: "ix_neighbors", arguments: { symbol: "verify", relation } });+ }++ expect(calls.map((c) => c[0])).toEqual(["callers", "callees", "imports", "imported-by"]);+ });++ it("carries the disambiguation flags through", async () => {+ const calls: string[][] = [];+ const server = createIxMcpServer({+ version: "test",+ runIx: async (args) => {+ calls.push(args);+ return { ok: true, stdout: "ok", stderr: "" };+ },+ });+ const client = new Client({ name: "neighbors-flags", version: "1.0.0" });+ const [ct, st] = InMemoryTransport.createLinkedPair();+ await server.connect(st);+ await client.connect(ct);+ clients.push(client);++ await client.callTool({+ name: "ix_neighbors",+ arguments: { symbol: "config", relation: "callers", kind: "function", pick: 2 },+ });++ expect(calls).toEqual([["callers", "--kind=function", "--pick=2", "--format=llm", "--", "config"]]);+ });+});++describe("tool descriptions", () => {+ it("stay inside a line, so a catalog is skimmable", async () => {+ const tools = (await (await connect({ tools: "all", proAvailable: true })).listTools()).tools;+ for (const tool of tools) {+ expect(tool.description, tool.name).toBeDefined();+ expect(tool.description!.length, `${tool.name}: ${tool.description}`).toBeLessThanOrEqual(120);+ }+ });++ it("tell a reader that rows carry places", async () => {+ const tools = (await (await connect()).listTools()).tools;+ const withPlaces = tools.filter((t) => /path:lines|path:start-end/.test(t.description ?? ""));+ expect(withPlaces.length).toBeGreaterThanOrEqual(4);+ });+});++describe("ix mcp --tools", () => {+ it("defaults to core and takes only the two sets", () => {+ const program = new Command();+ program.name("ix").exitOverride();+ registerMcpCommand(program);+ const mcp = program.commands.find((c) => c.name() === "mcp")!;+ const option = mcp.options.find((o) => o.long === "--tools")!;+ expect(option.defaultValue).toBe("core");+ });+});diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.tsindex eaf0da4a..d7c96a32 100644--- a/ix-cli/src/cli/__tests__/mcp.test.ts+++ b/ix-cli/src/cli/__tests__/mcp.test.ts@@ -20,7 +20,9 @@ afterEach(async () => {});async function connect(runIx: IxRunner, proAvailable = false): Promise<Client> {- const server = createIxMcpServer({ version: "test", runIx, proAvailable });+ const server = createIxMcpServer({ version: "test", runIx, proAvailable, tools: "all" });+ // `all`, because these assertions are about the whole catalog. The core+ // default has its own tests in mcp-toolset.test.ts.const client = new Client({ name: "ix-mcp-test", version: "1.0.0" });const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();diff --git a/ix-cli/src/cli/commands/mcp.ts b/ix-cli/src/cli/commands/mcp.tsindex 2805ad6e..641cacdc 100644--- a/ix-cli/src/cli/commands/mcp.ts+++ b/ix-cli/src/cli/commands/mcp.ts@@ -101,10 +101,15 @@ export function registerMcpCommand(program: Command): void {const mcp = program.command("mcp").description("Serve Ix tools over the Model Context Protocol (stdio)")- .action(async () => {+ .option(+ "--tools <set>",+ "Which catalog to advertise (core|all). core is ten tools; all is every one",+ "core",+ )+ .action(async (opts: { tools: string }) => {// Keep the SDK off the startup path for ordinary CLI commands.const { startIxMcpServer } = await import("../../mcp/server.js");- await startIxMcpServer(program.version());+ await startIxMcpServer(program.version(), opts.tools === "all" ? "all" : "core");});mcpdiff --git a/ix-cli/src/cli/register/oss.ts b/ix-cli/src/cli/register/oss.tsindex 4dc249ef..cd3d5f1e 100644--- a/ix-cli/src/cli/register/oss.ts+++ b/ix-cli/src/cli/register/oss.ts@@ -75,6 +75,7 @@ const OPTION_CHOICES: Record<string, Record<string, string[]>> = {subsystems: { sort: ["importance", "confidence", "size", "alpha"] },savings: { model: ["opus", "sonnet", "haiku", "gpt-4o"] },context: { depth: ["compact", "standard", "full", "shallow", "deep"] },+ mcp: { tools: ["core", "all"] },};/**diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.tsindex 09ba39ca..00af17a7 100644--- a/ix-cli/src/mcp/server.ts+++ b/ix-cli/src/mcp/server.ts@@ -38,6 +38,9 @@ export const IX_MCP_OSS_TOOL_NAMES = ["ix_overview","ix_read","ix_diff",+ // One tool for four relations. The four singles stay in the catalog for+ // `--tools=all`; `--tools=core` advertises this instead.+ "ix_neighbors","ix_callers","ix_callees","ix_imported_by",@@ -115,29 +118,30 @@ const WRITE_OPEN_WORLD: ToolAnnotations = {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_health: { ...READ_ONLY, title: "Is the graph up to date. Call once at most; every other tool reports its own failure" },ix_locate: { ...READ_ONLY, title: "Resolve a symbol to its canonical target" },ix_search: { ...READ_ONLY, title: "Search the graph by name" },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" },+ ix_impact: { ...READ_ONLY, title: "What a change to this would reach. Members and dependents carry path:lines" },+ ix_map: { ...WRITE, title: "Re-ingest the workspace. Slow; run after editing code, not before reading it" },+ ix_overview: { ...READ_ONLY, title: "One call: what a file or symbol is, what it holds, and what it touches" },// 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_diff: { ...READ_ONLY, title: "What changed between two graph revisions, by entity rather than by line" },+ ix_neighbors: { ...READ_ONLY, title: "List a symbol's callers, callees, imports or importers" },+ ix_callers: { ...READ_ONLY, title: "Who calls this. Rows carry path:lines. Prefer ix_neighbors" },+ ix_callees: { ...READ_ONLY, title: "What this calls. Rows carry path:lines. Prefer ix_neighbors" },+ ix_imported_by: { ...READ_ONLY, title: "What imports this. Rows carry path:lines. Prefer ix_neighbors" },+ ix_imports: { ...READ_ONLY, title: "What this imports. Rows carry path:lines. Prefer ix_neighbors" },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_trace: { ...READ_ONLY, title: "Follow edges through a symbol, or find a path to another one. Bounded by depth" },+ ix_explain: { ...READ_ONLY, title: "What a symbol is for, from its edges: role, importance, and who uses it with path:lines" },ix_rank: { ...READ_ONLY, title: "Rank graph entities by importance" },ix_inventory: { ...READ_ONLY, title: "List graph entities by kind" },- ix_smells: { ...WRITE, 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_smells: { ...WRITE, title: "Orphans, god modules and cycles the graph can see. Not a linter" },+ ix_stats: { ...READ_ONLY, title: "Node and edge counts by kind. Use to tell an empty graph from a missing symbol" },+ ix_subsystems: { ...READ_ONLY, title: "The regions the map grouped this repo into, with health and confidence" },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" },// Reads the graph and composes a bundle; the CLI's --save and --out, which are@@ -180,11 +184,42 @@ const TOOL_OUTPUT_SCHEMA: Partial<Record<(typeof IX_MCP_TOOL_NAMES)[number], z.Z// passing `structured: true` receives.};+/** Which catalog to advertise. */+export type ToolsetName = "core" | "all";++/**+ * The tools an agent actually needs, and the default.+ *+ * `tools/list` is paid on every session before a single call is made, and the+ * full catalog is 26 tools of which a recorded run used four. The cost is not+ * only bytes: a model choosing between 26 near-identical names picks worse than+ * one choosing between ten, and `ix_callers` / `ix_callees` / `ix_imports` /+ * `ix_imported_by` had byte-identical schemas differing only in a word.+ *+ * Those four are one `ix_neighbors{relation}` here. Everything that is gone is+ * still reachable with `--tools=all`, which advertises the whole catalog —+ * including the four singles, so nothing that works today stops working.+ */+export const IX_MCP_CORE_TOOL_NAMES = [+ "ix_health",+ "ix_locate",+ "ix_search",+ "ix_text",+ "ix_impact",+ "ix_overview",+ "ix_read",+ "ix_neighbors",+ "ix_explain",+ "ix_context",+] as const;+interface CreateServerOptions {version?: string;runIx?: IxRunner;/** Advertise the Pro tools. Resolved by {@link detectPro} at startup. */proAvailable?: boolean;+ /** Which catalog to advertise. Defaults to `core`. */+ tools?: ToolsetName;}type ToolInput = Record<string, unknown>;@@ -231,24 +266,39 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServerversion,});- registerTool(server, "ix_health", "Check Ix backend and graph readiness", {}, async () =>+ // `core` unless asked otherwise. A tool left out here is not removed from the+ // CLI, only from what this session is told about.+ const toolset: ToolsetName = options.tools ?? "core";+ const core = new Set<string>(IX_MCP_CORE_TOOL_NAMES);+ // The Pro tools are exempt from the core gate. They are already conditional+ // on Pro being installed, and "Pro is installed, so its tools are offered"+ // is a contract a toolset choice has no business silently reversing.+ const ctx: RegisterContext = {+ server,+ advertise: (name: string) =>+ toolset === "all"+ || core.has(name)+ || (IX_MCP_PRO_TOOL_NAMES as readonly string[]).includes(name),+ };++ registerTool(ctx, "ix_health", "Check Ix backend and graph readiness", {}, async () =>runFormatted(runIx, "ix_health", ix("status")),);registerTool(- server,+ ctx,"ix_locate",- "Resolve a symbol to its canonical graph-backed target",+ "One name to one definition, with its path:lines. Use before reading when a name is ambiguous",{ symbol: z.string().min(1) },async (input) => runFormatted(runIx, "ix_locate", ix("locate", [stringArg(input, "symbol")])),);registerTool(- server,+ ctx,"ix_search",- "Search the graph by name, ranked, with each hit's path",+ "Find a symbol by name. Ranked, each row carries path:lines. Use instead of grep for a definition",{term: z.string().min(1),- kind: z.string().min(1).optional().describe("narrow to one entity kind"),- path: z.string().min(1).optional().describe("narrow to files whose path contains this"),+ kind: z.string().min(1).optional(),+ path: z.string().min(1).optional(),language: z.string().min(1).optional(),limit: z.number().int().min(1).max(200).default(10),},@@ -261,9 +311,9 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerTool(- server,+ ctx,"ix_text",- "Search text across the indexed repository and return ranked hits",+ "Literal or regex search, code ranked above tests above prose. Use instead of grep for a string",{pattern: z.string().min(1),limit: z.number().int().min(1).max(100).default(20),@@ -278,14 +328,14 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerTool(- server,+ ctx,"ix_impact","Analyze the blast radius and risk of changing a symbol or file",{ target: z.string().min(1) },async (input) => runFormatted(runIx, "ix_impact", ix("impact", [stringArg(input, "target")])),);registerTool(- server,+ ctx,"ix_map","Ingest one path or refresh the full workspace architecture map",{ file: z.string().min(1).optional() },@@ -295,21 +345,21 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerTool(- server,+ ctx,"ix_overview","Return the structural overview of a symbol, file, or subsystem",{ target: z.string().min(1) },async (input) => runFormatted(runIx, "ix_overview", ix("overview", [stringArg(input, "target")])),);registerTool(- server,+ ctx,"ix_read",- "Read a symbol's source, or a line range of a file",+ "Source for a symbol, or path:start-end for a range. Prefer a range over a whole file",{symbol: z.string().min(1).describe("a symbol, a path, or `path:start-end`"),kind: z.string().min(1).optional(),path: z.string().min(1).optional(),- pick: z.number().int().min(1).max(50).optional().describe("choose the Nth candidate, 1-based"),+ pick: z.number().int().min(1).max(50).optional().describe("Nth candidate, 1-based"),},// Nothing is forwarded as a size bound: `ix read` owns its own cap, and a// second one here would be a number to keep in sync with it. A range goes@@ -318,7 +368,7 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServerrunFormatted(runIx, "ix_read", ix("read", [stringArg(input, "symbol")], symbolOptions(input, { limit: false }))),);registerTool(- server,+ ctx,"ix_diff","Show the structural diff between two graph revisions",{@@ -336,14 +386,35 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServerreturn runFormatted(runIx, "ix_diff", ix("diff", positionals, input.summary === true ? ["--summary"] : []));},);- registerSymbolTool(server, runIx, "ix_callers", "List incoming call edges", "callers");- registerSymbolTool(server, runIx, "ix_callees", "List outgoing call edges", "callees");- registerSymbolTool(server, runIx, "ix_imported_by", "List incoming import edges", "imported-by");- registerSymbolTool(server, runIx, "ix_imports", "List outgoing import edges", "imports");registerTool(- server,+ ctx,+ "ix_neighbors",+ "Who calls, is called by, imports or is imported by a symbol. Rows carry path:lines",+ {+ ...SYMBOL_TOOL_INPUT,+ relation: z+ .enum(["callers", "callees", "imports", "imported_by"])+ .describe("callers = who calls it; callees = what it calls"),+ },+ async (input) => {+ const relation = stringArg(input, "relation");+ // The CLI spells one of them with a dash.+ const command = relation === "imported_by" ? "imported-by" : relation;+ return runFormatted(+ runIx,+ "ix_neighbors",+ ix(command, [stringArg(input, "symbol")], symbolOptions(input)),+ );+ },+ );+ registerSymbolTool(ctx, runIx, "ix_callers", "List incoming call edges", "callers");+ registerSymbolTool(ctx, runIx, "ix_callees", "List outgoing call edges", "callees");+ registerSymbolTool(ctx, runIx, "ix_imported_by", "List incoming import edges", "imported-by");+ registerSymbolTool(ctx, runIx, "ix_imports", "List outgoing import edges", "imports");+ registerTool(+ ctx,"ix_depends",- "Show downstream dependencies to a bounded depth",+ "The dependent tree, bounded. Use when one hop of ix_neighbors is not enough",{symbol: z.string().min(1),depth: z.number().int().min(1).max(5).default(2),@@ -354,7 +425,7 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer])),);registerTool(- server,+ ctx,"ix_trace","Trace execution paths through a symbol",{@@ -372,7 +443,7 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerSymbolTool(- server,+ ctx,runIx,"ix_explain","Explain a symbol using graph evidence",@@ -382,9 +453,9 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer{ symbol: SYMBOL_TOOL_INPUT.symbol, kind: SYMBOL_TOOL_INPUT.kind, path: SYMBOL_TOOL_INPUT.path, pick: SYMBOL_TOOL_INPUT.pick },);registerTool(- server,+ ctx,"ix_rank",- "Rank graph entities by importance or connectivity",+ "The most connected entities of a kind. Use to find where to start in an unfamiliar repo",{by: z.string().min(1).default("dependents"),kind: z.string().min(1).default("class"),@@ -402,9 +473,9 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerTool(- server,+ ctx,"ix_inventory",- "List graph entities by kind, optionally scoped to a repository path",+ "Every entity of one kind, grouped by file. Use instead of a glob to enumerate symbols",{// Optional, and `--limit` is forwarded, because the CLI's own contract is// `--kind` required and `--path` an optional filter. Requiring a path@@ -422,7 +493,7 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerTool(- server,+ ctx,"ix_smells","Detect graph-backed architecture smells",{@@ -435,23 +506,23 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},async (input) => runSmells(runIx, input),);- registerTool(server, "ix_stats", "Return graph-wide statistics", {}, async () =>+ registerTool(ctx, "ix_stats", "Return graph-wide statistics", {}, async () =>runFormatted(runIx, "ix_stats", ix("stats")),);- registerTool(server, "ix_subsystems", "List graph-derived subsystems", {}, async () =>+ registerTool(ctx, "ix_subsystems", "List graph-derived subsystems", {}, async () =>runFormatted(runIx, "ix_subsystems", ix("subsystems")),);registerTool(- server,+ ctx,"ix_history",- "Show provenance and patch history for a file or symbol",+ "Which revisions touched this, and what each patch said it was doing",{ target: z.string().min(1) },async (input) => runFormatted(runIx, "ix_history", ix("history", [stringArg(input, "target")])),);registerTool(- server,+ ctx,"ix_context",- "Build a bounded, deterministic context bundle for a symbol, file, or entity",+ "Start here. Ranked evidence around a target, every row a path:lines, ending in reads to run",{target: z.string().min(1),as_of_rev: z.number().int().nonnegative().optional().describe("graph revision for historical context"),@@ -489,9 +560,9 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerTool(- server,+ ctx,"ix_ingest",- "Ingest a path, or issues/PRs/commits from a GitHub repository, into the graph",+ "Add a path or a GitHub repo to the graph. Slow; ix_map is the usual way in",{path: z.string().min(1).optional(),github: z.string().min(1).optional().describe("owner/repo"),@@ -517,11 +588,11 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer);if (options.proAvailable) {- registerTool(server, "ix_briefing", "Load the Ix Pro session briefing", {}, async () =>+ registerTool(ctx, "ix_briefing", "Load the Ix Pro session briefing", {}, async () =>runJson(runIx, "ix_briefing", ix("briefing")),);registerTool(- server,+ ctx,"ix_decisions","List Ix Pro architecture decisions, optionally scoped to a path",{ path: z.string().min(1).optional() },@@ -532,7 +603,7 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServer},);registerTool(- server,+ ctx,"ix_decide","Record an architecture decision with its rationale",{@@ -551,11 +622,11 @@ export function createIxMcpServer(options: CreateServerOptions = {}): McpServerreturn server;}-export async function startIxMcpServer(version = "0.0.0"): Promise<void> {+export async function startIxMcpServer(version = "0.0.0", tools: ToolsetName = "core"): Promise<void> {// Before anything can throw: the CLI's own handlers exit the process on any// stray error, which for a server means losing every tool mid-session.installServerErrorHandlers();- const server = createIxMcpServer({ version, proAvailable: await detectPro() });+ const server = createIxMcpServer({ version, tools, proAvailable: await detectPro() });// A dedicated handle on fd 1 rather than process.stdout, which the in-process// runner patches to capture command output.await server.connect(new StdioServerTransport(process.stdin, createProtocolStdout()));@@ -572,10 +643,10 @@ export async function startIxMcpServer(version = "0.0.0"): Promise<void> {*/const SYMBOL_TOOL_INPUT = {symbol: z.string().min(1),- kind: z.string().min(1).optional().describe("narrow to one entity kind"),- path: z.string().min(1).optional().describe("narrow to files whose path contains this"),- pick: z.number().int().min(1).max(50).optional().describe("choose the Nth candidate, 1-based"),- limit: z.number().int().min(1).max(500).optional().describe("max rows"),+ kind: z.string().min(1).optional(),+ path: z.string().min(1).optional(),+ pick: z.number().int().min(1).max(50).optional().describe("Nth candidate, 1-based"),+ limit: z.number().int().min(1).max(500).optional(),} as const;/** Turn the shared disambiguation input into CLI flags. */@@ -591,27 +662,36 @@ function symbolOptions(input: ToolInput, opts: { limit?: boolean } = {}): string}function registerSymbolTool(- server: McpServer,+ ctx: RegisterContext,runIx: IxRunner,name: string,description: string,command: string,input: z.ZodRawShape = SYMBOL_TOOL_INPUT,): void {- registerTool(server, name, description, input, async (args) =>+ registerTool(ctx, name, description, input, async (args) =>runFormatted(runIx, name, ix(command, [stringArg(args, "symbol")], symbolOptions(args))),);}+/** The server being built, and whether this session advertises a given tool. */+interface RegisterContext {+ server: McpServer;+ advertise: (name: string) => boolean;+}+function registerTool(- server: McpServer,+ ctx: RegisterContext,name: string,description: string,inputSchema: z.ZodRawShape,handler: (input: ToolInput) => Promise<CallToolResult>,outputSchema?: z.ZodType,): void {- server.registerTool(+ // Not registered at all rather than registered and hidden: a tool the client+ // cannot see but can still call is a surface with no documentation.+ if (!ctx.advertise(name)) return;+ ctx.server.registerTool(name,{description,diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex e712c14f..3aad478a 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -47,6 +47,12 @@ surfaces (#575).--limit 50` exits with an error rather than a shorter list. `--detailed`auto-paginates on its own; `--offset` or `--regions` turns that off, and`--limit` only sets the page size.+- **`ix mcp` advertises ten tools by default**, not twenty-six: `ix_health`,+ `ix_locate`, `ix_search`, `ix_text`, `ix_impact`, `ix_overview`, `ix_read`,+ `ix_neighbors`, `ix_explain` and `ix_context`. `ix_neighbors{relation}`+ replaces `ix_callers` / `ix_callees` / `ix_imports` / `ix_imported_by`, whose+ schemas differed by one word. `--tools=all` advertises every tool, and the Pro+ tools are offered under both whenever Pro is installed.- **`--pick <n>` is 1-based** everywhere it appears, and is how you resolve anambiguous target without re-running with a longer name.- **`--no-recursive` and `--no-open` negate a default-on behaviour**, so their@@ -389,7 +395,9 @@ Serve Ix tools over the Model Context Protocol (stdio).Subcommands: `install`, `doctor`.-No flags.+| Flag | Value | Default | Effect |+|---|---|---|---|+| `--tools` | `core\|all` | `core` | Which catalog to advertise — ten tools, or every one |#### `ix mcp install`