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
// Copyright 2026 Ix Infrastructure Inc.
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 { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { statSync } from "node:fs";
import { isAbsolute, join, resolve as resolvePath } from "node:path";
import { z } from "zod";
import { isReadablePath, resolveWorkspaceRoot } from "../cli/config.js";
import { resolveIngestRootWithSource } from "../cli/map-root.js";
import {
createProtocolStdout,
DEFAULT_TIMEOUT_MS,
detectPro,
installServerErrorHandlers,
resolveDefaultRunner,
type IxRunner,
} from "./runner.js";
export type { IxRunner } from "./runner.js";
/**
* Tools every install can run.
*
* This set is the union of what the per-host Ix plugins expose, minus three
* deliberate drops: `ix_query` is the deprecated command the CLI docs tell
* agents not to use, and `ix_neighbors` / `ix_docs_tool` are convenience
* composites of `ix_callers` + `ix_callees` + `ix_depends` and of
* `ix_overview`, all of which are here individually.
*/
export const IX_MCP_OSS_TOOL_NAMES = [
// First, as it is registered first: tools/list leads with where to start.
"ix_context",
"ix_health",
"ix_locate",
// `ix search` is the command every other one starts from, and it was the one
// command with no tool at all — an agent over MCP could follow an edge from
// a symbol it already knew, and had no way to find the first symbol.
"ix_search",
"ix_text",
"ix_impact",
"ix_map",
"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",
"ix_imports",
"ix_depends",
"ix_trace",
"ix_explain",
"ix_rank",
"ix_inventory",
"ix_smells",
"ix_stats",
"ix_subsystems",
"ix_history",
"ix_ingest",
] as const;
/**
* Tools that need Ix Pro.
*
* Advertised only when the Pro package actually loads. Listing them
* unconditionally — as this server did for `ix_briefing` and `ix_decisions` —
* hands an OSS agent tools whose every call returns "requires Ix Pro", which it
* cannot tell apart from a real failure.
*/
export const IX_MCP_PRO_TOOL_NAMES = ["ix_briefing", "ix_decisions", "ix_decide"] as const;
/** 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 });
// Titles are display labels, a few words each. What a tool is FOR — when to
// reach for it, what it returns that Grep and Read cannot, and when not to use
// it — is in its description, which is the text a model actually weighs.
const TOOL_ANNOTATIONS: Record<(typeof IX_MCP_TOOL_NAMES)[number], ToolAnnotations> = {
ix_health: { ...READ_ONLY, title: "Graph health" },
ix_locate: { ...READ_ONLY, title: "Locate a definition" },
ix_search: { ...READ_ONLY, title: "Find definitions by name" },
ix_text: { ...READ_ONLY, title: "Ranked text search" },
ix_impact: { ...READ_ONLY, title: "Change impact" },
ix_map: { ...WRITE, title: "Re-map the workspace" },
ix_overview: { ...READ_ONLY, title: "Structural overview" },
// 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 by symbol or range" },
ix_diff: { ...READ_ONLY, title: "Graph diff between revisions" },
ix_neighbors: { ...READ_ONLY, title: "Callers, callees, imports, importers" },
ix_callers: { ...READ_ONLY, title: "Callers" },
ix_callees: { ...READ_ONLY, title: "Callees" },
ix_imported_by: { ...READ_ONLY, title: "Importers" },
ix_imports: { ...READ_ONLY, title: "Imports" },
ix_depends: { ...READ_ONLY, title: "Dependent tree" },
ix_trace: { ...READ_ONLY, title: "Trace paths" },
ix_explain: { ...READ_ONLY, title: "Explain a symbol" },
ix_rank: { ...READ_ONLY, title: "Rank by connectivity" },
ix_inventory: { ...READ_ONLY, title: "Inventory by kind" },
ix_smells: { ...WRITE, title: "Architecture smells" },
ix_stats: { ...READ_ONLY, title: "Graph statistics" },
ix_subsystems: { ...READ_ONLY, title: "Subsystems" },
ix_history: { ...READ_ONLY, title: "Patch history" },
ix_ingest: { ...WRITE_OPEN_WORLD, title: "Ingest a path or GitHub repo" },
// Reads the graph and composes a bundle; the CLI's --save and --out, which are
// the only parts of `ix context` that write anything, are not exposed here.
ix_context: { ...READ_ONLY, title: "Context bundle" },
// 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` 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.
};
/** 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 near-identical names picks worse than
* one choosing between a few that each answer a different question.
*
* Ten was still too many. With Ix connected and told to use it, recorded
* agents called `ix_context`, `ix_read` and `ix_search` and never `ix_explain`,
* `ix_impact`, `ix_overview` or `ix_locate` — four of the ten answered "tell me
* about X" and two were name lookups, so the graph's own answers (who calls
* this, what does a change reach) went unasked. The five kept are one per
* question, each something Grep/Glob/Read cannot answer in one step:
*
* - `ix_context`: where to start on a target or an issue, ranked.
* - `ix_search`: which definition a name means, definitions first.
* - `ix_neighbors`: who calls / is called by / imports / is imported by X.
* - `ix_impact`: what a change to X reaches.
* - `ix_read`: a definition's source by name, without knowing its file.
*
* Left for `--tools=all`: `ix_health` (every tool reports backend and graph
* failures itself), `ix_text` (ripgrep with a ranking — the caller already has
* Grep), and `ix_locate` / `ix_overview` / `ix_explain`, which `ix_search` and
* `ix_context` cover. Nothing is removed: `--tools=all` advertises the whole
* catalog, including the four `ix_neighbors` singles.
*/
export const IX_MCP_CORE_TOOL_NAMES = [
"ix_context",
"ix_search",
"ix_neighbors",
"ix_impact",
"ix_read",
] as const;
/**
* Server instructions, sent in the `initialize` result.
*
* The one channel that reaches the model when a host defers tool schemas.
* Claude Code shows a deferred server's tools as bare names until the model
* searches for them, and in 32 recorded runs no agent ever did, so not one
* tool description was read and Ix went uncalled. Instructions go into the
* system prompt either way.
*
* Written for an agent that already has Grep, Glob and Read: when the graph
* answers something they cannot, which tool, and when not to bother. Every
* tool it names is in the core set, so it is true for every session.
*/
export const IX_MCP_INSTRUCTIONS = [
"Ix is a code graph of this repository: definitions, calls and imports parsed from the source, not matched as text. Use it next to Grep/Glob/Read for what they cannot answer in one step:",
"- Where to start on an issue or task, or what a file or symbol touches: ix_context (target=<name or path>, or issue=<issue text>). Ranked evidence, each row path:lines.",
"- Who calls or imports X across files, or what X calls or imports: ix_neighbors (relation=callers|callees|imports|imported_by).",
"- What a change to X would reach, before you edit it: ix_impact.",
"- Which definition a name means when several share it: ix_search (definitions first); ix_read returns a definition's source by name.",
"Not for a literal string, a regex, or a line in a file you already have open: use Grep/Read.",
"No health check is needed first; a tool that cannot answer says why.",
].join("\n");
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>;
/**
* `ix_context` output schema — shared contract from the CLI bundle module so
* the MCP surface and persisted investigation state validate the same shape.
*/
/**
* One Ix invocationation, with its options kept apart from its positional values.
*
* The split is what lets every positional go behind a `--` separator. Appending
* them as bare tokens let commander read any value beginning with `-` as a
* flag: `ix_text` searching for `--force` failed outright, and searching for
* `--path` quietly consumed the following `--limit` as its value and ranked
* hits for the literal text `20` instead — a wrong answer the caller had no way
* to detect.
*/
interface IxArgv {
command: string;
positionals: string[];
options: string[];
}
function ix(command: string, positionals: string[] = [], options: string[] = []): IxArgv {
return { command, positionals, options };
}
export function createIxMcpServer(options: CreateServerOptions = {}): McpServer {
const version = options.version ?? "0.0.0";
// Built on first use, not here: constructing the default runner takes over
// process.stdout and process.exit, which a caller supplying its own runner
// (every test, and any embedder) must not have done to it.
let fallback: IxRunner | undefined;
const runIx: IxRunner =
options.runIx ??
((args, timeoutMs) =>
(fallback ??= resolveDefaultRunner({ version, redirectIdleStdout: true }))(args, timeoutMs));
const server = new McpServer(
{
// Not renamed: every existing registration is keyed by this name.
name: "ix-memory",
version,
},
{ instructions: IX_MCP_INSTRUCTIONS },
);
// `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),
};
// First, so it heads tools/list: it is where a session should start.
registerTool(
ctx,
"ix_context",
"Use first on an issue, a task, or an unfamiliar symbol or file (target=<name or path>, or issue=<text>). Returns ranked evidence (definition, members, callers, importers, related files, recent commits), each row path:lines, then next calls. Not for a literal string: use Grep.",
{
target: z.string().min(1).optional(),
issue: z.string().min(1).max(200_000).optional().describe("issue or task text, instead of target"),
kind: SYMBOL_TOOL_INPUT.kind,
path: SYMBOL_TOOL_INPUT.path,
pick: SYMBOL_TOOL_INPUT.pick,
as_of_rev: z.number().int().nonnegative().optional(),
max_entities: z.number().int().min(1).max(500).optional(),
max_relationships: z.number().int().min(1).max(1000).optional(),
max_evidence: z.number().int().min(1).max(200).optional(),
max_tokens: z.number().int().min(500).max(200_000).optional().describe("default 3000"),
max_chars: z
.number()
.int()
.min(1000)
.max(1_000_000)
.optional()
.describe("exact character budget, instead of max_tokens"),
structured: z
.boolean()
.optional()
.describe("JSON bundle as structuredContent, not records"),
},
async (input) => {
const hasTarget = typeof input.target === "string";
const hasIssue = typeof input.issue === "string";
// Checked here rather than left to the CLI, whose refusals name flags an
// MCP caller does not have.
const refusal =
hasTarget === hasIssue
? "pass exactly one of target or issue"
: hasIssue && ["kind", "path", "pick"].some((key) => input[key] !== undefined)
? "kind, path and pick narrow a named target; they do not combine with issue"
: input.max_tokens !== undefined && input.max_chars !== undefined
? "pass max_tokens or max_chars, not both; they bound the same evidence in different units"
: undefined;
if (refusal) return textResult(JSON.stringify({ error: refusal, tool: "ix_context" }), true);
const options: string[] = symbolOptions(input, { limit: false });
if (typeof input.as_of_rev === "number") options.push(`--as-of-rev=${numberArg(input, "as_of_rev")}`);
if (typeof input.max_entities === "number") options.push(`--max-entities=${numberArg(input, "max_entities")}`);
if (typeof input.max_relationships === "number")
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_tokens === "number") options.push(`--max-tokens=${numberArg(input, "max_tokens")}`);
if (typeof input.max_chars === "number") options.push(`--max-chars=${numberArg(input, "max_chars")}`);
const run = (argv: IxArgv) =>
// 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.
input.structured === true
? runJsonStructured(runIx, "ix_context", argv)
: runFormatted(runIx, "ix_context", argv);
if (hasTarget) return run(ix("context", [stringArg(input, "target")], options));
// `--from-issue` reads a file. The in-process runner has no stdin to give
// it, so the text goes through a private temp file that lives only for
// this call.
return withIssueFile(stringArg(input, "issue"), (file) =>
run(ix("context", [], [...options, `--from-issue=${file}`])),
);
},
);
registerTool(ctx, "ix_health", "Use only when a result suggests the graph is missing or stale. Returns backend reachability, workspace mapping and freshness. Not needed before other calls: each reports its own failure.", {}, async () =>
runFormatted(runIx, "ix_health", ix("status")),
);
registerTool(
ctx,
"ix_locate",
"Use when a name has several definitions and you want the canonical one. Returns one definition with path:lines, or the candidates when it cannot choose. For a ranked list use ix_search.",
{ symbol: z.string().min(1) },
async (input) => runFormatted(runIx, "ix_locate", ix("locate", [stringArg(input, "symbol")])),
);
registerTool(
ctx,
"ix_search",
"Use when you know a name, or part of one, and need its definition, or which of several same-named definitions you mean. Returns entities ranked definitions-first, each with kind and path:lines, not every text occurrence. Not for strings, comments or regex: use Grep.",
{
term: z.string().min(1),
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),
// Search hides test and fixture entities, and says how many it hid; this
// is the argument that hint names.
include_tests: z.boolean().optional(),
},
async (input) => {
const options = [`--limit=${numberArg(input, "limit")}`];
pushOption(options, "--kind", input.kind);
pushOption(options, "--path", input.path);
pushOption(options, "--language", input.language);
if (input.include_tests === true) options.push("--include-tests");
return runFormatted(runIx, "ix_search", ix("search", [stringArg(input, "term")], options));
},
);
registerTool(
ctx,
"ix_text",
"Use for a literal or regex match when you want code ranked above tests above docs. Returns matching lines with path:line. The same matches Grep finds; prefer Grep when you have it.",
{
pattern: z.string().min(1),
limit: z.number().int().min(1).max(100).default(20),
path: z.string().min(1).optional(),
language: z.string().min(1).optional(),
// Takes back next_offset= (see EDGE_TOOL_INPUT); no description, same budget.
offset: z.number().int().min(0).max(100000).optional(),
},
async (input) => {
const options = [`--limit=${numberArg(input, "limit")}`];
pushOption(options, "--path", input.path);
pushOption(options, "--language", input.language);
if (typeof input.offset === "number") options.push(`--offset=${numberArg(input, "offset")}`);
return runFormatted(runIx, "ix_text", ix("text", [stringArg(input, "pattern")], options));
},
);
registerTool(
ctx,
"ix_impact",
"Use before changing a symbol or file, to see what the change reaches. Returns a risk level, dependents grouped by subsystem and the most affected members with path:lines, which grep cannot compute. For a flat list of direct callers use ix_neighbors.",
{
target: z.string().min(1),
// The disambiguation the CLI already has. Without them an ambiguous name
// had no second call that could get past it.
kind: SYMBOL_TOOL_INPUT.kind,
path: SYMBOL_TOOL_INPUT.path,
pick: SYMBOL_TOOL_INPUT.pick,
// Caps the top-impacted members and the leaf caller/callee rows. The CLI
// default is 10, so the hint's "Raise --limit" needs this to be reachable.
limit: z.number().int().min(0).max(500).optional(),
},
async (input) => runFormatted(runIx, "ix_impact", ix("impact", [stringArg(input, "target")], symbolOptions(input))),
);
registerTool(
ctx,
"ix_map",
"Use after editing code, when later answers must see the change. Re-maps the whole workspace; unchanged files are skipped. Slow; not needed before reading.",
{},
// No path argument. `ix map` takes a workspace root and rejects a file
// ("Map path is not a directory"), and a subdirectory would be mapped as a
// workspace of its own. The old optional `file` is dropped from the schema,
// so a caller that still sends it gets the workspace map.
async () => runJson(runIx, "ix_map", ix("map"), 120_000),
);
registerTool(
ctx,
"ix_overview",
"Use for a one-call summary of a file, symbol or subsystem: what it is, what it holds, and what it touches. For ranked evidence around a task use ix_context.",
{ target: z.string().min(1) },
async (input) => runFormatted(runIx, "ix_overview", ix("overview", [stringArg(input, "target")])),
);
registerTool(
ctx,
"ix_read",
"Use when you have a symbol name but not its file or lines. Returns that definition's source, 400 lines a page (pass each next= back as symbol until none is given); also takes a path or path:start-end. Not needed when you already know path and range: Read does that.",
{
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("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
// in the target, where the CLI already takes one: `read src/a.ts:40-80`.
async (input) =>
runFormatted(runIx, "ix_read", ix("read", [stringArg(input, "symbol")], symbolOptions(input, { limit: false }))),
);
registerTool(
ctx,
"ix_diff",
"Use to see what changed between two graph revisions. Returns added, removed and modified entities rather than changed lines.",
{
from_rev: z.number().int().nonnegative(),
to_rev: z.number().int().nonnegative(),
target: z.string().min(1).optional(),
summary: z.boolean().default(false),
},
async (input) => {
const positionals = [
numberArg(input, "from_rev").toString(),
numberArg(input, "to_rev").toString(),
];
if (typeof input.target === "string") positionals.push(input.target);
return runFormatted(runIx, "ix_diff", ix("diff", positionals, input.summary === true ? ["--summary"] : []));
},
);
registerTool(
ctx,
"ix_neighbors",
"Use when you need who calls X, what X calls, what X imports, or which files import X, across the repo. Returns one row per resolved edge with path:lines, where grep finds every same-named symbol too. For transitive reach use ix_impact.",
{
...EDGE_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, { offset: true })),
);
},
);
registerSymbolTool(ctx, runIx, "ix_callers", "Who calls this, with path:lines. Prefer ix_neighbors.", "callers", EDGE_TOOL_INPUT);
registerSymbolTool(ctx, runIx, "ix_callees", "What this calls, with path:lines. Prefer ix_neighbors.", "callees", EDGE_TOOL_INPUT);
registerSymbolTool(ctx, runIx, "ix_imported_by", "What imports this, with path:lines. Prefer ix_neighbors.", "imported-by", EDGE_TOOL_INPUT);
registerSymbolTool(ctx, runIx, "ix_imports", "What this imports, with path:lines. Prefer ix_neighbors.", "imports", EDGE_TOOL_INPUT);
registerTool(
ctx,
"ix_depends",
"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),
},
async (input) =>
runFormatted(runIx, "ix_depends", ix("depends", [stringArg(input, "symbol")], [
`--depth=${numberArg(input, "depth")}`,
])),
);
registerTool(
ctx,
"ix_trace",
"Use to follow edges through a symbol, or find a path from it to another (to=). Returns the chain, bounded by depth.",
{
symbol: z.string().min(1),
to: z.string().min(1).optional(),
// The one tool whose traversal had no bound it could be told about:
// `ix_depends` has had a `depth` since it was written and this did not,
// so a trace through a hub ran as deep as the graph goes.
depth: z.number().int().min(1).max(10).default(3),
},
async (input) => {
const options = [`--depth=${numberArg(input, "depth")}`];
pushOption(options, "--to", input.to);
return runFormatted(runIx, "ix_trace", ix("trace", [stringArg(input, "symbol")], options));
},
);
registerSymbolTool(
ctx,
runIx,
"ix_explain",
"Use to learn what a symbol is for from how it is used. Returns its role, importance and main users with path:lines, inferred from graph edges. For ranked evidence around a task use ix_context.",
"explain",
// No `--limit`: `ix explain` has none, and forwarding a flag the command
// rejects turns a resolvable call into a usage error.
{ symbol: SYMBOL_TOOL_INPUT.symbol, kind: SYMBOL_TOOL_INPUT.kind, path: SYMBOL_TOOL_INPUT.path, pick: SYMBOL_TOOL_INPUT.pick },
);
registerTool(
ctx,
"ix_rank",
"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"),
top: z.number().int().min(1).max(100).default(10),
path: z.string().min(1).optional(),
},
async (input) => {
const options = [
`--by=${stringArg(input, "by")}`,
`--kind=${stringArg(input, "kind")}`,
`--top=${numberArg(input, "top")}`,
];
pushOption(options, "--path", input.path);
return runFormatted(runIx, "ix_rank", ix("rank", [], options));
},
);
registerTool(
ctx,
"ix_inventory",
"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
// made the documented `ix inventory --kind function` call impossible over
// MCP, and dropping the limit capped every answer at the CLI's default 50
// with no way to ask for more.
kind: z.string().min(1).default("file"),
path: z.string().min(1).optional(),
limit: z.number().int().min(1).max(500).default(50),
// Takes back next_offset= (see EDGE_TOOL_INPUT); no description, same budget.
offset: z.number().int().min(0).max(100000).optional(),
},
async (input) => {
const options = [`--kind=${stringArg(input, "kind")}`, `--limit=${numberArg(input, "limit")}`];
pushOption(options, "--path", input.path);
if (typeof input.offset === "number") options.push(`--offset=${numberArg(input, "offset")}`);
return runFormatted(runIx, "ix_inventory", ix("inventory", [], options));
},
);
registerTool(
ctx,
"ix_smells",
"Orphans, god modules and cycles the graph can see. Not a linter.",
{
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),
);
registerTool(ctx, "ix_stats", "Node and edge counts by kind. Use to tell an empty graph from a missing symbol.", {}, async () =>
runFormatted(runIx, "ix_stats", ix("stats")),
);
registerTool(ctx, "ix_subsystems", "The regions the map grouped this repo into, with health and confidence.", {}, async () =>
runFormatted(runIx, "ix_subsystems", ix("subsystems")),
);
registerTool(
ctx,
"ix_history",
"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(
ctx,
"ix_ingest",
"Add a path or a GitHub repo to the graph. A path inside a mapped workspace refreshes just that part of it. Slow; ix_map is the usual way in",
{
path: z.string().min(1).optional(),
github: z.string().min(1).optional().describe("owner/repo"),
limit: z.number().int().min(1).max(500).default(50),
since: z.string().min(1).optional().describe("ISO 8601 date"),
},
async (input) => {
if (typeof input.path === "string" && typeof input.github === "string") {
return textResult(
JSON.stringify({ error: "path and github are mutually exclusive; provide only one", tool: "ix_ingest" }),
true,
);
}
// Confined like ix_read. An ingested path's workspace becomes a root
// ix_read may open files from, so an unconfined path let a caller turn
// any directory into a readable one (ix_ingest, then ix_read).
// Resolved against the workspace root, as ingestFiles does, not cwd:
// from <ws>/a, "../outside/x" is <ws>/outside for cwd but outside for the CLI.
if (typeof input.path === "string") {
const abs = isAbsolute(input.path) ? input.path : resolvePath(resolveWorkspaceRoot(), input.path);
if (!isReadablePath(abs)) {
return textResult(
JSON.stringify({
error: "path_outside_workspace",
message: `Refusing to ingest a path outside the workspace: ${input.path}. Run ix map in that directory to make it a workspace.`,
tool: "ix_ingest",
}),
true,
);
}
// A path in no workspace and no repository would be ingested as a
// workspace of its own; over MCP that is refused. A path that does not
// exist falls through: the CLI reports it and registers nothing.
let isDir: boolean | undefined;
try { isDir = statSync(abs).isDirectory(); } catch { /* the CLI reports it */ }
if (isDir !== undefined && resolveIngestRootWithSource(abs, isDir).source === "loose") {
return textResult(
JSON.stringify({
error: "path_outside_workspace",
message: `Refusing to ingest ${input.path}: it is in no mapped workspace and no git repository. Run ix map in that directory to make it a workspace.`,
tool: "ix_ingest",
}),
true,
);
}
}
const options: string[] = [];
pushOption(options, "--github", input.github);
pushOption(options, "--since", input.since);
if (typeof input.github === "string") options.push(`--limit=${numberArg(input, "limit")}`);
const positionals = typeof input.path === "string" ? [input.path] : [];
// Ingestion walks the tree or pages a GitHub API, so it gets the same
// headroom as ix_map rather than the default read timeout.
return runJson(runIx, "ix_ingest", ix("ingest", positionals, options), 120_000);
},
);
if (options.proAvailable) {
registerTool(ctx, "ix_briefing", "Load the Ix Pro session briefing", {}, async () =>
runJson(runIx, "ix_briefing", ix("briefing")),
);
registerTool(
ctx,
"ix_decisions",
"List Ix Pro architecture decisions, optionally scoped to a path",
{ path: z.string().min(1).optional() },
async (input) => {
const options: string[] = [];
pushOption(options, "--path", input.path);
return runJson(runIx, "ix_decisions", ix("decisions", [], options));
},
);
registerTool(
ctx,
"ix_decide",
"Record an architecture decision with its rationale",
{
title: z.string().min(1),
rationale: z.string().min(1),
affects: z.string().min(1).optional().describe("entity the decision affects"),
},
async (input) => {
const options = [`--rationale=${stringArg(input, "rationale")}`];
pushOption(options, "--affects", input.affects);
return runJson(runIx, "ix_decide", ix("decide", [stringArg(input, "title")], options));
},
);
}
return server;
}
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, 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()));
}
/**
* The flags that let a caller resolve an ambiguous symbol.
*
* Every one of these tools took a bare `symbol` and nothing else, so a name
* with three definitions answered "Ambiguous symbol" and there was no second
* call that could get past it — the CLI's own `--pick`, `--kind` and `--path`
* were unreachable over MCP. An agent's only move was to shell out, which is
* the thing this server exists to avoid.
*/
const SYMBOL_TOOL_INPUT = {
symbol: z.string().min(1),
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;
/**
* The edge tools (ix_neighbors and the four single-relation tools) page with
* `offset`, following `next_offset=` on a results_truncated diagnostic: every
* tool that can print that diagnostic has to be able to take the offset back.
* Kept out of SYMBOL_TOOL_INPUT so ix_impact, ix_read and ix_explain do not
* grow a flag their commands lack. No description: five copies would push the
* full catalog past its tools/list budget (mcp-structured-output.test.ts), and
* for the same reason the four single-relation descriptions no longer spell
* out the ix_neighbors relation their own name already gives. An offset past
* the end is answered with an offset_past_end diagnostic, not an error.
*/
const EDGE_TOOL_INPUT = {
...SYMBOL_TOOL_INPUT,
offset: z.number().int().min(0).max(100000).optional(),
} as const;
/** Turn the shared disambiguation input into CLI flags. */
function symbolOptions(input: ToolInput, opts: { limit?: boolean; offset?: boolean } = {}): string[] {
const options: string[] = [];
pushOption(options, "--kind", input.kind);
pushOption(options, "--path", input.path);
if (typeof input.pick === "number") options.push(`--pick=${numberArg(input, "pick")}`);
if (opts.limit !== false && typeof input.limit === "number") {
options.push(`--limit=${numberArg(input, "limit")}`);
}
if (opts.offset === true && typeof input.offset === "number") {
options.push(`--offset=${numberArg(input, "offset")}`);
}
return options;
}
function registerSymbolTool(
ctx: RegisterContext,
runIx: IxRunner,
name: string,
description: string,
command: string,
input: z.ZodRawShape = SYMBOL_TOOL_INPUT,
): void {
const offset = "offset" in input;
registerTool(ctx, name, description, input, async (args) =>
runFormatted(runIx, name, ix(command, [stringArg(args, "symbol")], symbolOptions(args, { offset }))),
);
}
/** The server being built, and whether this session advertises a given tool. */
interface RegisterContext {
server: McpServer;
advertise: (name: string) => boolean;
}
function registerTool(
ctx: RegisterContext,
name: string,
description: string,
inputSchema: z.ZodRawShape,
handler: (input: ToolInput) => Promise<CallToolResult>,
outputSchema?: z.ZodType,
): void {
// 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,
inputSchema,
annotations: TOOL_ANNOTATIONS[name as keyof typeof TOOL_ANNOTATIONS],
// ix_context passes its schema as an argument rather than through the
// table, because the shape is owned by the CLI bundle module.
outputSchema: outputSchema ?? TOOL_OUTPUT_SCHEMA[name as keyof typeof TOOL_OUTPUT_SCHEMA],
},
async (input) => handler(input as ToolInput),
);
}
/**
* Flatten to argv: options first, then every positional behind `--`.
*
* Option values use the `--flag=value` form for the same reason, so a value of
* `--rationale` cannot be mistaken for the next flag.
*/
function toArgv(argv: IxArgv, format: string): string[] {
const args = [argv.command, ...argv.options, `--format=${format}`];
if (argv.positionals.length > 0) args.push("--", ...argv.positionals);
return args;
}
/**
* How much of one tool result a client should have to hold.
*
* The only bound before this was the runner's 16 MiB heap guard, which exists
* to stop a long-lived server growing — not to stop a single `ix text` filling
* a model's context. Most hosts truncate a tool result themselves, from the
* end, with no marker: the caller then cannot tell a short answer from a
* chopped one.
*/
const MAX_TOOL_RESULT_BYTES = 24 * 1024;
/**
* The failure text an error result carries. A command's stderr can be a whole
* stack trace or a multi-megabyte proxy page, and an error result goes into
* the model's context the same as a success does.
*/
const MAX_ERROR_DETAIL_CHARS = 4000;
export function capErrorDetail(detail: string): string {
return detail.length > MAX_ERROR_DETAIL_CHARS
? `${detail.slice(0, MAX_ERROR_DETAIL_CHARS)}… (${detail.length - MAX_ERROR_DETAIL_CHARS} more characters)`
: detail;
}
/**
* Cap a record stream, on a line boundary, and say so in a record.
*
* Record streams only. Cutting JSON produces something that does not parse,
* which is worse than something large — so `runJson`, `runJsonStructured` and
* `runSmells` are deliberately uncapped, and their size is bounded by the
* command's own budgets instead.
*/
export function capRecordStream(text: string, tool: string): string {
if (text.length <= MAX_TOOL_RESULT_BYTES) return text;
const boundary = text.lastIndexOf("\n", MAX_TOOL_RESULT_BYTES);
const head = text.slice(0, boundary > 0 ? boundary : MAX_TOOL_RESULT_BYTES);
return `${head}\ntruncated tool=${tool} shown_bytes=${head.length} total_bytes=${text.length} hint="Narrow the call — every one of these tools takes a limit, a path or a depth."`;
}
async function runFormatted(
runIx: IxRunner,
tool: string,
argv: IxArgv,
timeoutMs = DEFAULT_TIMEOUT_MS,
): Promise<CallToolResult> {
const result = await runCommand(runIx, tool, toArgv(argv, "llm"), timeoutMs);
if (result.isError) return result;
const first = result.content[0];
// Only the leading record governs status. `ix_read` may contain error-like
// source lines after its successful `content` record.
const semanticError = first?.type === "text" && first.text.startsWith("error code=");
if (semanticError) return { ...result, isError: true };
if (first?.type !== "text") return result;
const capped = capRecordStream(first.text, tool);
return capped === first.text
? result
: { ...result, content: [{ type: "text", text: capped }, ...result.content.slice(1)] };
}
async function runJson(
runIx: IxRunner,
tool: string,
argv: IxArgv,
timeoutMs = DEFAULT_TIMEOUT_MS,
): Promise<CallToolResult> {
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;
}
/**
* Run a command in JSON format and surface the parsed result as MCP
* `structuredContent` alongside the text payload. The context bundle carries
* its own versioned schema (`ix-context-bundle/1`), so the structured copy is
* stable across releases; when the output does not parse into a usable object
* we omit structured content and keep the text result authoritative rather
* than throwing. The copy leaves out `generatedAt`, the bundle's one per-call
* field, so identical calls return identical bytes and a prompt cache or dedup
* can match; `--save` / `--out` files and CLI stdout keep it.
*/
async function runJsonStructured(
runIx: IxRunner,
tool: string,
argv: IxArgv,
): Promise<CallToolResult> {
const result = await runIx(toArgv(argv, "json"), DEFAULT_TIMEOUT_MS);
if (!result.ok) {
const detail = result.stderr.trim() || result.stdout.trim() || `${argv.command} failed without output`;
return textResult(JSON.stringify({ error: capErrorDetail(detail), tool }), true);
}
const text = result.stdout.trim() || "{}";
const parsed = parseJsonOutput(text);
// The CLI contract for `--format=json` is a parseable bundle; when stdout is
// not a usable object the tool genuinely failed, and returning an MCP error
// is more truthful than inventing a bundle (the output schema requires
// schema-valid structured content on every result).
if (!isRecord(parsed) || Object.keys(parsed).length === 0) {
return textResult(text || JSON.stringify({ error: `${argv.command} produced no parseable JSON`, tool }), true);
}
const { generatedAt: _perCall, ...stable } = parsed;
return {
content: [{ type: "text", text: JSON.stringify(stable) }],
structuredContent: stable,
};
}
async function runCommand(
runIx: IxRunner,
tool: string,
args: string[],
timeoutMs: number,
): Promise<CallToolResult> {
const result = await runIx(args, timeoutMs);
if (!result.ok) {
const machineError = machineErrorOutput(result.stdout);
if (machineError) return textResult(machineError, true);
const detail =
result.stderr.trim() ||
result.stdout.trim() ||
`${args.slice(0, 2).join(" ")} failed without output`;
return textResult(JSON.stringify({ error: capErrorDetail(detail), tool }), true);
}
if (args.includes("--format=json")) {
const silent = silentJsonFailure(result, tool);
if (silent) return silent;
}
return textResult(result.stdout.trim() || "{}");
}
/**
* A JSON-mode run that "succeeded" with nothing on stdout and something on
* stderr: a command that failed without saying so through its exit code. A
* JSON command always prints its answer, so this is reported as the failure it
* is; turning the empty stdout into `{}` told the client the tool succeeded
* with nothing to say. Both empty is left to the caller, as before.
*/
function silentJsonFailure(result: { stdout: string; stderr: string }, tool: string): CallToolResult | null {
if (result.stdout.trim()) return null;
const stderr = result.stderr.trim();
return stderr ? textResult(JSON.stringify({ error: capErrorDetail(stderr), tool }), true) : null;
}
/**
* 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 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";
return textResult(JSON.stringify({ error: capErrorDetail(detail), tool: "ix_smells" }), true);
}
const silent = silentJsonFailure(result, "ix_smells");
if (silent) return silent;
const parsed = parseJsonOutput(result.stdout);
if (!isRecord(parsed) || !Array.isArray(parsed.candidates)) {
const text = textResult(result.stdout.trim() || "{}");
return structured ? withStructuredContent(text) : text;
}
const path = typeof input.path === "string" ? normalizePath(input.path) : null;
const limit = numberArg(input, "limit");
const matched = parsed.candidates
.filter((candidate) => {
if (path === null || !isRecord(candidate) || typeof candidate.file !== "string") {
return path === null;
}
// Substring, matching what `--path` means everywhere else in the CLI
// ("Filter by source file path substring" on inventory, the same on
// rank). Prefix matching answered `{"count": 0}` — a confident "no
// architecture smells here" — for the `src` an agent had just used
// successfully against ix_inventory on files stored as `ix-cli/src/...`.
return normalizePath(candidate.file).includes(path);
});
const candidates = matched.slice(0, limit);
// shown/truncated describe this response, not the CLI's, so recompute them
// after the path filter and limit.
const meta = "shown" in parsed
? { shown: candidates.length, truncated: parsed.truncated === true || matched.length > candidates.length }
: {};
const payload = { ...parsed, count: candidates.length, ...meta, candidates };
// 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;
}
/** Hand `work` a private file holding `text`, and remove it afterwards whatever happens. */
async function withIssueFile<T>(text: string, work: (file: string) => Promise<T>): Promise<T> {
const dir = await mkdtemp(join(tmpdir(), "ix-mcp-issue-"));
try {
const file = join(dir, "issue.md");
await writeFile(file, text, { encoding: "utf8", mode: 0o600 });
return await work(file);
} finally {
await rm(dir, { recursive: true, force: true });
}
}
function textResult(text: string, isError = false): CallToolResult {
return {
content: [{ type: "text", text }],
...(isError ? { isError: true } : {}),
};
}
function stringArg(input: ToolInput, key: string): string {
return input[key] as string;
}
function numberArg(input: ToolInput, key: string): number {
return input[key] as number;
}
function pushOption(options: string[], flag: string, value: unknown): void {
if (typeof value === "string" && value.length > 0) {
options.push(`${flag}=${value}`);
}
}
function parseJsonOutput(output: string): unknown {
const text = output.trim();
for (let index = 0; index < text.length; index += 1) {
if (text[index] !== "{" && text[index] !== "[") continue;
try {
return JSON.parse(text.slice(index));
} catch {
// A startup notice can contain punctuation before the actual JSON body.
}
}
return null;
}
function machineErrorOutput(output: string): string | null {
const text = output.trim();
if (text.startsWith("error code=")) return text;
const parsed = parseJsonOutput(text);
if (isRecord(parsed) && typeof parsed.error === "string") return text;
return null;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
function normalizePath(value: string): string {
return value.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
}