BACK-558 - Resolve MCP project root from client workspace roots

The MCP server froze its project root at startup and only consulted client MCP
roots in fallback (uninitialized) mode, so a shared/user-scope server -- or one
launched in the main checkout while working in a git worktree -- wrote tasks to
the wrong backlog directory.

Extend the request-scoped roots discovery from #608 (BACK-434) to the normal
(initialized) startup path: unless pinned, the server now follows the client's
workspace roots and re-resolves on roots/list_changed. A startupHasProject flag
makes a launch-directory project return to itself when the client workspace has
no backlog (rather than dropping to init-required); a fallback baseline still
reverts to init-required. An explicit --cwd/BACKLOG_CWD pin opts out of roots
entirely. The existing upgradeToProject/downgradeToFallback/resolveFromRoots and
the #570 constraints are kept intact.

Behavior change: the normal/initialized path now issues one roots/list request to
follow the client workspace (#608 issued none in normal mode); a pin opts out.

Closes #558.

Author: ycaptain

README.md

@@ -194,7 +194,7 @@ You can run `backlog init` (even if you already initialized Backlog.md) to set u
 
 </details>
 
-Use the shared `backlog` server name everywhere – the MCP server auto-detects whether the current directory is initialized and falls back to `backlog://init-required` when needed.
+Use the shared `backlog` server name everywhere. The server finds the active project from your client's MCP roots, and re-resolves when you switch workspace or worktree. Until it finds one, it serves `backlog://init-required`. A single user-scope server covers every repo.
 
 ### Manual config
 
@@ -212,7 +212,7 @@ Use the shared `backlog` server name everywhere – the MCP server auto-detects
 }
 ```
 
-If your IDE can't set the process working directory for MCP servers, set `BACKLOG_CWD` as shown above.
+Set `BACKLOG_CWD` to pin the server to one project and stop workspace following. Use it to always target the same backlog, or when your client can't report MCP roots. Roots-capable clients like Claude Code can drop the `env` block.
 If your IDE supports custom args but not env vars, you can also use `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]`.
 
 > [!IMPORTANT]

backlog/tasks/back-558 - Resolve-MCP-project-root-from-client-workspace-roots.md

@@ -0,0 +1,58 @@
+---
+id: BACK-558
+title: Resolve MCP project root from client workspace roots
+status: In Progress
+assignee:
+  - "@ycaptain"
+created_date: "2026-06-14 06:58"
+labels:
+  - mcp
+  - bug
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+
+The MCP server resolves its project root once at startup and only consults MCP roots in fallback mode, so a shared/user-scope server (or one launched in the main checkout while working in a git worktree) writes tasks to the wrong backlog directory. See #558. Extend the request-scoped MCP roots discovery introduced in #608 (BACK-434) to the normal (initialized) startup path so the server follows the client's workspace roots, while preserving explicit pins (--cwd/BACKLOG_CWD) and the behavior of clients without the roots capability.
+
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+
+<!-- AC:BEGIN -->
+
+- [x] #1 An unpinned shared/user-scope server resolves the project from the client's workspace roots instead of a frozen startup directory, and re-resolves on roots/list_changed.
+- [x] #2 An explicit --cwd/BACKLOG_CWD pin keeps a fixed root and never queries client roots.
+- [x] #3 When the client workspace has no backlog project (empty/unusable roots, or a folder without a backlog), an unpinned launch-directory project is kept rather than dropped to init-required; pin with --cwd/BACKLOG_CWD to target a fixed global backlog.
+- [x] #4 Clients without the roots capability keep the previous process.cwd() behavior, and the constraints from #570 are preserved (each root checked directly, multi-root selects the first advertised root that has a backlog config, single-flight).
+- [x] #5 Tests cover the git-worktree case from #558, the shared-server case, pin precedence, the nested monorepo case, and the no-roots fallback; the full suite passes.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+
+1. Thread a pinned flag from src/commands/mcp.ts into createMcpServer, derived from whether the directory came from --cwd/BACKLOG_CWD or process.cwd().
+2. Enable the existing request-scoped roots discovery on the normal (initialized) startup path too — gated by pinned — reusing upgradeToProject/downgradeToFallback/resolveFromRoots from #608 rather than rewriting the resolver.
+3. Track startupHasProject so a normal baseline keeps its project when the client workspace has no backlog (only a fallback/init-required baseline downgrades); make upgradeToProject's no-op short-circuit cover the normal baseline.
+4. Keep the #570 constraints (each root checked directly, multi-root first-with-config, single-flight).
+5. Cover cases in src/test/mcp-workspace-root.test.ts; update mcp-roots-discovery.test.ts for the confirm-once behavior; update the README MCP section.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+
+Minimal patch on top of #608's request-scoped roots discovery — upgradeToProject/downgradeToFallback/resolveFromRoots are kept intact rather than rewriting the resolver.
+
+- src/mcp/server.ts: the normal (initialized) startup path now also calls enableRootsDiscovery unless pinned; a startupHasProject flag makes a normal baseline keep its project when the client workspace has no backlog (only a fallback baseline reverts to init-required); upgradeToProject's no-op short-circuit covers the normal baseline so a client root equal to the launch dir does not re-register.
+- src/commands/mcp.ts threads pinned from --cwd/BACKLOG_CWD vs process.cwd().
+- Scope: this PR intentionally does NOT drop an unrelated launch project (e.g. a global ~/.backlog) or add monorepo-nesting rules; those were left out to keep it a minimal bugfix within the existing architecture. Pin with --cwd/BACKLOG_CWD to fix a global backlog.
+- Behavior change (reviewer note): the normal/initialized path now issues one roots/list request to follow the client workspace (#608 issued none in normal mode); a pin opts out entirely.
+
+Full suite passes; bun run check . and bunx tsc --noEmit clean.
+
+<!-- SECTION:NOTES:END -->

src/commands/mcp.ts

@@ -38,7 +38,10 @@ function registerStartCommand(mcpCmd: Command): void {
 			try {
 				const runtimeCwd = await resolveRuntimeCwd({ cwd: options.cwd });
 				const projectRoot = (await findBacklogRoot(runtimeCwd.cwd)) ?? runtimeCwd.cwd;
-				const server = await createMcpServer(projectRoot, { debug: options.debug });
+				// An explicit --cwd/BACKLOG_CWD pins the root; an inferred process.cwd()
+				// lets the server follow the client's workspace roots instead.
+				const pinned = runtimeCwd.source !== "process";
+				const server = await createMcpServer(projectRoot, { debug: options.debug, pinned });
 
 				await server.connect();
 				await server.start();

src/mcp/server.ts

@@ -57,6 +57,8 @@ const INSTRUCTIONS =
 
 type ServerInitOptions = {
 	debug?: boolean;
+	/** When true (from --cwd/BACKLOG_CWD), the root is fixed and client roots are never consulted. */
+	pinned?: boolean;
 };
 
 type ServerRequestExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
@@ -81,6 +83,9 @@ export class McpServer extends Core {
 	/** True when the server has been upgraded from fallback to a real project. */
 	private upgraded = false;
 
+	/** True when the launch directory was itself an initialized project (vs fallback). */
+	private startupHasProject = false;
+
 	private readonly tools = new Map<string, McpToolHandler>();
 	private readonly resources = new Map<string, McpResourceHandler>();
 	private readonly prompts = new Map<string, McpPromptHandler>();
@@ -109,16 +114,20 @@ export class McpServer extends Core {
 	}
 
 	/**
-	 * Enable roots-based project discovery for fallback mode.
+	 * Enable roots-based project discovery so the server follows the client
+	 * workspace. Used from both fallback mode and a normal (initialized) startup;
+	 * pass `startupHasProject` for the latter so an unusable client workspace
+	 * returns to the launch-directory project instead of init-required.
 	 *
 	 * The first request-scoped handler invocation can query MCP roots to look
 	 * for a valid backlog project. If found, the server reinitializes the Core,
 	 * registers the full toolset, and notifies the client. Subsequent requests
 	 * reuse the cached resolution until the client reports roots changes.
 	 */
-	enableRootsDiscovery(options?: { debug?: boolean }): void {
+	enableRootsDiscovery(options?: { debug?: boolean; startupHasProject?: boolean }): void {
 		this.rootsDiscoveryEnabled = true;
-		this.rootsDiscoveryOptions = options ?? {};
+		this.rootsDiscoveryOptions = { debug: options?.debug };
+		this.startupHasProject = options?.startupHasProject ?? false;
 		this.rootsResolutionDirty = true;
 	}
 
@@ -177,7 +186,11 @@ export class McpServer extends Core {
 				}
 			}
 
-			if (this.upgraded) {
+			// No usable client root. A launch-directory (normal) baseline returns to its
+			// own project rather than a now-stale one; a fallback baseline reverts to init-required.
+			if (this.startupHasProject) {
+				await this.upgradeToProject(this.initialProjectRoot, options);
+			} else if (this.upgraded) {
 				await this.downgradeToFallback(options);
 			}
 
@@ -220,7 +233,7 @@ export class McpServer extends Core {
 	 * toolset, replacing fallback-mode registrations.
 	 */
 	private async upgradeToProject(projectRoot: string, options?: { debug?: boolean }): Promise<boolean> {
-		if (this.upgraded && this.filesystem.rootDir === projectRoot) {
+		if (this.filesystem.rootDir === projectRoot && (this.upgraded || this.startupHasProject)) {
 			this.log(`MCP roots still resolve to current project: ${projectRoot}`, options);
 			return true;
 		}
@@ -505,7 +518,12 @@ export async function createMcpServer(projectRoot: string, options: ServerInitOp
 	// and enable roots discovery so the server can find the project via MCP roots
 	if (!config) {
 		registerInitRequiredResource(server, projectRoot);
-		server.enableRootsDiscovery({ debug: options.debug });
+		if (!options.pinned) {
+			server.enableRootsDiscovery({
+				debug: options.debug,
+				startupHasProject: false,
+			});
+		}
 
 		if (options.debug) {
 			console.error("MCP server initialised in fallback mode (roots discovery enabled).");
@@ -522,6 +540,15 @@ export async function createMcpServer(projectRoot: string, options: ServerInitOp
 	registerDefinitionOfDoneTools(server);
 	registerDocumentTools(server, config);
 
+	// Follow the client workspace roots so a server launched in the main checkout
+	// (or a shared/user-scope server) targets the active project, not a frozen one.
+	if (!options.pinned) {
+		server.enableRootsDiscovery({
+			debug: options.debug,
+			startupHasProject: true,
+		});
+	}
+
 	if (options.debug) {
 		console.error("MCP server initialised (stdio transport only).");
 	}

src/test/mcp-roots-discovery.test.ts

@@ -246,7 +246,7 @@ describe("MCP roots discovery", () => {
 		}
 	});
 
-	it("normal mode does not issue roots/list requests", async () => {
+	it("confirms an initialized launch directory against client roots exactly once", async () => {
 		const { projectRoot } = await setupDirs();
 
 		const server = await createMcpServer(projectRoot);
@@ -256,6 +256,30 @@ describe("MCP roots discovery", () => {
 		try {
 			const tools = await client.listTools();
 			expect(tools.tools.map((tool) => tool.name)).toContain("task_create");
+			expect(server.filesystem.rootDir).toBe(projectRoot);
+			expect(getRootsRequestCount()).toBe(1);
+
+			// Matching roots keep the same project and the resolution is cached.
+			await client.listResources();
+			expect(server.filesystem.rootDir).toBe(projectRoot);
+			expect(getRootsRequestCount()).toBe(1);
+		} finally {
+			await client.close();
+			await server.stop();
+		}
+	});
+
+	it("pinned server never issues roots/list requests", async () => {
+		const { projectRoot, secondProjectRoot } = await setupDirs();
+
+		const server = await createMcpServer(projectRoot, { pinned: true });
+		const rootsRef = { current: [pathToFileURL(secondProjectRoot).toString()] };
+		const { client, getRootsRequestCount } = await connectRootsClient(server, rootsRef);
+
+		try {
+			const tools = await client.listTools();
+			expect(tools.tools.map((tool) => tool.name)).toContain("task_create");
+			expect(server.filesystem.rootDir).toBe(projectRoot);
 			expect(getRootsRequestCount()).toBe(0);
 		} finally {
 			await client.close();