BACK-522 - Resolve MCP project root from client workspace roots (MrLesk#687)

## Summary
The MCP server chose its project root once at startup and only looked at
the client's MCP roots when it had no project of its own (fallback
mode). A server shared across projects, or one started in the main
checkout while the active workspace is a git worktree, therefore kept
writing tasks to whatever directory it launched in (MrLesk#558).

This makes an already-initialized server follow the client workspace as
well, reusing the request-scoped roots discovery that MrLesk#608 added for
fallback mode. On its first request the server asks the client for its
roots and switches to the matching project, then re-checks on every
`roots/list_changed`. If the workspace has no backlog of its own, the
server stays on its launch directory instead of dropping to "init
required". Passing `--cwd` or `BACKLOG_CWD` pins the root and turns
roots discovery off, which is what a deliberately shared server wants.

## Behavior change
An initialized, unpinned server now sends one `roots/list` request on
its first handled request, where before it sent none. If the client's
root matches the launch directory, nothing is re-registered. Clients
that do not advertise the roots capability keep the old `process.cwd()`
behavior. A pinned server sends no roots requests at all.

## Implementation notes
* `src/commands/mcp.ts` marks the root as pinned when it comes from
`--cwd` or `BACKLOG_CWD`, and unpinned when it is only `process.cwd()`.
* `src/mcp/server.ts` adds a `startupHasProject` flag so an initialized
server returns to its own project when the client offers nothing usable,
while a fallback server still reverts to init-required.
* `upgradeToProject`, `downgradeToFallback` and `resolveFromRoots` are
unchanged, as are the root checks from MrLesk#570: each root is checked on its
own, no walking up the tree, one resolution in flight at a time.
* README now documents workspace following and the `--cwd` /
`BACKLOG_CWD` pin.

## Related Tasks
Closes MrLesk#558. Task `backlog/tasks/back-558 -
Resolve-MCP-project-root-from-client-workspace-roots.md` (BACK-558),
acceptance criteria and DoD checked.

## Validation
* `bun test src/test/mcp-workspace-root.test.ts
src/test/mcp-roots-discovery.test.ts` (15 pass): following the client
workspace from an unrelated launch directory, a pin that sends zero
roots requests, a monorepo package kept, the launch project kept when
the workspace has no backlog, the return to the launch project after the
workspace loses its backlog, and the worktree case from MrLesk#558.
* `bunx tsc --noEmit`
* `bun run check .`

---------

Co-authored-by: Alex Gavrilescu <leskcorp@gmail.com>

Author: kuwork

README.en.md

@@ -267,7 +267,7 @@ You can run `backlog init` (even if you already initialized Backlog.md) and choo
 
 </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
 
@@ -285,7 +285,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.
 If your IDE supports custom args but not env vars, you can also use `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]`.
 
 > [!IMPORTANT]

README.md

@@ -267,7 +267,7 @@ CLI 指令是默认的 AI 接入方式。如果您明确偏好 MCP 连接器，B
 
 </details>
 
-处处统一使用 `backlog` 作为服务器名称 —— MCP 服务器会自动检测当前目录是否已初始化，并在需要时回退到 `backlog://init-required`。
+处处统一使用 `backlog` 作为服务器名称。服务器会从客户端的 MCP roots 中查找当前项目，并在切换工作区或 worktree 时重新解析。找到项目前，它会提供 `backlog://init-required`。一个用户级服务器即可覆盖所有仓库。
 
 ### 手动配置
 
@@ -285,7 +285,7 @@ CLI 指令是默认的 AI 接入方式。如果您明确偏好 MCP 连接器，B
 }
 ```
 
-如果您的 IDE 无法为 MCP 服务器设置进程工作目录，如上所示设置 `BACKLOG_CWD`。
+设置 `BACKLOG_CWD` 可将服务器固定到单个项目并停止工作区跟随。当你始终想定位同一个 backlog，或客户端无法上报 MCP roots 时使用它。
 如果您的 IDE 支持自定义参数但不支持环境变量，您也可以使用 `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]`。
 
 > [!IMPORTANT]

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

@@ -0,0 +1,59 @@
+---
+id: BACK-522
+title: Resolve MCP project root from client workspace roots
+status: Done
+assignee:
+  - '@ycaptain'
+created_date: '2026-06-14 06:58'
+updated_date: '2026-06-15 17:04'
+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();