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

The MCP server froze its project root at startup and only consulted MCP
roots in fallback 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.

Unify startup and fallback resolution into one request-scoped resolver:
a --cwd/BACKLOG_CWD pin wins; otherwise client workspace roots are
authoritative and re-resolved on roots/list_changed; a launch-directory
project is kept only when nested inside an advertised root; clients
without the roots capability keep process.cwd() behavior.

Closes #558

Author: ycaptain

README.md

@@ -7,7 +7,6 @@
 
 ![Backlog demo GIF using: backlog board](./.github/backlog-v1.40.gif)
 
-
 ---
 
 > **Backlog.md** turns any folder with a Git repo into a **self‑contained project board**
@@ -16,27 +15,26 @@
 
 ## Features
 
-* 📝 **Markdown-native tasks** -- manage every issue as a plain `.md` file
-
-* 🤖 **AI-Ready** -- Works with Claude Code, Gemini CLI, Codex, Kiro & any other MCP or CLI compatible AI assistants
+- 📝 **Markdown-native tasks** -- manage every issue as a plain `.md` file
 
-* 📊 **Instant terminal Kanban** -- `backlog board` paints a live board in your shell
+- 🤖 **AI-Ready** -- Works with Claude Code, Gemini CLI, Codex, Kiro & any other MCP or CLI compatible AI assistants
 
-* 🌐 **Modern web interface** -- `backlog browser` launches a sleek web UI for visual task management
+- 📊 **Instant terminal Kanban** -- `backlog board` paints a live board in your shell
 
-* 🔍 **Powerful search** -- fuzzy search across tasks, docs & decisions with `backlog search`
+- 🌐 **Modern web interface** -- `backlog browser` launches a sleek web UI for visual task management
 
-* 📋 **Rich query commands** -- view, list, filter, or archive tasks with ease
-* ✅ **Definition of Done defaults** -- add a reusable checklist to every new task
+- 🔍 **Powerful search** -- fuzzy search across tasks, docs & decisions with `backlog search`
 
-* 📤 **Board export** -- `backlog board export` creates shareable markdown reports
+- 📋 **Rich query commands** -- view, list, filter, or archive tasks with ease
+- ✅ **Definition of Done defaults** -- add a reusable checklist to every new task
 
-* 🔒 **100 % private & offline** -- backlog lives entirely inside your repo and you can manage everything locally
+- 📤 **Board export** -- `backlog board export` creates shareable markdown reports
 
-* 💻 **Cross-platform** -- runs on macOS, Linux, and Windows
+- 🔒 **100 % private & offline** -- backlog lives entirely inside your repo and you can manage everything locally
 
-* 🆓 **MIT-licensed & open-source** -- free for personal or commercial use
+- 💻 **Cross-platform** -- runs on macOS, Linux, and Windows
 
+- 🆓 **MIT-licensed & open-source** -- free for personal or commercial use
 
 ---
 
@@ -56,6 +54,7 @@ backlog init "Personal Planning" --no-git
 ```
 
 The init wizard will ask how you want to connect AI tools:
+
 - **MCP connector** (recommended) — auto-configures Claude Code, Codex, Gemini CLI, Kiro or Cursor and adds workflow instructions for your agents.
 - **CLI commands** — creates instruction files (CLAUDE.md, AGENTS.md, etc.) so agents use Backlog via CLI.
 - **Skip** — no AI setup; use Backlog.md purely as a task manager.
@@ -72,6 +71,7 @@ After running `backlog init` and choosing the MCP or CLI integration, work in th
 **Step 1 — Describe your idea.** Tell the agent what you want to build and ask it to split the work into small tasks with clear descriptions and acceptance criteria.
 
 **🤖 Ask your AI Agent:**
+
 > I want to add a search feature to the web view that searches tasks, docs, and decisions. Please decompose this into small Backlog.md tasks.
 
 > [!NOTE]
@@ -82,6 +82,7 @@ After running `backlog init` and choosing the MCP or CLI integration, work in th
 **Step 3 — Plan before coding.** Ask the agent to research and write an implementation plan in the task. Do this right before implementation so the plan reflects the current state of the codebase.
 
 **🤖 Ask your AI Agent:**
+
 > Work on BACK-10 only. Research the codebase and write an implementation plan in the task. Wait for my approval before coding.
 
 > [!NOTE]
@@ -137,6 +138,7 @@ backlog browser --no-open
 ```
 
 **Features:**
+
 - Interactive Kanban board with drag-and-drop
 - Task creation and editing with rich forms
 - Interactive acceptance criteria editor with checklists
@@ -161,43 +163,56 @@ You can run `backlog init` (even if you already initialized Backlog.md) to set u
 <details>
   <summary><strong>Claude Code</strong></summary>
 
-  ```bash
-  claude mcp add backlog --scope user -- backlog mcp start
-  ```
+```bash
+claude mcp add backlog --scope user -- backlog mcp start
+```
 
 </details>
 
 <details>
   <summary><strong>Codex</strong></summary>
 
-  ```bash
-  codex mcp add backlog -- backlog mcp start
-  ```
+```bash
+codex mcp add backlog -- backlog mcp start
+```
 
 </details>
 
 <details>
   <summary><strong>Gemini CLI</strong></summary>
 
-  ```bash
-  gemini mcp add backlog -s user backlog mcp start
-  ```
+```bash
+gemini mcp add backlog -s user backlog mcp start
+```
 
 </details>
 
 <details>
   <summary><strong>Kiro</strong></summary>
 
-  ```bash
-  kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start
-  ```
+```bash
+kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start
+```
 
 </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 MCP server follows your editor's active workspace: it reads the client's MCP roots to locate the project, re-resolves when you switch workspace or git worktree, and falls back to `backlog://init-required` when the workspace has no backlog project yet. A single user-scope server therefore works across all your projects.
 
 ### Manual config
 
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "backlog",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+Pinning to one project: set `BACKLOG_CWD` (or pass `--cwd`) to fix the server on a single backlog and turn off workspace following. This is useful when you want every session to target the same backlog (for example one global backlog), or when your client does not advertise MCP roots and cannot set the process working directory.
+
 ```json
 {
   "mcpServers": {
@@ -212,15 +227,13 @@ 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.
-If your IDE supports custom args but not env vars, you can also use `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]`.
+If your client supports custom args but not env vars, use `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]` instead.
 
 > [!IMPORTANT]
 > When adding the MCP server manually, you should add some extra instructions in your CLAUDE.md/AGENTS.md files to inform the agent about Backlog.md.
 > This step is not required when using `backlog init` as it adds these instructions automatically.
 > Backlog.md's instructions for agents are available at [`/src/guidelines/mcp/agent-nudge.md`](/src/guidelines/mcp/agent-nudge.md).
 
-
 Once connected, agents can read the Backlog.md workflow instructions via the resource `backlog://docs/task-workflow`.
 Use `/mcp` command in your AI tool (Claude Code, Codex, Kiro) to verify if the connection is working.
 
@@ -249,6 +262,7 @@ Backlog.md merges the following layers (highest → lowest):
 ### Interactive wizard (`backlog config`)
 
 Run `backlog config` with no arguments to launch the full interactive wizard. This is the same experience triggered from `backlog init` when you opt into advanced settings, and it walks through the complete configuration surface:
+
 - Cross-branch accuracy: `checkActiveBranches`, `remoteOperations`, and `activeBranchDays`.
 - Git workflow: `autoCommit` and `bypassGitHooks`.
 - ID formatting: enable or size `zeroPaddedIds`.
@@ -257,6 +271,7 @@ Run `backlog config` with no arguments to launch the full interactive wizard. Th
 - Web UI defaults: choose `defaultPort` and whether `autoOpenBrowser` should run.
 
 Skipping the wizard (answering "No" during init) applies the safe defaults that ship with Backlog.md:
+
 - `checkActiveBranches=true`, `remoteOperations=true`, `activeBranchDays=30`.
 - `autoCommit=false`, `bypassGitHooks=false`.
 - `zeroPaddedIds` disabled.

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();