Skip to content

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

Merge branch 'main' of https://github.com/NanoNets/context-graph-engine

Shrish Dwivedi92d8ef6c8400
diff --cc graft/.graph/wiring.json
index 1171829d,8dd89cc8..8ae57e68
--- a/graft/.graph/wiring.json
+++ b/graft/.graph/wiring.json
@@@ -1,8 -1,8 +1,8 @@@
{
"meta": {
"version": 1,
- "nodeCount": 687,
- "edgeCount": 1786,
- "nodeCount": 621,
- "edgeCount": 1620,
++ "nodeCount": 701,
++ "edgeCount": 1823,
"languages": [
"typescript"
]
@@@ -2577,12 -2728,12 +2728,12 @@@
"name": "skill-template.ts",
"kind": "file",
"path": "src/claude/skill-template.ts",
- "span": "L1-L73",
- "span": "L1-L71",
++ "span": "L1-L77",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "504bd803d05aa6812ffaaf1a745f1eecab2fcd3e41f9029e5f0bf7db12025afd",
- "chars": 3767,
- "body_hash": "56d89c215e3ba0175d9f1ae2cf8baabe104c45d2b5bf2c18557ba29a4e97520b",
- "chars": 3725,
++ "body_hash": "4e951868562ef41f827b4828dc1931cf1e645d2e57999308b1919f62de5af7fb",
++ "chars": 4071,
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -2592,11 -2743,11 +2743,11 @@@
"name": "skillTemplate",
"kind": "function",
"path": "src/claude/skill-template.ts",
- "span": "L6-L72",
- "span": "L6-L70",
++ "span": "L6-L76",
"signature": "function skillTemplate(): string",
"exported": true,
"origin": "ast",
- "body_hash": "b882ca515f8601e55047f62c13837e42e8267c6d8f8c877329a4c7f8c73a2d7b",
- "body_hash": "687db45aebaf068cd90725a5fb01283394e6a3dc84be034fc828e8a11b1f4e48",
++ "body_hash": "a556c949cf0d4da9758a04f07d3a0d2ba7b7630e947aca38bdaad8430ee73a2f",
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -3256,12 -3407,12 +3407,12 @@@
"name": "cli.ts",
"kind": "file",
"path": "src/cli.ts",
- "span": "L1-L415",
- "span": "L1-L363",
++ "span": "L1-L430",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "5d7096b1320ec7422299df6fed455208659e6d91d76d1cb6c81bc9e9a0bc046d",
- "chars": 17906,
- "body_hash": "305a20f34e586f22be7eee9b5d3084586d96e1edfec50a819deb4c83978ee265",
- "chars": 16131,
++ "body_hash": "16405afe8b55c6c376785cbd9ddb2854631f6985ab287b5ac230189bf360d00e",
++ "chars": 18761,
"summary_state": "stale",
"summary": "This file implements the `graft` CLI tool for building and maintaining a context graph from code, ensuring it stays in sync with the repository.",
"crux": {
@@@ -3308,7 -3459,7 +3459,7 @@@
"name": "traverseAction",
"kind": "function",
"path": "src/cli.ts",
- "span": "L242-L248",
- "span": "L254-L260",
++ "span": "L257-L263",
"signature": "function traverseAction(kind: import(\"./graph/traverse-cli.js\").TraverseKind)",
"exported": false,
"origin": "ast",
@@@ -6756,12 -6344,12 +6907,12 @@@
"name": "instructions.ts",
"kind": "file",
"path": "src/hosts/instructions.ts",
- "span": "L1-L61",
- "span": "L1-L62",
++ "span": "L1-L65",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "36cac50d0acd13aaadb2459199cd9fc9e4ae60a955b62fd592175d2a81835de6",
- "chars": 2389,
- "body_hash": "b86b1f2dcc4d0b1e393c89f39cb772f76d5c592393f758603cfc20373fd98821",
- "chars": 2427,
++ "body_hash": "1dddea660f4d5e65952faf2beee42f04153ccab893658e75bda1dce6c0245b18",
++ "chars": 2627,
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -6771,7 -6359,7 +6922,7 @@@
"name": "cursorRule",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L40-L47",
- "span": "L41-L48",
++ "span": "L44-L51",
"signature": "function cursorRule(): string",
"exported": true,
"origin": "ast",
@@@ -6785,11 -6373,11 +6936,11 @@@
"name": "instructionBody",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L6-L38",
- "span": "L6-L39",
++ "span": "L6-L42",
"signature": "function instructionBody(): string",
"exported": true,
"origin": "ast",
- "body_hash": "5b5f2c1d46bcf84a58b255e183baf95ce52319002cd06aee6f8757cf846164da",
- "body_hash": "8cc2c40fcc950972a65305ce9773fa1e2bd0e99af84531af60f6ab1420b76697",
++ "body_hash": "9003c83453867680b4936696a28bb8086e14e432bb3c3debc4d7e5ab5ab7a0be",
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -6799,7 -6387,7 +6950,7 @@@
"name": "kiroSteering",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L49-L55",
- "span": "L50-L56",
++ "span": "L53-L59",
"signature": "function kiroSteering(): string",
"exported": true,
"origin": "ast",
@@@ -6813,7 -6401,7 +6964,7 @@@
"name": "windsurfRule",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L57-L60",
- "span": "L58-L61",
++ "span": "L61-L64",
"signature": "function windsurfRule(): string",
"exported": true,
"origin": "ast",
@@@ -7203,12 -6791,12 +7354,12 @@@
"name": "tools.ts",
"kind": "file",
"path": "src/mcp/tools.ts",
- "span": "L1-L221",
- "span": "L1-L193",
++ "span": "L1-L243",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "ee469ba03cc30f58916d1b6ab624664242fd3c743832e25f617b5a8b15d0530c",
- "chars": 9923,
- "body_hash": "2f134f9db2767f3595dbd3db26849ef5fb6e23bf58c3019d73e1f716c9eef7db",
- "chars": 8152,
++ "body_hash": "26d386319a711ec0eb758a2561513dc05e164f2c4d5828b6089b41db2b0a715b",
++ "chars": 10847,
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -7218,11 -6806,11 +7369,11 @@@
"name": "callTool",
"kind": "function",
"path": "src/mcp/tools.ts",
- "span": "L133-L220",
- "span": "L120-L192",
- "signature": "function callTool( root: string, name: string, args: Record<string, unknown>, ): { text: string; isError: boolean }",
++ "span": "L149-L242",
+ "signature": "function callTool( root: string, name: string, args: Record<string, unknown>, dirOverride?: string, ): { text: string; isError: boolean }",
"exported": true,
"origin": "ast",
- "body_hash": "aeeebfde3d08b44b32953ecc1b8f6358f1958fe6728baa378b2dcb1c306ff1ef",
- "body_hash": "5001ab4af1ff126fc4c0361469b41b8a7c3e44f1c26fb64d103d0a0fb3ec55be",
++ "body_hash": "ff7c769fef542a2ef86fd774fd9ad72aee3dc1745d295a675c530f76c530dab2",
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -7232,7 -6820,7 +7383,7 @@@
"name": "renderMatches",
"kind": "function",
"path": "src/mcp/tools.ts",
- "span": "L121-L131",
- "span": "L108-L118",
++ "span": "L137-L147",
"signature": "function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string",
"exported": false,
"origin": "ast",
@@@ -9185,12 -8348,12 +9378,12 @@@
"name": "mcp-server.test.ts",
"kind": "file",
"path": "test/mcp-server.test.ts",
- "span": "L1-L67",
- "span": "L1-L66",
++ "span": "L1-L68",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "69674cd877124d732de6426d45e9ad9d90031a3da4dfe8be54d893ebf1513337",
- "chars": 2582,
- "body_hash": "7cd0e518acabc53f7285a65502a76331813da3ed224b70795ce39801b666c2ee",
- "chars": 2569,
++ "body_hash": "4d828181f0a8c645f00097ab43c2bdcf5bc65da276e83b7503bc2888ae09f254",
++ "chars": 2604,
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -9214,12 -8377,12 +9407,12 @@@
"name": "mcp-tools.test.ts",
"kind": "file",
"path": "test/mcp-tools.test.ts",
- "span": "L1-L279",
- "span": "L1-L188",
++ "span": "L1-L290",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "68ce4d5883e0812cc246d9731bf4c1049a6db68b17646765d01161654d522b77",
- "chars": 12154,
- "body_hash": "36116ac8d25d8e7aa0dc185bc4171041602523889d693ee1f25f532c397446f0",
- "chars": 8150,
++ "body_hash": "22d3a32a85a0ba1542969786e8bda07d3df02ee068554d4070f705d30d7239dc",
++ "chars": 12646,
"summary_state": "pending",
"summary": null,
"crux": null
diff --cc graft/src/claude/skill-template.md
index ea4f4582,bb11a369..4b6deeb8
--- a/graft/src/claude/skill-template.md
+++ b/graft/src/claude/skill-template.md
@@@ -1,3 -1,3 +1,3 @@@
# src/claude/skill-template.ts
- - skillTemplate · function · L6-L72 — function skillTemplate(): string
-- skillTemplate · function · L6-L70 — function skillTemplate(): string
++- skillTemplate · function · L6-L76 — function skillTemplate(): string
diff --cc graft/src/cli.md
index 40fb37f3,dc1ff14d..36f27da2
--- a/graft/src/cli.md
+++ b/graft/src/cli.md
@@@ -2,6 -2,6 +2,6 @@@
This file implements the `graft` CLI tool for building and maintaining a context graph from code, ensuring it stays in sync with the repository.
-- engineFrom · function · L41-L44 — Creates an instance of the Graft engine configured with the specified context directory.
-- fmt · function · L80-L84 — Formats a record of counts into a human-readable string for console output.
-- traverseAction · function · L254-L260 — function traverseAction(kind: import("./graph/traverse-cli.js").TraverseKind)
+- engineFrom · function · L43-L46 — Creates an instance of the Graft engine configured with the specified context directory.
+- fmt · function · L82-L86 — Formats a record of counts into a human-readable string for console output.
- - traverseAction · function · L242-L248 — function traverseAction(kind: import("./graph/traverse-cli.js").TraverseKind)
++- traverseAction · function · L257-L263 — function traverseAction(kind: import("./graph/traverse-cli.js").TraverseKind)
diff --cc graft/src/hosts/instructions.md
index 2f439f6a,f63ea87f..1ae906f8
--- a/graft/src/hosts/instructions.md
+++ b/graft/src/hosts/instructions.md
@@@ -1,6 -1,6 +1,6 @@@
# src/hosts/instructions.ts
- - instructionBody · function · L6-L38 — function instructionBody(): string
- - cursorRule · function · L40-L47 — function cursorRule(): string
- - kiroSteering · function · L49-L55 — function kiroSteering(): string
- - windsurfRule · function · L57-L60 — function windsurfRule(): string
-- instructionBody · function · L6-L39 — function instructionBody(): string
-- cursorRule · function · L41-L48 — function cursorRule(): string
-- kiroSteering · function · L50-L56 — function kiroSteering(): string
-- windsurfRule · function · L58-L61 — function windsurfRule(): string
++- instructionBody · function · L6-L42 — function instructionBody(): string
++- cursorRule · function · L44-L51 — function cursorRule(): string
++- kiroSteering · function · L53-L59 — function kiroSteering(): string
++- windsurfRule · function · L61-L64 — function windsurfRule(): string
diff --cc graft/src/mcp/tools.md
index 6159e69c,5c6e5de5..0348feb6
--- a/graft/src/mcp/tools.md
+++ b/graft/src/mcp/tools.md
@@@ -1,6 -1,6 +1,6 @@@
# src/mcp/tools.ts
-- ToolDef · interface · L15-L19 — interface ToolDef
-- unknownSymbolText · function · L26-L28 — function unknownSymbolText(query: string): string
-- renderMatches · function · L108-L118 — function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string
-- callTool · function · L120-L192 — function callTool( root: string, name: string, args: Record<string, unknown>, ): { text: string; isError: boolean }
+- ToolDef · interface · L18-L22 — interface ToolDef
+- unknownSymbolText · function · L29-L31 — function unknownSymbolText(query: string): string
- - renderMatches · function · L121-L131 — function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string
- - callTool · function · L133-L220 — function callTool( root: string, name: string, args: Record<string, unknown>, dirOverride?: string, ): { text: string; isError: boolean }
++- renderMatches · function · L137-L147 — function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string
++- callTool · function · L149-L242 — function callTool( root: string, name: string, args: Record<string, unknown>, dirOverride?: string, ): { text: string; isError: boolean }
diff --cc src/hosts/instructions.ts
index 14039423,91819990..a6e38f61
--- a/src/hosts/instructions.ts
+++ b/src/hosts/instructions.ts
@@@ -12,17 -12,18 +12,21 @@@ system and carry exact file:line spans
For ANY task here — understanding how something works, finding where code lives,
or scoping a change — get context from the graph before grepping or opening
source files. Re-ask freely (it's cheap) and reuse literal identifiers you
-already have (symbol, error string, file name) as the query.
+already have (symbol, error string, file name) as the query. New to this repo?
+Run \`graft map\` first — a token-budgeted orientation (dir clusters, hubs,
+hotspots), no LLM, no key.
- Run \`graft ask "<your question>" --source\` → ranked nodes with the relevant
- code spans inlined. Match the tool to the task shape: for understanding or
- editing, the top node IS the answer — cite its \`covers:\` file:line spans and
- edit straight from \`--source\`. For exhaustive tasks ("every occurrence /
- every caller of this pattern"), ranked results are top-N, not complete — run
- \`graft grep "<literal>"\` instead (exhaustive over indexed files, grouped by
- enclosing symbol), falling back to raw \`grep -rn\` only for unindexed files.
+ code spans inlined (each hit's ≤8-line crux by default; \`--full\` for whole
+ definitions when the crux isn't enough). Match the tool to the task shape:
+ for understanding or editing, the top node IS the answer — cite its
+ \`covers:\` file:line spans and edit straight from \`--source\`. For
+ exhaustive tasks ("every occurrence / every caller of this pattern"), ranked
- results are top-N, not complete — use graft to orient, then enumerate with
- grep over the source and verify each hit.
++ results are top-N, not complete — run \`graft grep "<literal>"\` instead
++ (exhaustive over indexed files, grouped by enclosing symbol), falling back
++ to raw \`grep -rn\` only for unindexed files.
+ - \`graft skeleton <file>\` → every definition's signature + span, ~10× cheaper
+ than reading the file; use it to skim an API surface.
- \`graft callers/callees <symbol>\` and \`graft impact <symbol> [-d N]\` give
precomputed, exact edges — who calls/is called by a symbol, and the full
blast radius — for structural questions, skip ranking and use these directly.
diff --cc src/mcp/tools.ts
index 91a124e1,31833c92..3e3952a3
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@@ -142,12 -128,18 +158,18 @@@ export function callTool
const query = String(args.query ?? '');
if (!query) return { text: 'graft_ask requires a query', isError: true };
const limit = typeof args.limit === 'number' ? args.limit : 5;
- const engine = new Graft();
+ const engine = new Graft({ contextDir: dirOverride });
- const r = engine.ask(root, query, { limit, source: true });
+ const r = engine.ask(root, query, { limit, source: true, full: args.full === true });
return { text: formatAsk(r), isError: false };
}
+ case 'graft_skeleton': {
+ const file = String(args.file ?? '');
+ if (!file) return { text: 'graft_skeleton requires a file', isError: true };
- const r = skeleton(root, file);
++ const r = skeleton(root, file, { contextDir: dirOverride });
+ return { text: formatSkeleton(r), isError: !r.entries.length && !!r.note };
+ }
case 'graft_check': {
- const engine = new Graft();
+ const engine = new Graft({ contextDir: dirOverride });
const r = engine.check(root);
const g = engine.checkGraph(root);
const parts = [formatCheckReport(r)];
diff --cc test/mcp-tools.test.ts
index 05f472a4,3b30a795..6ab6e266
--- a/test/mcp-tools.test.ts
+++ b/test/mcp-tools.test.ts
@@@ -59,22 -47,10 +59,23 @@@ function fileScopeRepo(): string
return d;
}
-test('TOOLS lists all six tools with schemas', () => {
+/** 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
+ * prove it's wired through to `buildRepoMap`. */
+function multiDirRepo(): string {
+ const d = mkdtempSync(join(tmpdir(), 'graft-mcptools-multidir-'));
+ for (const dir of ['aaa', 'bbb', 'ccc', 'ddd', 'eee']) {
+ mkdirSync(join(d, dir), { recursive: true });
+ writeFileSync(join(d, dir, 'x.ts'), `export function ${dir}Fn(): number {\n return 1;\n}\n`);
+ }
+ execFileSync(process.execPath, ['--import', 'tsx', 'src/cli.ts', 'build', d], { stdio: 'pipe' });
+ return d;
+}
+
- test('TOOLS lists all seven tools with schemas', () => {
++test('TOOLS lists all eight tools with schemas', () => {
assert.deepEqual(TOOLS.map((t) => t.name), [
'graft_ask',
+ 'graft_skeleton',
'graft_check',
'graft_blast_radius',
'graft_callers',
@@@ -202,77 -176,12 +203,87 @@@ test('graft_blast_radius: unknown symbo
assert.match(r.text, /check spelling/);
});
+test('graft_grep round-trips a hit on the built fixture, grouped by enclosing symbol', () => {
+ const d = builtRepo();
+ const r = callTool(d, 'graft_grep', { 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', () => {
+ const d = builtRepo();
+ const r = callTool(d, 'graft_grep', { pattern: 'noSuchPatternAnywhere' });
+ assert.equal(r.isError, false);
+ assert.match(r.text, /no hits for "noSuchPatternAnywhere"/);
+ assert.match(r.text, /grep -rn "noSuchPatternAnywhere"/);
+});
+
+test('graft_grep: missing pattern and unbuilt repo are soft errors', () => {
+ const d = builtRepo();
+ const r1 = callTool(d, 'graft_grep', {});
+ assert.equal(r1.isError, true);
+ assert.match(r1.text, /requires a pattern/);
+
+ const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-grep-bare-'));
+ const r2 = callTool(bare, 'graft_grep', { 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', () => {
+ const d = builtRepo();
+ const r = callTool(d, 'graft_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', () => {
+ const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-map-bare-'));
+ const r = callTool(bare, 'graft_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', () => {
+ const d = multiDirRepo();
+
+ const capped = callTool(d, 'graft_map', { max_dirs: 1 });
+ assert.equal(capped.isError, false);
+ assert.match(capped.text, /\+4 more directories not shown/);
+
+ const raised = callTool(d, 'graft_map', { max_dirs: 10 });
+ assert.equal(raised.isError, false);
+ assert.doesNotMatch(raised.text, /more directories? not shown/);
+});
+
+test('callTool honors a dirOverride for a graph built in a non-default dir', () => {
+ const { repo, graphDir } = customDirRepo();
+
+ // With the override pointing at the actual graph location, tools find it.
+ const check = callTool(repo, 'graft_check', {}, graphDir);
+ assert.equal(check.isError, false);
+ assert.match(check.text, /graph check: OK/);
+
+ const callers = callTool(repo, 'graft_callers', { 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 = callTool(repo, 'graft_callers', { 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', () => {
+ const d = builtRepo();
+ const r = callTool(d, 'graft_skeleton', { 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 = callTool(d, 'graft_skeleton', { file: 'src/nope.ts' });
+ assert.equal(miss.isError, true);
+ });