Skip to content

Commit 1cd162a

Browse files
colbymchenryclaude
colbymchenry
and
claude
authored
fix(mcp): auto-detect project via roots/list when no rootUri (colbymchenry#196) (colbymchenry#214)
MCP tools failed with "CodeGraph not initialized" when a client launched the server outside the project and sent no rootUri/workspaceFolders — the server fell back to its own cwd, missed the project's .codegraph/, and returned a misleading "run codegraph init" error on every call. The only workaround was passing projectPath by hand to each tool. When no explicit path is given, the server now asks the client for its workspace root via the standard MCP roots/list request (gated on the client advertising the roots capability) before falling back to cwd. This required teaching the stdio transport to send server->client requests and match their responses by id (previously responses were dropped as invalid). When a project still can't be resolved, the error now names the directory it searched and tells the user to pass projectPath or add --path to the MCP config, instead of pointing at a re-init they don't need. Reported-by: @zhangyu1197 Closes colbymchenry#196 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent cf7db7c commit 1cd162a

5 files changed

Lines changed: 388 additions & 20 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,23 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
5757
Thanks to [@essopsp](https://github.com/essopsp) for the repro.
5858

5959
### Fixed
60+
- **MCP**: tools no longer fail with "CodeGraph not initialized" when the index
61+
actually exists. This hit clients that launch the MCP server from a directory
62+
other than your project and don't report a workspace root in `initialize`
63+
(some IDE/JetBrains-family integrations) — the server fell back to its own
64+
working directory, missed the project's `.codegraph/`, and returned the
65+
misleading "Run 'codegraph init' first" on every call. The only workaround
66+
was passing `projectPath` to each tool by hand. Now, when no project path is
67+
supplied, the server asks the client for its workspace root via the standard
68+
MCP `roots/list` request (when the client advertises the `roots` capability)
69+
before falling back to the working directory — so detection just works for
70+
spec-compliant clients. When it still can't resolve a project, the error is
71+
now actionable: it names the directory it searched and tells you to pass
72+
`projectPath` or add `--path /abs/project` to the server's MCP config args,
73+
instead of pointing you at a re-init you don't need. Closes
74+
[#196](https://github.com/colbymchenry/codegraph/issues/196). Thanks to
75+
[@zhangyu1197](https://github.com/zhangyu1197) for the report and the
76+
`projectPath` workaround.
6077
- **MCP**: the server no longer hangs on startup under WSL2 when the project
6178
lives on an NTFS `/mnt/*` mount. Setting up the recursive file watcher
6279
there took tens of seconds — every directory read crosses the Windows/9p

‎__tests__/mcp-roots.test.ts‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
/**
2+
* MCP project-resolution regression tests (issue #196).
3+
*
4+
* When an MCP client launches the server outside the project directory AND
5+
* doesn't pass a `rootUri`/`workspaceFolders` in `initialize`, the server used
6+
* to fall straight back to `process.cwd()` — which for many IDE clients is the
7+
* wrong directory. Every tool call without an explicit `projectPath` then
8+
* failed with a misleading "CodeGraph not initialized. Run 'codegraph init'."
9+
*
10+
* The fix: when no explicit path is provided, the server asks the client for
11+
* its workspace root via the spec-blessed `roots/list` request (if the client
12+
* advertised the `roots` capability), and only falls back to cwd otherwise.
13+
* When it still can't resolve, the error now says exactly how to fix it.
14+
*
15+
* These tests drive the real stdio transport via a spawned subprocess — no
16+
* mocking — so they also exercise the new bidirectional request/response path.
17+
*/
18+
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
19+
import { spawn, ChildProcessWithoutNullStreams } from 'child_process';
20+
import * as fs from 'fs';
21+
import * as path from 'path';
22+
import * as os from 'os';
23+
import { CodeGraph } from '../src';
24+
25+
const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
26+
27+
function spawnServer(cwd: string): ChildProcessWithoutNullStreams {
28+
// --no-watch keeps the test deterministic and avoids watcher startup noise.
29+
return spawn(process.execPath, [BIN, 'serve', '--mcp', '--no-watch'], {
30+
cwd,
31+
stdio: ['pipe', 'pipe', 'pipe'],
32+
}) as ChildProcessWithoutNullStreams;
33+
}
34+
35+
/** Parse every JSON-RPC message the server writes to stdout into an array. */
36+
function collectMessages(child: ChildProcessWithoutNullStreams): Array<Record<string, any>> {
37+
const messages: Array<Record<string, any>> = [];
38+
let buf = '';
39+
child.stdout.on('data', (chunk) => {
40+
buf += chunk.toString('utf8');
41+
let idx;
42+
while ((idx = buf.indexOf('\n')) !== -1) {
43+
const line = buf.slice(0, idx).trim();
44+
buf = buf.slice(idx + 1);
45+
if (!line) continue;
46+
try { messages.push(JSON.parse(line)); } catch { /* ignore non-JSON */ }
47+
}
48+
});
49+
return messages;
50+
}
51+
52+
function waitForMessage(
53+
messages: ReadonlyArray<Record<string, any>>,
54+
predicate: (m: Record<string, any>) => boolean,
55+
timeoutMs: number,
56+
): Promise<Record<string, any>> {
57+
return new Promise((resolve, reject) => {
58+
const started = Date.now();
59+
const tick = () => {
60+
const hit = messages.find(predicate);
61+
if (hit) return resolve(hit);
62+
if (Date.now() - started > timeoutMs) {
63+
return reject(new Error(`Timed out. Messages so far: ${JSON.stringify(messages)}`));
64+
}
65+
setTimeout(tick, 20);
66+
};
67+
tick();
68+
});
69+
}
70+
71+
function send(child: ChildProcessWithoutNullStreams, msg: object): void {
72+
child.stdin.write(JSON.stringify(msg) + '\n');
73+
}
74+
75+
const CLIENT_INFO = { name: 'test', version: '0.0.0' };
76+
77+
describe('MCP project resolution via roots/list (issue #196)', () => {
78+
let cwdDir: string; // where the server is launched — has NO .codegraph
79+
let projectDir: string; // the real indexed project the client reports
80+
let child: ChildProcessWithoutNullStreams | null = null;
81+
82+
beforeEach(() => {
83+
cwdDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-mcp-cwd-'));
84+
projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-mcp-proj-'));
85+
});
86+
87+
afterEach(() => {
88+
if (child && !child.killed) {
89+
child.kill('SIGKILL');
90+
child = null;
91+
}
92+
fs.rmSync(cwdDir, { recursive: true, force: true });
93+
fs.rmSync(projectDir, { recursive: true, force: true });
94+
});
95+
96+
it('resolves the project from the client roots/list when no rootUri is sent', async () => {
97+
const cg = await CodeGraph.init(projectDir);
98+
cg.close();
99+
100+
child = spawnServer(cwdDir);
101+
const messages = collectMessages(child);
102+
103+
// Advertise the roots capability but pass NO rootUri/workspaceFolders.
104+
send(child, {
105+
jsonrpc: '2.0', id: 0, method: 'initialize',
106+
params: { protocolVersion: '2025-11-25', capabilities: { roots: {} }, clientInfo: CLIENT_INFO },
107+
});
108+
await waitForMessage(messages, (m) => m.id === 0 && !!m.result, 5000);
109+
send(child, { jsonrpc: '2.0', method: 'notifications/initialized' });
110+
111+
// First tool call (no projectPath) drives the server to ask us for roots.
112+
send(child, { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'codegraph_status', arguments: {} } });
113+
114+
const rootsReq = await waitForMessage(messages, (m) => m.method === 'roots/list', 5000);
115+
expect(typeof rootsReq.id).toBe('string'); // server-initiated id
116+
send(child, {
117+
jsonrpc: '2.0', id: rootsReq.id,
118+
result: { roots: [{ uri: `file://${projectDir}`, name: 'proj' }] },
119+
});
120+
121+
// The status call now succeeds against the resolved project.
122+
const resp = await waitForMessage(messages, (m) => m.id === 1, 8000);
123+
const text = resp.result.content[0].text as string;
124+
expect(text).toContain('CodeGraph Status');
125+
expect(text).not.toContain('No CodeGraph project is loaded');
126+
}, 20000);
127+
128+
it('returns an actionable error when there is no rootUri and no roots capability', async () => {
129+
child = spawnServer(cwdDir);
130+
const messages = collectMessages(child);
131+
132+
send(child, {
133+
jsonrpc: '2.0', id: 0, method: 'initialize',
134+
params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: CLIENT_INFO },
135+
});
136+
await waitForMessage(messages, (m) => m.id === 0 && !!m.result, 5000);
137+
send(child, { jsonrpc: '2.0', method: 'notifications/initialized' });
138+
139+
send(child, { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'codegraph_status', arguments: {} } });
140+
const resp = await waitForMessage(messages, (m) => m.id === 1, 8000);
141+
const text = resp.result.content[0].text as string;
142+
143+
expect(text).toContain('No CodeGraph project is loaded');
144+
expect(text).toContain('projectPath');
145+
expect(text).toContain('--path');
146+
// Names the directory it actually searched (the wrong cwd) so the user can
147+
// see why detection missed. basename survives any symlink realpath-ing.
148+
expect(text).toContain(path.basename(cwdDir));
149+
// It must not have hung waiting on roots/list — the client never offered it.
150+
expect(messages.some((m) => m.method === 'roots/list')).toBe(false);
151+
}, 20000);
152+
153+
it('honors an explicit rootUri without asking the client for roots', async () => {
154+
const cg = await CodeGraph.init(projectDir);
155+
cg.close();
156+
157+
child = spawnServer(cwdDir);
158+
const messages = collectMessages(child);
159+
160+
send(child, {
161+
jsonrpc: '2.0', id: 0, method: 'initialize',
162+
params: {
163+
protocolVersion: '2025-11-25',
164+
capabilities: { roots: {} },
165+
clientInfo: CLIENT_INFO,
166+
rootUri: `file://${projectDir}`,
167+
},
168+
});
169+
await waitForMessage(messages, (m) => m.id === 0 && !!m.result, 5000);
170+
send(child, { jsonrpc: '2.0', method: 'notifications/initialized' });
171+
172+
send(child, { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'codegraph_status', arguments: {} } });
173+
const resp = await waitForMessage(messages, (m) => m.id === 1, 8000);
174+
const text = resp.result.content[0].text as string;
175+
176+
expect(text).toContain('CodeGraph Status');
177+
// rootUri is a stronger signal than roots — we never needed to ask.
178+
expect(messages.some((m) => m.method === 'roots/list')).toBe(false);
179+
}, 20000);
180+
});

‎src/mcp/index.ts‎

Lines changed: 101 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,26 @@ const SERVER_INFO = {
5454
*/
5555
const PROTOCOL_VERSION = '2024-11-05';
5656

57+
/**
58+
* How long to wait for the client's `roots/list` response before giving up
59+
* and falling back to the process cwd.
60+
*/
61+
const ROOTS_LIST_TIMEOUT_MS = 5000;
62+
63+
/**
64+
* Extract the first usable filesystem path from a `roots/list` result.
65+
* Shape per MCP spec: `{ roots: [{ uri: "file:///path", name?: string }] }`.
66+
* Returns null if the result is empty or malformed.
67+
*/
68+
function firstRootPath(result: unknown): string | null {
69+
if (!result || typeof result !== 'object') return null;
70+
const roots = (result as { roots?: unknown }).roots;
71+
if (!Array.isArray(roots) || roots.length === 0) return null;
72+
const first = roots[0] as { uri?: unknown };
73+
if (typeof first?.uri !== 'string') return null;
74+
return fileUriToPath(first.uri);
75+
}
76+
5777
/**
5878
* MCP Server for CodeGraph
5979
*
@@ -68,6 +88,13 @@ export class MCPServer {
6888
// In-flight background init kicked off from handleInitialize. Tracked so the
6989
// sync retry path doesn't race against it (double-opening the SQLite file).
7090
private initPromise: Promise<void> | null = null;
91+
// Whether the client advertised the MCP `roots` capability during initialize.
92+
// If so, and no explicit project path was given, we ask it for the workspace
93+
// root via roots/list rather than guessing from the (often wrong) cwd.
94+
private clientSupportsRoots = false;
95+
// Guards the one-shot deferred resolution (roots/list or cwd) so we don't
96+
// re-issue roots/list on every tool call.
97+
private rootsAttempted = false;
7198

7299
constructor(projectPath?: string) {
73100
this.projectPath = projectPath || null;
@@ -108,6 +135,9 @@ export class MCPServer {
108135
* are still possible.
109136
*/
110137
private async tryInitializeDefault(projectPath: string): Promise<void> {
138+
// Record where we searched so a later "not initialized" error can name it.
139+
this.toolHandler.setDefaultProjectHint(projectPath);
140+
111141
// Walk up parent directories to find nearest .codegraph/
112142
const resolvedRoot = findNearestCodeGraphRoot(projectPath);
113143

@@ -146,10 +176,28 @@ export class MCPServer {
146176

147177
// Already initialized successfully
148178
if (this.toolHandler.hasDefaultCodeGraph()) return;
149-
// No project path to retry with
150-
if (!this.projectPath) return;
151179

152-
const resolvedRoot = findNearestCodeGraphRoot(this.projectPath);
180+
// No explicit path was given at initialize. Resolve it now, exactly once:
181+
// ask the client via roots/list (if it advertised roots), else use cwd.
182+
// Deferring to here lets a roots answer override the wrong cwd, and the
183+
// one-shot guard means we never re-issue roots/list per tool call.
184+
if (!this.projectPath && !this.rootsAttempted) {
185+
this.rootsAttempted = true;
186+
this.initPromise = (
187+
this.clientSupportsRoots
188+
? this.initFromRoots()
189+
: this.tryInitializeDefault(process.cwd())
190+
).finally(() => { this.initPromise = null; });
191+
try { await this.initPromise; } catch { /* fall through to last-resort below */ }
192+
if (this.toolHandler.hasDefaultCodeGraph()) return;
193+
}
194+
195+
// Last resort: re-walk from the best candidate we have. Picks up projects
196+
// initialized after the server started, and covers clients that sent no
197+
// usable initialize signal at all.
198+
const candidate = this.projectPath ?? process.cwd();
199+
this.toolHandler.setDefaultProjectHint(candidate);
200+
const resolvedRoot = findNearestCodeGraphRoot(candidate);
153201
if (!resolvedRoot) return;
154202

155203
try {
@@ -167,6 +215,28 @@ export class MCPServer {
167215
}
168216
}
169217

218+
/**
219+
* Resolve the project root via the MCP `roots/list` request and initialize
220+
* from the first root the client reports. Falls back to the process cwd if
221+
* the client returns no usable root or doesn't answer in time. See issue #196.
222+
*/
223+
private async initFromRoots(): Promise<void> {
224+
let target = process.cwd();
225+
try {
226+
const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
227+
const rootPath = firstRootPath(result);
228+
if (rootPath) {
229+
target = rootPath;
230+
} else {
231+
process.stderr.write('[CodeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
232+
}
233+
} catch (err) {
234+
const msg = err instanceof Error ? err.message : String(err);
235+
process.stderr.write(`[CodeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
236+
}
237+
await this.tryInitializeDefault(target);
238+
}
239+
170240
/**
171241
* Start file watching on the active CodeGraph instance.
172242
* Logs sync activity to stderr for diagnostics.
@@ -279,20 +349,25 @@ export class MCPServer {
279349
const params = request.params as {
280350
rootUri?: string;
281351
workspaceFolders?: Array<{ uri: string; name: string }>;
352+
capabilities?: { roots?: unknown };
282353
} | undefined;
283354

284-
// Extract project path from rootUri or workspaceFolders
285-
let projectPath = this.projectPath;
355+
// Does the client support the MCP `roots` protocol? If so, and we have no
356+
// explicit path, we ask it for the workspace root after the handshake
357+
// instead of falling back to the (frequently wrong) cwd. See issue #196.
358+
this.clientSupportsRoots = !!params?.capabilities?.roots;
286359

360+
// Explicit project signal, strongest first: a client-provided rootUri /
361+
// workspaceFolders (LSP-style, non-standard but some clients send it), else
362+
// the --path the server was launched with. cwd is NOT used here — we defer
363+
// it so a roots/list answer can win over it.
364+
let explicitPath: string | null = null;
287365
if (params?.rootUri) {
288-
projectPath = fileUriToPath(params.rootUri);
366+
explicitPath = fileUriToPath(params.rootUri);
289367
} else if (params?.workspaceFolders?.[0]?.uri) {
290-
projectPath = fileUriToPath(params.workspaceFolders[0].uri);
291-
}
292-
293-
// Fall back to current working directory if no path provided
294-
if (!projectPath) {
295-
projectPath = process.cwd();
368+
explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
369+
} else if (this.projectPath) {
370+
explicitPath = this.projectPath;
296371
}
297372

298373
// Respond to the handshake BEFORE doing any heavy initialization. Loading
@@ -315,13 +390,20 @@ export class MCPServer {
315390
instructions: SERVER_INSTRUCTIONS,
316391
});
317392

318-
// Kick off the default-project init in the background. Tool calls that
319-
// arrive before it finishes will see the "not initialized yet" path and
320-
// fall through to `retryInitIfNeeded`, which now waits for this promise
321-
// rather than racing against it with a second open.
322-
this.initPromise = this.tryInitializeDefault(projectPath).finally(() => {
323-
this.initPromise = null;
324-
});
393+
// If we know the project dir, kick off init in the background now. Tool
394+
// calls that arrive before it finishes fall through to `retryInitIfNeeded`,
395+
// which waits for this promise rather than racing it with a second open.
396+
//
397+
// If we DON'T know it (no rootUri, no --path), defer: the first tool call
398+
// resolves it via roots/list (when the client supports roots) or cwd. This
399+
// is the fix for issue #196 — clients that launch the server outside the
400+
// project and don't pass a rootUri previously got a misleading "not
401+
// initialized" error on every call.
402+
if (explicitPath) {
403+
this.initPromise = this.tryInitializeDefault(explicitPath).finally(() => {
404+
this.initPromise = null;
405+
});
406+
}
325407
}
326408

327409
/**

0 commit comments

Comments
 (0)