Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

Rename MCP tools to say what they do, keep old names as aliases

anirudhkumar-nanonets0f6af007ca00
diff --git a/.claude/skills/graft/SKILL.md b/.claude/skills/graft/SKILL.md
index 5be5c060..6ab23204 100644
--- a/.claude/skills/graft/SKILL.md
+++ b/.claude/skills/graft/SKILL.md
@@ -116,6 +116,6 @@ This is the per-turn figure; the statusline carries the running session total.
exhaustive where it matters, so reach for them first.
When the graft MCP server is connected, these are exposed as tools too:
-`graft_ask`, `graft_grep`, `graft_skeleton`, `graft_callers` (with
-`direction` / `depth`), `graft_map`, `graft_check`. Use whichever surface is
+`graft_find_code`, `graft_find_all`, `graft_file_api`, `graft_trace_calls` (with
+`direction` / `depth`), `graft_repo_map`, `graft_check_freshness`. Use whichever surface is
available; the guidance is identical.
diff --git a/README.md b/README.md
index 3cba4add..9a4fbca6 100644
--- a/README.md
+++ b/README.md
@@ -203,12 +203,12 @@ Both configs are user-level, so they apply to **every** repo you open with Codex
| Tool | Takes | What it's for |
|---|---|---|
-| `graft_ask` | a question | Ranked nodes with file:line, source inlined — usually the full answer, no follow-up read needed. |
-| `graft_skeleton` | a file path | Every signature in that file, no bodies — the API surface for a tenth of the tokens. |
-| `graft_callers` | a symbol | Who depends on it, or what it depends on with `direction: out`, N levels deep for blast radius. |
-| `graft_grep` | a regex | Every hit, grouped by enclosing symbol, ranked by how coupled that symbol is. |
-| `graft_map` | nothing | A first look at an unfamiliar repo: directory clusters, hubs, hotspots. |
-| `graft_check` | nothing | Whether the local graph has drifted from the code. |
+| `graft_find_code` | a question | Ranked nodes with file:line, source inlined — usually the full answer, no follow-up read needed. |
+| `graft_file_api` | a file path | Every signature in that file, no bodies — the API surface for a tenth of the tokens. |
+| `graft_trace_calls` | a symbol | Who depends on it, or what it depends on with `direction: out`, N levels deep for blast radius. |
+| `graft_find_all` | a regex | Every hit, grouped by enclosing symbol, ranked by how coupled that symbol is. |
+| `graft_repo_map` | nothing | A first look at an unfamiliar repo: directory clusters, hubs, hotspots. |
+| `graft_check_freshness` | nothing | Whether the local graph has drifted from the code. |
Register it by hand if your agent needs it explicit:
@@ -384,7 +384,7 @@ normalized on load — no regeneration needed.
An agent that reads the graph should be cheaper and faster without getting more answers wrong. That's the whole claim, so we measured it instead of asserting it.
-The harness ran three variants of the same Claude Sonnet 5 agent with the same file tools: **cold** (explores from zero), **Graft** (a `graft ask --source` bundle pushed up front), and **pull** (graft_ask/graft_skeleton tools, nothing injected — context paid for only when asked). An Opus 4.8 judge scored correctness with a required-keyword floor, so a fast-but-wrong answer couldn't win by being fast. Cost is cache-aware: reads ≈0.1×, writes 1.25×, the billing model agents actually run under.
+The harness ran three variants of the same Claude Sonnet 5 agent with the same file tools: **cold** (explores from zero), **Graft** (a `graft ask --source` bundle pushed up front), and **pull** (graft_find_code/graft_file_api tools, nothing injected — context paid for only when asked). An Opus 4.8 judge scored correctness with a required-keyword floor, so a fast-but-wrong answer couldn't win by being fast. Cost is cache-aware: reads ≈0.1×, writes 1.25×, the billing model agents actually run under.
162 runs, two repos (graft itself and a real Node/Express auth service), 3 trials each, tasks split between single-file and multi-file questions.
diff --git a/src/claude/init.ts b/src/claude/init.ts
index 9c6efd06..ced30568 100644
--- a/src/claude/init.ts
+++ b/src/claude/init.ts
@@ -5,7 +5,7 @@ import { mergeGraftSettings } from './settings-merge.js';
import { statuslineShim, hooksShim } from './shim-template.js';
import { skillTemplate } from './skill-template.js';
import { claudeDistDir } from './paths.js';
-import { mergeJsonKey, SERVER_ENTRY, type McpWrite } from '../hosts/mcp-config.js';
+import { mergeJsonKey, serverEntry, type McpWrite } from '../hosts/mcp-config.js';
import type { PlannedWrite } from '../hosts/plan.js';
/**
@@ -78,9 +78,9 @@ export function runInit(dir: string, opts: { build?: boolean; cliPath?: string }
writeFileSync(skillPath, skillTemplate());
// Register the graft MCP server in the project's .mcp.json so Claude Code
- // exposes graft_ask/graft_callers/etc. as tools — the same keyed merge the
+ // exposes graft_find_code/graft_trace_calls/etc. as tools — the same keyed merge the
// other hosts use (existing servers preserved; unparseable files skipped).
- const mcp = mergeJsonKey('claude', mcpTarget, 'mcpServers', SERVER_ENTRY);
+ const mcp = mergeJsonKey('claude', mcpTarget, 'mcpServers', serverEntry());
const built = buildGraphIfMissing(dir, opts);
return { settingsPath, shims: [sl, hk], skill: skillPath, mcp, warnings, built };
diff --git a/src/claude/settings-merge.ts b/src/claude/settings-merge.ts
index bf6810be..66f53bdc 100644
--- a/src/claude/settings-merge.ts
+++ b/src/claude/settings-merge.ts
@@ -2,7 +2,16 @@ type Json = Record<string, any>;
const SL_CMD = 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/graft-statusline.cjs"';
const FOOTER = 'graft/[\\w./-]+\\.md';
-const ALLOW_ENTRIES = ['Bash(graft:*)', 'Bash(npx graft:*)'];
+// Every form graft is actually invoked as. 'graft:*' covers a global install;
+// the other two cover a repo working on graft itself (or any consumer running it
+// from a checkout), where the binary is not on PATH under that name. A retrieval
+// call that raises a permission prompt loses to grep, which never does.
+const ALLOW_ENTRIES = [
+ 'Bash(graft:*)',
+ 'Bash(npx graft:*)',
+ 'Bash(graft-dev:*)',
+ 'Bash(node dist/cli.js:*)',
+];
function hookCmd(arg: string): string {
return `node "\${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/graft-hooks.cjs" ${arg}`;
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
index 26500f57..a2184ab8 100644
--- a/src/claude/skill-template.ts
+++ b/src/claude/skill-template.ts
@@ -145,8 +145,8 @@ This is the per-turn figure; the statusline carries the running session total.
exhaustive where it matters, so reach for them first.
When the graft MCP server is connected, these are exposed as tools too:
-\`graft_ask\`, \`graft_grep\`, \`graft_skeleton\`, \`graft_callers\` (with
-\`direction\` / \`depth\`), \`graft_map\`, \`graft_check\`. Use whichever surface is
+\`graft_find_code\`, \`graft_find_all\`, \`graft_file_api\`, \`graft_trace_calls\` (with
+\`direction\` / \`depth\`), \`graft_repo_map\`, \`graft_check_freshness\`. Use whichever surface is
available; the guidance is identical.
`;
}
diff --git a/src/cli.ts b/src/cli.ts
index 733c9d52..4447f880 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -333,7 +333,7 @@ program
program
.command("mcp")
- .description("Serve the graph over MCP (stdio) — exposes graft_ask, graft_callers, graft_grep, graft_skeleton, graft_map and graft_check as tools")
+ .description("Serve the graph over MCP (stdio) — exposes graft_find_code, graft_trace_calls, graft_find_all, graft_file_api, graft_repo_map and graft_check_freshness as tools")
.argument("[dir]", "repository root", ".")
.action(async (dir: string) => {
const { resolve } = await import("node:path");
diff --git a/src/graph/cards.ts b/src/graph/cards.ts
index 30094704..c8efefda 100644
--- a/src/graph/cards.ts
+++ b/src/graph/cards.ts
@@ -197,8 +197,8 @@ export function writeIndex(outDir: string, files: CardFileInfo[]): void {
// Whoever reads this file has already decided to look at graft, so this is the
// one place a pointer to the richer surface is welcome rather than noise. Stated
// as what exists, not as an instruction — see `mcp/instructions.ts` for why.
- "The same graph is queryable as MCP tools (`graft_ask`, `graft_grep`,",
- "`graft_callers`, `graft_skeleton`, `graft_map`) where a host exposes them, and",
+ "The same graph is queryable as MCP tools (`graft_find_code`, `graft_find_all`,",
+ "`graft_trace_calls`, `graft_file_api`, `graft_repo_map`) where a host exposes them, and",
"as the `graft` CLI everywhere else. Edges — who calls what — live only in the",
"graph, not in these files: `graft callers <symbol>` is the only way to read them.",
"",
diff --git a/src/graph/traverse-cli.ts b/src/graph/traverse-cli.ts
index 2ec2f2ff..e1e425fd 100644
--- a/src/graph/traverse-cli.ts
+++ b/src/graph/traverse-cli.ts
@@ -8,7 +8,7 @@
* unit-testable without shelling out to the CLI on every case.
*
* `--direction out` subsumes the old `graft callees`; `--depth N` subsumes the
- * old `graft impact`. Exported formatters are reused by the MCP `graft_callers`
+ * old `graft impact`. Exported formatters are reused by the MCP `graft_trace_calls`
* tool (`src/mcp/tools.ts`), so both surfaces render identical reports.
*/
import { resolve } from "node:path";
@@ -32,7 +32,7 @@ export interface CallersCliOptions {
const ARROW: Record<Direction, "←" | "→"> = { in: "←", out: "→" };
const DEFAULT_DEPTH = 1;
-/** Exported so the MCP `graft_callers` tool (`src/mcp/tools.ts`) can render the
+/** Exported so the MCP `graft_trace_calls` tool (`src/mcp/tools.ts`) can render the
* same human report format as the CLI, rather than re-implementing it — both
* surfaces walk the same edges via the same `resolveSymbol` / `edgeWalk` core. */
export function headerOf(n: NodeV1): string {
diff --git a/src/graph/traverse.ts b/src/graph/traverse.ts
index 6edea82c..7776065c 100644
--- a/src/graph/traverse.ts
+++ b/src/graph/traverse.ts
@@ -1,6 +1,6 @@
/**
* Pure graph-traversal core shared by `graft callers` (its `--direction`/
- * `--depth` flags), the MCP `graft_callers` tool, and `ask`'s structural
+ * `--depth` flags), the MCP `graft_trace_calls` tool, and `ask`'s structural
* intent path.
*
* Centralizes the symbol-resolution contract (bare name, qualified id-suffix,
@@ -203,7 +203,7 @@ export function impactOfFile(graph: GraphV1, fileNode: NodeV1, maxDepth = 2, dir
}
/**
- * The single entry point behind `graft callers` and the MCP `graft_callers`
+ * The single entry point behind `graft callers` and the MCP `graft_trace_calls`
* tool, covering all of what were once three commands:
* - `direction:in, depth:1` → callers (who calls/references this)
* - `direction:out, depth:1` → callees (what this calls/references)
diff --git a/src/hosts/mcp-config.ts b/src/hosts/mcp-config.ts
index 248d0843..b263e1dd 100644
--- a/src/hosts/mcp-config.ts
+++ b/src/hosts/mcp-config.ts
@@ -8,6 +8,7 @@
* `registerMcpConfigs()` walks that same list to do the writing.
*/
import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
import { dirname, join } from 'node:path';
import { homedir } from 'node:os';
import type { PlannedWrite } from './plan.js';
@@ -27,8 +28,50 @@ export interface McpTarget extends PlannedWrite {
entry?: object;
}
-export const SERVER_ENTRY = { command: 'npx', args: ['-y', '@nanonets/graft', 'mcp'] };
-const OPENCODE_ENTRY = { type: 'local', command: ['npx', '-y', '@nanonets/graft', 'mcp'], enabled: true };
+/**
+ * How to launch the MCP server, decided once at init time.
+ *
+ * `npx -y` resolves the package before it can serve: measured at a 211 ms
+ * spawn→`initialize` handshake against 80 ms for the installed binary, five runs
+ * each. The harness registers a server's tools only once that handshake lands, and
+ * a slow one can miss the first request entirely — in a traced session graft's
+ * tools arrived 13.9 s in, four model turns too late to shape the approach. (That
+ * 13.9 s is NOT explained by 130 ms; the gap's cause is still unknown. This is the
+ * cheap half of the fix, not the whole of it.)
+ *
+ * Deliberately a bare command name, never an absolute path: these files get
+ * committed and shared, and this repo already carries the scar of the alternative —
+ * a checked-in hook shim with another machine's home directory baked into it. A
+ * bare `graft` works on any machine that has it installed; `npx` remains the
+ * fallback for machines that don't.
+ */
+const NPX_LAUNCH = { command: 'npx', args: ['-y', '@nanonets/graft', 'mcp'] };
+const BIN_LAUNCH = { command: 'graft', args: ['mcp'] };
+
+function graftOnPath(): boolean {
+ const r = spawnSync('graft', ['--version'], { stdio: 'ignore', timeout: 5000 });
+ return r.status === 0;
+}
+
+/**
+ * JSON hosts: `{ command, args }`.
+ *
+ * `GRAFT_MCP_NPX=1` forces the `npx` form — the escape hatch for a machine whose
+ * global install is stale or shadowed, and what the tests set so their expectations
+ * don't depend on whether the machine running them happens to have graft installed.
+ * `opts.onPath` is the same override for direct unit tests of both branches.
+ */
+export function serverEntry(opts: { onPath?: boolean } = {}): { command: string; args: string[] } {
+ const forced = process.env.GRAFT_MCP_NPX;
+ if (forced !== undefined && forced !== '' && forced !== '0' && forced !== 'false') return NPX_LAUNCH;
+ return (opts.onPath ?? graftOnPath()) ? BIN_LAUNCH : NPX_LAUNCH;
+}
+
+
+function opencodeEntry(): object {
+ const { command, args } = serverEntry();
+ return { type: 'local', command: [command, ...args], enabled: true };
+}
function dirExists(p: string): boolean {
try { return statSync(p).isDirectory(); } catch { return false; }
@@ -60,7 +103,9 @@ function upsertCodexToml(id: string, path: string): McpWrite {
const existed = existsSync(path);
const text = existed ? readFileSync(path, 'utf8') : '';
if (/^\[mcp_servers\.graft\]$/m.test(text)) return { id, path, action: 'unchanged' };
- const section = `[mcp_servers.graft]\ncommand = "npx"\nargs = ["-y", "@nanonets/graft", "mcp"]\n`;
+ const { command, args } = serverEntry();
+ const argList = args.map((a) => JSON.stringify(a)).join(", ");
+ const section = `[mcp_servers.graft]\ncommand = \"${command}\"\nargs = [${argList}]\n`;
const sep = text.length === 0 ? '' : text.endsWith('\n') ? '\n' : '\n\n';
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, `${text}${sep}${section}`);
@@ -89,17 +134,18 @@ export function mcpTargets(
opts: { home?: string } = {},
): McpTarget[] {
const home = opts.home ?? homedir();
+ const entry = serverEntry();
const out: McpTarget[] = [];
for (const id of ids) {
switch (id) {
case 'cursor':
- out.push(jsonTarget(id, id, join(repo, '.cursor', 'mcp.json'), 'mcpServers', SERVER_ENTRY));
+ out.push(jsonTarget(id, id, join(repo, '.cursor', 'mcp.json'), 'mcpServers', entry));
break;
case 'gemini':
- out.push(jsonTarget(id, id, join(repo, '.gemini', 'settings.json'), 'mcpServers', SERVER_ENTRY));
+ out.push(jsonTarget(id, id, join(repo, '.gemini', 'settings.json'), 'mcpServers', entry));
break;
case 'kiro':
- out.push(jsonTarget(id, id, join(repo, '.kiro', 'settings', 'mcp.json'), 'mcpServers', SERVER_ENTRY));
+ out.push(jsonTarget(id, id, join(repo, '.kiro', 'settings', 'mcp.json'), 'mcpServers', entry));
break;
case 'agents':
// Guarded on the CLI actually being installed, so a plan only ever
@@ -111,7 +157,7 @@ export function mcpTargets(
});
}
if (dirExists(join(home, '.config', 'opencode'))) {
- out.push(jsonTarget(id, 'opencode', join(repo, 'opencode.json'), 'mcp', OPENCODE_ENTRY));
+ out.push(jsonTarget(id, 'opencode', join(repo, 'opencode.json'), 'mcp', opencodeEntry()));
}
break;
default:
diff --git a/src/mcp/instructions.ts b/src/mcp/instructions.ts
index 24f434bf..2375b775 100644
--- a/src/mcp/instructions.ts
+++ b/src/mcp/instructions.ts
@@ -26,11 +26,11 @@
/** Tool names in the order an agent should reach for them, most-used first. */
const TOOL_ORDER = [
- 'graft_ask',
- 'graft_grep',
- 'graft_callers',
- 'graft_skeleton',
- 'graft_map',
+ 'graft_find_code',
+ 'graft_find_all',
+ 'graft_trace_calls',
+ 'graft_file_api',
+ 'graft_repo_map',
] as const;
/** The `select:` argument that loads every graft tool in one lookup. */
@@ -46,11 +46,11 @@ export function mcpInstructions(): string {
'',
`**If these tools are deferred (names shown, schemas withheld), load them all in ONE lookup:** ToolSearch "${toolSearchQuery()}" — one round trip for the whole session. Never load them one at a time.`,
'',
- '- graft_ask — "how does X work" / "where is Y": ranked hits, code inlined.',
- '- graft_grep — when you need EVERY occurrence; ask is top-N and misses some.',
- '- graft_callers — who calls it, what it calls, blast radius before a rename.',
- '- graft_skeleton — a file\'s whole API in ~200 tokens.',
- '- graft_map — orientation in an unfamiliar repo.',
+ '- graft_find_code — "how does X work" / "where is Y": ranked hits, code inlined.',
+ '- graft_find_all — when you need EVERY occurrence; find_code is top-N and misses some.',
+ '- graft_trace_calls — who calls it, what it calls, blast radius before a rename.',
+ '- graft_file_api — a file\'s whole API in ~200 tokens.',
+ '- graft_repo_map — orientation in an unfamiliar repo.',
'',
'Results already reflect uncommitted edits — the graph refreshes before each query.',
].join('\n');
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 3bd472e8..8133871f 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -39,7 +39,7 @@ function unknownSymbolText(query: string): string {
export const TOOLS: ToolDef[] = [
{
- name: 'graft_ask',
+ name: 'graft_find_code',
description:
'Query the repo context graph in plain words. Returns ranked nodes with exact file:line spans and the relevant source inlined — usually the full answer, no file reads needed.',
inputSchema: {
@@ -60,7 +60,7 @@ export const TOOLS: ToolDef[] = [
},
},
{
- name: 'graft_skeleton',
+ name: 'graft_file_api',
description:
"Signatures-only view of one file — every definition's signature + line span, ~10× cheaper than reading the file ($0, no LLM).",
inputSchema: {
@@ -72,12 +72,12 @@ export const TOOLS: ToolDef[] = [
},
},
{
- name: 'graft_check',
+ name: 'graft_check_freshness',
description: 'Report whether the committed graph is in sync with the code (drift check).',
inputSchema: { type: 'object', properties: {} },
},
{
- name: 'graft_callers',
+ name: 'graft_trace_calls',
description:
'Structural edges for a symbol, over call/reference/import/implements/extends ($0, no LLM). Defaults to direct callers (who depends on it). Set direction:"out" for callees (what it calls); set depth>1 (or depth:"all" for the full closure) to walk transitively for the full blast radius — every source that breaks if it changes. Run before a multi-file refactor to find ALL affected files.',
inputSchema: {
@@ -96,7 +96,7 @@ export const TOOLS: ToolDef[] = [
},
},
{
- name: 'graft_grep',
+ name: 'graft_find_all',
description:
'Regex search over the graph\'s indexed files, hits grouped by innermost enclosing symbol and ranked by incoming-edge count (coupling) — which hit matters, not just where it is.',
inputSchema: {
@@ -111,7 +111,7 @@ export const TOOLS: ToolDef[] = [
},
},
{
- name: 'graft_map',
+ name: 'graft_repo_map',
description:
'Token-budgeted repo orientation — directory clusters, per-directory hubs, and global hotspots computed purely from the wiring graph ($0, no LLM). Use this to get oriented in an unfamiliar repo before diving into files.',
inputSchema: {
@@ -155,17 +155,17 @@ function callWorkspaceTool(
args: Record<string, unknown>,
): { text: string; isError: boolean } | null {
switch (name) {
- case 'graft_ask': {
+ case 'graft_find_code': {
const query = String(args.query ?? '');
- if (!query) return { text: 'graft_ask requires a query', isError: true };
+ if (!query) return { text: 'graft_find_code requires a query', isError: true };
const limit = typeof args.limit === 'number' ? args.limit : 5;
const inArg = typeof args.in === 'string' && args.in ? args.in : undefined;
const r = federateAsk(root, dirOverride, query, { limit, source: true, full: args.full === true, in: inArg });
return { text: formatAsk(r), isError: false };
}
- case 'graft_callers': {
+ case 'graft_trace_calls': {
const symbol = String(args.symbol ?? args.file ?? '');
- if (!symbol) return { text: 'graft_callers requires a symbol', isError: true };
+ if (!symbol) return { text: 'graft_trace_calls requires a symbol', isError: true };
const { text, found } = federateCallers(root, dirOverride, symbol, {
direction: args.direction === 'out' ? 'out' : 'in',
depth: typeof args.depth === 'number' && Number.isFinite(args.depth) ? args.depth : undefined,
@@ -173,9 +173,9 @@ function callWorkspaceTool(
});
return { text, isError: !found };
}
- case 'graft_grep': {
+ case 'graft_find_all': {
const pattern = String(args.pattern ?? '');
- if (!pattern) return { text: 'graft_grep requires a pattern', isError: true };
+ if (!pattern) return { text: 'graft_find_all requires a pattern', isError: true };
const { result, coverage } = federateGrep(root, dirOverride, pattern, {
ignoreCase: typeof args.ignore_case === 'boolean' ? args.ignore_case : undefined,
fixed: typeof args.fixed === 'boolean' ? args.fixed : undefined,
@@ -183,11 +183,11 @@ function callWorkspaceTool(
const text = result.totalHits === 0 ? zeroHitNote(result) : formatGrepResult(result);
return { text: coverage ? `${text}\n${coverage}` : text, isError: false };
}
- case 'graft_map': {
+ case 'graft_repo_map': {
const maxDirs = typeof args.max_dirs === 'number' && Number.isFinite(args.max_dirs) && args.max_dirs > 0 ? args.max_dirs : undefined;
return { text: federateMap(root, dirOverride, { maxDirs }), isError: false };
}
- case 'graft_check': {
+ case 'graft_check_freshness': {
const { text } = federateCheck(root, dirOverride);
return { text, isError: false };
}
@@ -197,16 +197,42 @@ function callWorkspaceTool(
}
/** Tools whose whole job is to REPORT drift. Rebuilding first would make
- * `graft_check` answer about a graph it just fixed, i.e. always "OK". */
-const NO_REFRESH_TOOLS = new Set(['graft_check']);
+ * `graft_check_freshness` answer about a graph it just fixed, i.e. always "OK". */
+const NO_REFRESH_TOOLS = new Set(['graft_check_freshness']);
+
+/**
+ * The pre-0.8.1 tool names, still accepted.
+ *
+ * The names were the reason for renaming: when a host defers graft's schemas it
+ * shows the model the *names alone* — no descriptions — so `graft_ask` had to
+ * compete with `Grep` on 9 characters of self-description. The new names say what
+ * they do. But a name is an API: skills, saved prompts, scripts and other people's
+ * notes reference the old ones, and silently 404-ing on them would be a worse
+ * outcome than an ugly name. Not advertised in {@link TOOLS} — the roster stays six
+ * — so this costs nothing in the payload and only ever rescues an old caller.
+ */
+const TOOL_ALIASES: Record<string, string> = {
+ graft_ask: 'graft_find_code',
+ graft_grep: 'graft_find_all',
+ graft_callers: 'graft_trace_calls',
+ graft_skeleton: 'graft_file_api',
+ graft_map: 'graft_repo_map',
+ graft_check: 'graft_check_freshness',
+};
+
+/** Canonical name for a requested tool: itself, or what it was renamed to. */
+export function canonicalToolName(name: string): string {
+ return TOOL_ALIASES[name] ?? name;
+}
export async function callTool(
root: string,
- name: string,
+ requestedName: string,
args: Record<string, unknown>,
dirOverride?: string,
): Promise<{ text: string; isError: boolean }> {
try {
+ const name = canonicalToolName(requestedName);
const ws = readWorkspace(root, dirOverride);
// Freshness first: an answer that cites file:line has to be about the code as
// it is right now, including edits nobody has committed (or even saved through
@@ -234,22 +260,22 @@ function callSingleTool(
dirOverride?: string,
): { text: string; isError: boolean } {
switch (name) {
- case 'graft_ask': {
+ case 'graft_find_code': {
const query = String(args.query ?? '');
- if (!query) return { text: 'graft_ask requires a query', isError: true };
+ if (!query) return { text: 'graft_find_code requires a query', isError: true };
const limit = typeof args.limit === 'number' ? args.limit : 5;
const engine = new Graft({ contextDir: dirOverride });
const inArg = typeof args.in === 'string' && args.in ? args.in : undefined;
const r = engine.ask(root, query, { limit, source: true, full: args.full === true, in: inArg });
return { text: formatAsk(r), isError: false };
}
- case 'graft_skeleton': {
+ case 'graft_file_api': {
const file = String(args.file ?? '');
- if (!file) return { text: 'graft_skeleton requires a file', isError: true };
+ if (!file) return { text: 'graft_file_api requires a file', isError: true };
const r = skeleton(root, file, { contextDir: dirOverride });
return { text: formatSkeleton(r), isError: !r.entries.length && !!r.note };
}
- case 'graft_check': {
+ case 'graft_check_freshness': {
const engine = new Graft({ contextDir: dirOverride });
const r = engine.check(root);
const g = engine.checkGraph(root);
@@ -257,7 +283,7 @@ function callSingleTool(
if (!g.missing) parts.push(formatGraphCheckReport(g));
return { text: parts.join('\n\n'), isError: false };
}
- case 'graft_callers': {
+ case 'graft_trace_calls': {
// One tool covers callers (direction:in, the default), callees
// (direction:out), and blast radius (depth>1). edgeWalk handles the
// file-seed aggregation that the old graft_blast_radius did: for a
@@ -265,7 +291,7 @@ function callSingleTool(
// it, so dependents that call into a symbol (targeting the SYMBOL id,
// never the FILE id) aren't silently dropped.
const symbol = String(args.symbol ?? args.file ?? '');
- if (!symbol) return { text: 'graft_callers requires a symbol', isError: true };
+ if (!symbol) return { text: 'graft_trace_calls requires a symbol', isError: true };
const w = loadGraphCached(contextDirFor(root, dirOverride));
if (!w) return { text: NO_GRAPH, isError: true };
const inOpt = typeof args.in === 'string' && args.in ? { in: args.in } : {};
@@ -286,9 +312,9 @@ function callSingleTool(
const text = body + savingsFooter(body, callersSavings(w, results));
return { text, isError: false };
}
- case 'graft_grep': {
+ case 'graft_find_all': {
const pattern = String(args.pattern ?? '');
- if (!pattern) return { text: 'graft_grep requires a pattern', isError: true };
+ if (!pattern) return { text: 'graft_find_all requires a pattern', isError: true };
const w = loadGraphCached(contextDirFor(root, dirOverride));
if (!w) return { text: NO_GRAPH, isError: true };
const result = grepGraph(w, root, pattern, {
@@ -299,7 +325,7 @@ function callSingleTool(
if (result.totalHits === 0) return { text: zeroHitNote(result), isError: false };
return { text: formatGrepResult(result), isError: false };
}
- case 'graft_map': {
+ case 'graft_repo_map': {
const w = loadGraphCached(contextDirFor(root, dirOverride));
if (!w) return { text: NO_GRAPH, isError: true };
const maxDirs = typeof args.max_dirs === 'number' && Number.isFinite(args.max_dirs) && args.max_dirs > 0 ? args.max_dirs : undefined;
diff --git a/src/search/grep-cli.ts b/src/search/grep-cli.ts
index 5eb7c5dd..0b25aaad 100644
--- a/src/search/grep-cli.ts
+++ b/src/search/grep-cli.ts
@@ -4,7 +4,7 @@
* Kept out of cli.ts (argument wiring only) and out of grep.ts (pure core,
* unit-testable against hand-built fixture graphs without touching a real
* repo root) — same split as traverse.ts/traverse-cli.ts. `formatGrepResult`
- * is exported so `graft_grep` in `src/mcp/tools.ts` renders the identical
+ * is exported so `graft_find_all` in `src/mcp/tools.ts` renders the identical
* report, rather than re-implementing it.
*/
import { resolve } from "node:path";
diff --git a/src/search/grep.ts b/src/search/grep.ts
index 66c1ff01..6e2d8dec 100644
--- a/src/search/grep.ts
+++ b/src/search/grep.ts
@@ -7,7 +7,7 @@
*
* Pure I/O + regex, no CLI/MCP concerns: `grep-cli.ts` formats this into
* human text and wires the CLI command; `mcp/tools.ts` renders the same
- * shape for the `graft_grep` tool.
+ * shape for the `graft_find_all` tool.
*/
import { readFileSync } from "node:fs";
import { join } from "node:path";
diff --git a/test/claude-init.test.ts b/test/claude-init.test.ts
index 3f382e26..559f4c28 100644
--- a/test/claude-init.test.ts
+++ b/test/claude-init.test.ts
@@ -1,5 +1,9 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
+
+// The MCP launch command is resolved from PATH at init time; pin it to the npx
+// form so these expectations are the same on every machine.
+process.env.GRAFT_MCP_NPX = '1';
import { mkdtempSync, readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
@@ -30,7 +34,7 @@ test('runInit scaffolds settings + both shims + the skill (build skipped)', () =
const s = JSON.parse(readFileSync(join(d, '.claude', 'settings.json'), 'utf8'));
assert.ok(s.statusLine.command.includes('graft-statusline.cjs'));
assert.ok(s.hooks.Stop[0].hooks[0].command.includes('graft-hooks.cjs'));
- assert.deepEqual(s.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(s.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
test('runInit overwrites a stale skill file', () => {
@@ -59,7 +63,7 @@ test('runInit is idempotent', () => {
runInit(d, { build: false });
const s = JSON.parse(readFileSync(join(d, '.claude', 'settings.json'), 'utf8'));
assert.equal(s.hooks.PostToolUse.length, 2); // post-edit + tool-savings, not duplicated on re-init
- assert.deepEqual(s.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(s.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
test('runInit appends the allowlist to a pre-existing permissions block, preserving unrelated entries', () => {
@@ -68,7 +72,7 @@ test('runInit appends the allowlist to a pre-existing permissions block, preserv
writeFileSync(join(d, '.claude', 'settings.json'), JSON.stringify({ permissions: { allow: ['Bash(ls)'] } }));
runInit(d, { build: false });
const s = JSON.parse(readFileSync(join(d, '.claude', 'settings.json'), 'utf8'));
- assert.deepEqual(s.permissions.allow, ['Bash(ls)', 'Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(s.permissions.allow, ['Bash(ls)', 'Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
test('postinstall prints the nudge in a fresh dir', () => {
diff --git a/test/claude-settings-merge.test.ts b/test/claude-settings-merge.test.ts
index 3d23427e..fd794fd8 100644
--- a/test/claude-settings-merge.test.ts
+++ b/test/claude-settings-merge.test.ts
@@ -50,41 +50,41 @@ test('re-running is idempotent (no duplicate Graft entries or footer)', () => {
test('foreign top-level keys survive', () => {
const { merged } = mergeGraftSettings({ model: 'claude-sonnet-5', permissions: { allow: ['Bash(ls)'] } });
assert.equal(merged.model, 'claude-sonnet-5');
- assert.deepEqual(merged.permissions.allow, ['Bash(ls)', 'Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(merged.permissions.allow, ['Bash(ls)', 'Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
test('fresh init adds the graft CLI allowlist', () => {
const { merged } = mergeGraftSettings({});
- assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
test('re-init does not duplicate allowlist entries', () => {
const once = mergeGraftSettings({}).merged;
const twice = mergeGraftSettings(once).merged;
- assert.deepEqual(twice.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(twice.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
test('pre-existing unrelated allow entries are preserved and ours appended', () => {
const existing = { permissions: { allow: ['Bash(ls)', 'Bash(git:*)'] } };
const { merged } = mergeGraftSettings(existing);
- assert.deepEqual(merged.permissions.allow, ['Bash(ls)', 'Bash(git:*)', 'Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(merged.permissions.allow, ['Bash(ls)', 'Bash(git:*)', 'Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
-test('pre-existing allow list already containing Bash(graft:*) is left unchanged aside from the missing entry', () => {
+test('a partially-present allowlist gains only what it lacks, in order', () => {
const existing = { permissions: { allow: ['Bash(graft:*)'] } };
const { merged } = mergeGraftSettings(existing);
- assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
-test('pre-existing allow list already containing both entries is unchanged', () => {
+test('pre-existing allow entries are kept and only the missing ones appended', () => {
const existing = { permissions: { allow: ['Bash(graft:*)', 'Bash(npx graft:*)'] } };
const { merged } = mergeGraftSettings(existing);
- assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
test('permissions object with no allow key gets one added; other keys preserved', () => {
const existing = { permissions: { deny: ['Bash(rm:*)'] } };
const { merged } = mergeGraftSettings(existing);
assert.deepEqual(merged.permissions.deny, ['Bash(rm:*)']);
- assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)']);
+ assert.deepEqual(merged.permissions.allow, ['Bash(graft:*)', 'Bash(npx graft:*)', 'Bash(graft-dev:*)', 'Bash(node dist/cli.js:*)']);
});
diff --git a/test/graph-load.test.ts b/test/graph-load.test.ts
index f3a3124e..8b84e86e 100644
--- a/test/graph-load.test.ts
+++ b/test/graph-load.test.ts
@@ -123,14 +123,14 @@ test("loadAskIndexCached: caches and invalidates the same way as the graph loade
// the way. `graph-refresh.test.ts` covers the refresh itself.
process.env.GRAFT_NO_REFRESH = "1";
-test("callTool: graft_callers on the same dir twice doesn't reparse the graph", async () => {
+test("callTool: graft_trace_calls on the same dir twice doesn't reparse the graph", async () => {
const dir = fixtureDir();
mkdirSync(join(dir, "src"), { recursive: true });
writeFileSync(join(dir, "src", "math.ts"), "export function add() { return 1; }\n");
const graph: GraphV1 = {
version: 1,
// A real `buildGraph` always emits a `kind: "file"` node per source file;
- // include one here too so `graft_callers` with depth (a `resolveSymbol` +
+ // include one here too so `graft_trace_calls` with depth (a `resolveSymbol` +
// `edgeWalk` walk, the old `graft impact`) can resolve the filename-shaped
// query the way it would against a real build.
nodes: [
@@ -139,7 +139,7 @@ test("callTool: graft_callers on the same dir twice doesn't reparse the graph",
],
edges: [],
} as GraphV1;
- // graft_callers reads through `contextDirFor(root)`, i.e. `<root>/graft`
+ // graft_trace_calls reads through `contextDirFor(root)`, i.e. `<root>/graft`
// by default — write the graph there directly rather than round-tripping
// through a real `graft build`.
const outDir = join(dir, "graft");
@@ -147,11 +147,11 @@ test("callTool: graft_callers on the same dir twice doesn't reparse the graph",
writeGraph(graph, outDir);
__resetParseCounts();
- const r1 = await callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
+ const r1 = await callTool(dir, "graft_trace_calls", { symbol: "src/math.ts", depth: 2 });
assert.equal(r1.isError, false);
assert.equal(__parseCount.graph, 1);
- const r2 = await callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
+ const r2 = await callTool(dir, "graft_trace_calls", { symbol: "src/math.ts", depth: 2 });
assert.equal(r2.isError, false);
assert.equal(__parseCount.graph, 1, "second call on the same dir must not reparse");
});
diff --git a/test/graph-refresh.test.ts b/test/graph-refresh.test.ts
index ef7b5e9c..86970113 100644
--- a/test/graph-refresh.test.ts
+++ b/test/graph-refresh.test.ts
@@ -398,24 +398,24 @@ test("a workspace refreshes its children even under a --dir override", async ()
assert.equal(hasSymbol(child, "src/math.ts#mul"), true);
});
-test("callTool refreshes before answering — except for graft_check", async () => {
+test("callTool refreshes before answering — except for graft_check_freshness", async () => {
const d = repo();
await buildGraph(d);
writeFileSync(join(d, "src", "math.ts"), `${MATH}export function mul(a: number, b: number): number {\n return a * b;\n}\n`);
- // graft_check is the drift report: refreshing first would make it always say OK.
- const check = await callTool(d, "graft_check", {});
+ // graft_check_freshness is the drift report: refreshing first would make it always say OK.
+ const check = await callTool(d, "graft_check_freshness", {});
assert.equal(check.isError, false);
assert.ok(!check.text.startsWith("[graft] refreshed"));
assert.equal(hasSymbol(d, "src/math.ts#mul"), false, "check must not rebuild");
- const ask = await callTool(d, "graft_ask", { query: "multiply two numbers" });
+ const ask = await callTool(d, "graft_find_code", { query: "multiply two numbers" });
assert.equal(ask.isError, false);
assert.match(ask.text, /^\[graft\] refreshed the graph/);
assert.equal(hasSymbol(d, "src/math.ts#mul"), true);
assert.match(ask.text, /mul/, "and the answer knows about the symbol that was never committed");
- const again = await callTool(d, "graft_ask", { query: "multiply two numbers" });
+ const again = await callTool(d, "graft_find_code", { query: "multiply two numbers" });
assert.ok(!again.text.startsWith("[graft] refreshed"), "nothing moved — no note, no rebuild");
});
diff --git a/test/hosts-init.test.ts b/test/hosts-init.test.ts
index c56d790f..1d414ecb 100644
--- a/test/hosts-init.test.ts
+++ b/test/hosts-init.test.ts
@@ -1,5 +1,9 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
+
+// The MCP launch command is resolved from PATH at init time; pin it to the npx
+// form so these expectations are the same on every machine.
+process.env.GRAFT_MCP_NPX = '1';
import { mkdtempSync, mkdirSync, readFileSync, readdirSync, writeFileSync, existsSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
diff --git a/test/hosts-mcp-config.test.ts b/test/hosts-mcp-config.test.ts
index af015dab..8c819092 100644
--- a/test/hosts-mcp-config.test.ts
+++ b/test/hosts-mcp-config.test.ts
@@ -1,9 +1,13 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
+
+// The MCP launch command is resolved from PATH at init time; pin it to the npx
+// form so these expectations are the same on every machine.
+process.env.GRAFT_MCP_NPX = '1';
import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
-import { registerMcpConfigs } from '../src/hosts/mcp-config.js';
+import { registerMcpConfigs, serverEntry } from '../src/hosts/mcp-config.js';
function fresh(): string { return mkdtempSync(join(tmpdir(), 'graft-mcpcfg-')); }
@@ -74,3 +78,24 @@ test('JSON with non-object mcpServers value is skipped', () => {
assert.deepEqual(w.map((x) => x.action), ['skipped-unparseable']);
assert.equal(readFileSync(join(repo, '.cursor', 'mcp.json'), 'utf8'), badJson);
});
+
+// The launch command: bare binary when graft is installed, npx otherwise. Never an
+// absolute path — these files are committed and shared between machines.
+test('serverEntry prefers the installed binary and falls back to npx', () => {
+ const saved = process.env.GRAFT_MCP_NPX;
+ delete process.env.GRAFT_MCP_NPX;
+ try {
+ assert.deepEqual(serverEntry({ onPath: true }), { command: 'graft', args: ['mcp'] });
+ assert.deepEqual(serverEntry({ onPath: false }), { command: 'npx', args: ['-y', '@nanonets/graft', 'mcp'] });
+ for (const e of [serverEntry({ onPath: true }), serverEntry({ onPath: false })]) {
+ assert.ok(!e.command.startsWith('/'), 'never an absolute path — configs get shared');
+ }
+ } finally {
+ if (saved !== undefined) process.env.GRAFT_MCP_NPX = saved;
+ }
+});
+
+test('GRAFT_MCP_NPX overrides an installed binary', () => {
+ process.env.GRAFT_MCP_NPX = '1';
+ assert.equal(serverEntry({ onPath: true }).command, 'npx', 'the escape hatch wins');
+});
diff --git a/test/mcp-server.test.ts b/test/mcp-server.test.ts
index 956ec04d..8b37b42d 100644
--- a/test/mcp-server.test.ts
+++ b/test/mcp-server.test.ts
@@ -34,7 +34,7 @@ test('initialize → tools/list → tools/call round-trip', async () => {
{ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '0' } } },
{ jsonrpc: '2.0', method: 'notifications/initialized' },
{ jsonrpc: '2.0', id: 2, method: 'tools/list' },
- { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'graft_callers', arguments: { symbol: 'x.ts', depth: 2 } } },
+ { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'graft_trace_calls', arguments: { symbol: 'x.ts', depth: 2 } } },
],
dir,
3,
@@ -46,12 +46,12 @@ test('initialize → tools/list → tools/call round-trip', async () => {
assert.equal(init.result.serverInfo.name, 'graft');
const list = rs.find((r) => r.id === 2);
assert.deepEqual(list.result.tools.map((t: any) => t.name), [
- 'graft_ask',
- 'graft_skeleton',
- 'graft_check',
- 'graft_callers',
- 'graft_grep',
- 'graft_map',
+ 'graft_find_code',
+ 'graft_file_api',
+ 'graft_check_freshness',
+ 'graft_trace_calls',
+ 'graft_find_all',
+ 'graft_repo_map',
]);
const call = rs.find((r) => r.id === 3);
assert.equal(call.result.isError, true); // unbuilt repo → soft error content
@@ -70,8 +70,8 @@ test('initialize carries instructions — the layer that survives tool deferral'
// A host that defers graft's schemas shows the model six bare names and nothing
// else, so this string has to carry both the pitch and the recovery instruction.
assert.match(instructions, /ONE lookup/, 'tells the agent to batch the schema fetch');
- assert.match(instructions, /select:mcp__graft__graft_ask,/, 'gives a copy-pasteable query');
- for (const t of ['graft_ask', 'graft_grep', 'graft_callers', 'graft_skeleton', 'graft_map']) {
+ assert.match(instructions, /select:mcp__graft__graft_find_code,/, 'gives a copy-pasteable query');
+ for (const t of ['graft_find_code', 'graft_find_all', 'graft_trace_calls', 'graft_file_api', 'graft_repo_map']) {
assert.ok(instructions.includes(t), `names ${t}`);
}
// Observed sibling servers sit at 660–984 chars; nothing proves a longer one
diff --git a/test/mcp-tools.test.ts b/test/mcp-tools.test.ts
index 15fd77a5..ec98a02d 100644
--- a/test/mcp-tools.test.ts
+++ b/test/mcp-tools.test.ts
@@ -4,7 +4,7 @@ import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { execFileSync } from 'node:child_process';
-import { TOOLS, callTool } from '../src/mcp/tools.js';
+import { TOOLS, callTool, canonicalToolName } from '../src/mcp/tools.js';
function builtRepo(): string {
const d = mkdtempSync(join(tmpdir(), 'graft-mcptools-'));
@@ -60,7 +60,7 @@ function fileScopeRepo(): string {
}
/** Five top-level dirs, one file each — enough groups that a small `max_dirs`
- * actually drops some, so the `graft_map` `max_dirs` arg has something to
+ * actually drops some, so the `graft_repo_map` `max_dirs` arg has something to
* prove it's wired through to `buildRepoMap`. */
function multiDirRepo(): string {
const d = mkdtempSync(join(tmpdir(), 'graft-mcptools-multidir-'));
@@ -74,62 +74,62 @@ function multiDirRepo(): string {
test('TOOLS lists the six tools with schemas', async () => {
assert.deepEqual(TOOLS.map((t) => t.name), [
- 'graft_ask',
- 'graft_skeleton',
- 'graft_check',
- 'graft_callers',
- 'graft_grep',
- 'graft_map',
+ 'graft_find_code',
+ 'graft_file_api',
+ 'graft_check_freshness',
+ 'graft_trace_calls',
+ 'graft_find_all',
+ 'graft_repo_map',
]);
for (const t of TOOLS) {
assert.ok(t.description.length > 0);
assert.equal((t.inputSchema as { type: string }).type, 'object');
}
- // graft_callers absorbed callees (direction) and blast radius (depth) — the
+ // graft_trace_calls absorbed callees (direction) and blast radius (depth) — the
// schema must document both flags.
- const callers = TOOLS.find((t) => t.name === 'graft_callers')!;
+ const callers = TOOLS.find((t) => t.name === 'graft_trace_calls')!;
const props = (callers.inputSchema as { properties: Record<string, unknown> }).properties;
- assert.ok('direction' in props, 'graft_callers schema should document `direction`');
- assert.ok('depth' in props, 'graft_callers schema should document `depth`');
+ assert.ok('direction' in props, 'graft_trace_calls schema should document `direction`');
+ assert.ok('depth' in props, 'graft_trace_calls schema should document `depth`');
});
-test('graft_ask returns ranked hits for a built repo', async () => {
+test('graft_find_code returns ranked hits for a built repo', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_ask', { query: 'how do I add numbers' });
+ const r = await callTool(d, 'graft_find_code', { query: 'how do I add numbers' });
assert.equal(r.isError, false);
assert.match(r.text, /add/);
assert.match(r.text, /src\/math\.ts/);
});
-test('graft_ask: `in` arg round-trips — narrows results to the prefix and is a soft isError on an unknown one', async () => {
+test('graft_find_code: `in` arg round-trips — narrows results to the prefix and is a soft isError on an unknown one', async () => {
const d = builtRepo();
- const ok = await callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'src' });
+ const ok = await callTool(d, 'graft_find_code', { query: 'how do I add numbers', in: 'src' });
assert.equal(ok.isError, false);
assert.match(ok.text, /src\/math\.ts/);
- const miss = await callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'nosuchdir' });
+ const miss = await callTool(d, 'graft_find_code', { query: 'how do I add numbers', in: 'nosuchdir' });
assert.equal(miss.isError, true);
assert.match(miss.text, /nothing indexed under "nosuchdir\/"/);
assert.match(miss.text, /or any path prefix/);
});
-test('graft_check reports the wiring state', async () => {
+test('graft_check_freshness reports the wiring state', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_check', {});
+ const r = await callTool(d, 'graft_check_freshness', {});
assert.equal(r.isError, false);
assert.match(r.text, /graph check: OK/);
});
-test('graft_callers with depth names dependents of a file (blast radius)', async () => {
+test('graft_trace_calls with depth names dependents of a file (blast radius)', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_callers', { symbol: 'src/math.ts', depth: 2 });
+ const r = await callTool(d, 'graft_trace_calls', { symbol: 'src/math.ts', depth: 2 });
assert.equal(r.isError, false);
assert.ok(r.text.length > 0);
});
test('unbuilt repo and unknown tool are soft errors', async () => {
const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-bare-'));
- const r1 = await callTool(bare, 'graft_callers', { symbol: 'x.ts', depth: 2 });
+ const r1 = await callTool(bare, 'graft_trace_calls', { symbol: 'x.ts', depth: 2 });
assert.equal(r1.isError, true);
assert.match(r1.text, /graft build/);
const r2 = await callTool(bare, 'nope', {});
@@ -137,57 +137,57 @@ test('unbuilt repo and unknown tool are soft errors', async () => {
assert.match(r2.text, /unknown tool/i);
});
-test('graft_callers round-trips a caller on the built fixture', async () => {
+test('graft_trace_calls round-trips a caller on the built fixture', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_callers', { symbol: 'add' });
+ const r = await callTool(d, 'graft_trace_calls', { symbol: 'add' });
assert.equal(r.isError, false);
assert.match(r.text, /add · function · src\/math\.ts:/);
assert.match(r.text, /calls ← sub \(src\/math\.ts:/);
});
-test('graft_callers: qualified/--in narrowing still resolves through the shared resolver', async () => {
+test('graft_trace_calls: qualified/--in narrowing still resolves through the shared resolver', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_callers', { symbol: 'add', in: 'math' });
+ const r = await callTool(d, 'graft_trace_calls', { symbol: 'add', in: 'math' });
assert.equal(r.isError, false);
assert.match(r.text, /calls ← sub/);
- const miss = await callTool(d, 'graft_callers', { symbol: 'add', in: 'nowhere' });
+ const miss = await callTool(d, 'graft_trace_calls', { symbol: 'add', in: 'nowhere' });
assert.equal(miss.isError, true);
assert.match(miss.text, /no symbol "add" in the graph/);
});
-test('graft_callers direction:out round-trips a callee, and reports a loud note when there are none', async () => {
+test('graft_trace_calls direction:out round-trips a callee, and reports a loud note when there are none', async () => {
const d = builtRepo();
- const callee = await callTool(d, 'graft_callers', { symbol: 'sub', direction: 'out' });
+ const callee = await callTool(d, 'graft_trace_calls', { symbol: 'sub', direction: 'out' });
assert.equal(callee.isError, false);
assert.match(callee.text, /calls → add \(src\/math\.ts:/);
// `add` calls nothing, so its callees are empty — must be a loud note, not silence.
- const empty = await callTool(d, 'graft_callers', { symbol: 'add', direction: 'out' });
+ const empty = await callTool(d, 'graft_trace_calls', { symbol: 'add', direction: 'out' });
assert.equal(empty.isError, false);
assert.match(empty.text, /no indexed callees/);
assert.match(empty.text, /graft grep "add"/);
});
-test('graft_callers: unknown symbol / missing symbol are soft isErrors', async () => {
+test('graft_trace_calls: unknown symbol / missing symbol are soft isErrors', async () => {
const d = builtRepo();
- const r1 = await callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere' });
+ const r1 = await callTool(d, 'graft_trace_calls', { symbol: 'noSuchSymbolAnywhere' });
assert.equal(r1.isError, true);
assert.match(r1.text, /no symbol "noSuchSymbolAnywhere" in the graph/);
assert.match(r1.text, /check spelling|graft build/);
- const r2 = await callTool(d, 'graft_callers', {});
+ const r2 = await callTool(d, 'graft_trace_calls', {});
assert.equal(r2.isError, true);
assert.match(r2.text, /requires a symbol/);
});
-test('graft_callers: depth param is honored (depth 2 reaches further than depth 1)', async () => {
+test('graft_trace_calls: depth param is honored (depth 2 reaches further than depth 1)', async () => {
const d = chainRepo();
- const shallow = await callTool(d, 'graft_callers', { symbol: 'add', depth: 1 });
+ const shallow = await callTool(d, 'graft_trace_calls', { symbol: 'add', depth: 1 });
assert.equal(shallow.isError, false);
assert.match(shallow.text, /← sub \(/);
assert.doesNotMatch(shallow.text, /compute/);
- const deeper = await callTool(d, 'graft_callers', { symbol: 'add', depth: 2 });
+ const deeper = await callTool(d, 'graft_trace_calls', { symbol: 'add', depth: 2 });
assert.equal(deeper.isError, false);
assert.match(deeper.text, /← sub \(/);
assert.match(deeper.text, /\[depth 1\]/);
@@ -195,9 +195,9 @@ test('graft_callers: depth param is honored (depth 2 reaches further than depth
assert.match(deeper.text, /\[depth 2\]/);
});
-test('graft_callers depth>1 on a file aggregates dependents that call into a symbol the file defines, not just file-level imports', async () => {
+test('graft_trace_calls depth>1 on a file aggregates dependents that call into a symbol the file defines, not just file-level imports', async () => {
const d = fileScopeRepo();
- const r = await callTool(d, 'graft_callers', { symbol: 'src/a.ts', depth: 2 });
+ const r = await callTool(d, 'graft_trace_calls', { symbol: 'src/a.ts', depth: 2 });
assert.equal(r.isError, false);
// Walking only the FILE node's incoming edges would find b.ts via `imports`
// but drop it via `calls`, since a `calls` edge targets the SYMBOL id
@@ -206,66 +206,66 @@ test('graft_callers depth>1 on a file aggregates dependents that call into a sym
assert.match(r.text, /calls ← useB \(src\/b\.ts/);
});
-test('graft_callers: unknown symbol is a soft isError with the check-spelling message', async () => {
+test('graft_trace_calls: unknown symbol is a soft isError with the check-spelling message', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere', depth: 2 });
+ const r = await callTool(d, 'graft_trace_calls', { symbol: 'noSuchSymbolAnywhere', depth: 2 });
assert.equal(r.isError, true);
assert.match(r.text, /no symbol "noSuchSymbolAnywhere" in the graph/);
assert.match(r.text, /check spelling/);
});
-test('graft_grep round-trips a hit on the built fixture, grouped by enclosing symbol', async () => {
+test('graft_find_all round-trips a hit on the built fixture, grouped by enclosing symbol', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_grep', { pattern: 'add' });
+ const r = await callTool(d, 'graft_find_all', { pattern: 'add' });
assert.equal(r.isError, false);
assert.match(r.text, /"add" — \d+ hits? in \d+ symbols? across \d+ files? \(searched \d+ indexed files\)/);
assert.match(r.text, /src\/math\.ts/);
});
-test('graft_grep: no hits is a soft (non-error) result with the loud fallback note', async () => {
+test('graft_find_all: no hits is a soft (non-error) result with the loud fallback note', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_grep', { pattern: 'noSuchPatternAnywhere' });
+ const r = await callTool(d, 'graft_find_all', { pattern: 'noSuchPatternAnywhere' });
assert.equal(r.isError, false);
assert.match(r.text, /no hits for "noSuchPatternAnywhere"/);
assert.match(r.text, /retry graft grep/);
});
-test('graft_grep: missing pattern and unbuilt repo are soft errors', async () => {
+test('graft_find_all: missing pattern and unbuilt repo are soft errors', async () => {
const d = builtRepo();
- const r1 = await callTool(d, 'graft_grep', {});
+ const r1 = await callTool(d, 'graft_find_all', {});
assert.equal(r1.isError, true);
assert.match(r1.text, /requires a pattern/);
const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-grep-bare-'));
- const r2 = await callTool(bare, 'graft_grep', { pattern: 'add' });
+ const r2 = await callTool(bare, 'graft_find_all', { pattern: 'add' });
assert.equal(r2.isError, true);
assert.match(r2.text, /graft build/);
});
-test('graft_map round-trips a repo orientation on the built fixture', async () => {
+test('graft_repo_map round-trips a repo orientation on the built fixture', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_map', {});
+ const r = await callTool(d, 'graft_repo_map', {});
assert.equal(r.isError, false);
assert.match(r.text, /^repo map — \d+ files · \d+ symbols · \d+ edges/);
assert.match(r.text, /src/);
assert.match(r.text, /hotspots:/);
});
-test('graft_map: unbuilt repo is a soft isError with the no-graph message', async () => {
+test('graft_repo_map: unbuilt repo is a soft isError with the no-graph message', async () => {
const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-map-bare-'));
- const r = await callTool(bare, 'graft_map', {});
+ const r = await callTool(bare, 'graft_repo_map', {});
assert.equal(r.isError, true);
assert.match(r.text, /graft build/);
});
-test('graft_map: max_dirs arg is honored — the MCP escape hatch for dropped dirs', async () => {
+test('graft_repo_map: max_dirs arg is honored — the MCP escape hatch for dropped dirs', async () => {
const d = multiDirRepo();
- const capped = await callTool(d, 'graft_map', { max_dirs: 1 });
+ const capped = await callTool(d, 'graft_repo_map', { max_dirs: 1 });
assert.equal(capped.isError, false);
assert.match(capped.text, /\+4 more directories not shown/);
- const raised = await callTool(d, 'graft_map', { max_dirs: 10 });
+ const raised = await callTool(d, 'graft_repo_map', { max_dirs: 10 });
assert.equal(raised.isError, false);
assert.doesNotMatch(raised.text, /more directories? not shown/);
});
@@ -274,27 +274,68 @@ test('callTool honors a dirOverride for a graph built in a non-default dir', asy
const { repo, graphDir } = customDirRepo();
// With the override pointing at the actual graph location, tools find it.
- const check = await callTool(repo, 'graft_check', {}, graphDir);
+ const check = await callTool(repo, 'graft_check_freshness', {}, graphDir);
assert.equal(check.isError, false);
assert.match(check.text, /graph check: OK/);
- const callers = await callTool(repo, 'graft_callers', { symbol: 'add' }, graphDir);
+ const callers = await callTool(repo, 'graft_trace_calls', { symbol: 'add' }, graphDir);
assert.equal(callers.isError, false);
assert.match(callers.text, /calls ← sub \(src\/math\.ts:/);
// Without the override, tools fall back to the default `<repo>/graft`,
// which doesn't exist here — must report no graph, not silently succeed.
- const noOverride = await callTool(repo, 'graft_callers', { symbol: 'add' });
+ const noOverride = await callTool(repo, 'graft_trace_calls', { symbol: 'add' });
assert.equal(noOverride.isError, true);
assert.match(noOverride.text, /graft build/);
});
-test('graft_skeleton returns signatures for a file, errors on unknown file', async () => {
+test('graft_file_api returns signatures for a file, errors on unknown file', async () => {
const d = builtRepo();
- const r = await callTool(d, 'graft_skeleton', { file: 'src/math.ts' });
+ const r = await callTool(d, 'graft_file_api', { file: 'src/math.ts' });
assert.equal(r.isError, false);
assert.match(r.text, /graft skeleton — src\/math\.ts/);
assert.match(r.text, /function add {2}function add\(a: number, b: number\): number/);
- const miss = await callTool(d, 'graft_skeleton', { file: 'src/nope.ts' });
+ const miss = await callTool(d, 'graft_file_api', { file: 'src/nope.ts' });
assert.equal(miss.isError, true);
});
+
+// ── the rename: new names advertised, old names still answered ──
+// A tool name is an API. The rename exists because a host that defers graft's
+// schemas shows the model the names ALONE, so they have to describe themselves —
+// but skills, saved prompts and other people's scripts still say the old ones.
+const RENAMES: Record<string, string> = {
+ graft_ask: 'graft_find_code',
+ graft_grep: 'graft_find_all',
+ graft_callers: 'graft_trace_calls',
+ graft_skeleton: 'graft_file_api',
+ graft_map: 'graft_repo_map',
+ graft_check: 'graft_check_freshness',
+};
+
+test('TOOLS advertises exactly the six new names — the roster does not grow', () => {
+ assert.deepEqual([...TOOLS.map((t) => t.name)].sort(), Object.values(RENAMES).sort());
+});
+
+test('every old tool name still resolves to its replacement', () => {
+ for (const [old, neu] of Object.entries(RENAMES)) {
+ assert.equal(canonicalToolName(old), neu, `${old} → ${neu}`);
+ }
+ assert.equal(canonicalToolName('graft_find_code'), 'graft_find_code', 'new names pass through');
+ assert.equal(canonicalToolName('nope'), 'nope', 'unknown names are left alone for the error path');
+});
+
+test('an old name dispatches for real, not just in the alias map', async () => {
+ const d = builtRepo();
+ const viaOld = await callTool(d, 'graft_ask', { query: 'how do I add numbers' });
+ const viaNew = await callTool(d, 'graft_find_code', { query: 'how do I add numbers' });
+ assert.equal(viaOld.isError, false);
+ assert.match(viaOld.text, /add/);
+ assert.equal(viaOld.text, viaNew.text, 'the alias is the same call, not a near-miss');
+
+ // …including the one tool whose behaviour depends on its name being recognised:
+ // graft_check_freshness must not trigger a pre-query rebuild, or it would always
+ // report the graph it just fixed.
+ const check = await callTool(d, 'graft_check', {});
+ assert.equal(check.isError, false);
+ assert.ok(!check.text.startsWith('[graft] refreshed'), 'old check name still skips the refresh');
+});