PatrickSys · PatrickSys · Mar 11, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- **mcp:** rework multi-project routing so one MCP server can serve multiple projects instead of one hardcoded server entry per repo
+- **mcp:** keep explicit `project` as the fallback when the client does not provide enough project context
+- **mcp:** accept repo paths, subproject paths, and file paths as `project` selectors when routing is ambiguous
+
+### Documentation
+
+- simplify the setup story around three cases: default rootless setup, single-project fallback, and explicit `project` retries
+- clarify that issue #63 fixed the architecture and workspace-aware workflow, but issue #2 is not fully solved when the client does not provide enough project context
+- remove the repo-local `init` / marker-file story from the public setup guidance
+
 ## [1.8.2](https://github.com/PatrickSys/codebase-context/compare/v1.8.1...v1.8.2) (2026-03-05)
 
 
@@ -85,10 +99,13 @@
 ### Bug Fixes
 
 - restore `npx` / `npm exec` installs by removing the published pnpm-only `preinstall` guard
+- harden multi-project MCP routing so configured roots are pre-warmed in the background, `codebase://context` falls back to a workspace overview before selection, and ambiguous sessions now recover through an explicit path-based `project` selector instead of an opaque session ref
 
 ### Added
 
 - **Definition-first ranking**: Exact-name searches now show the file that _defines_ a symbol before files that use it. For example, searching `parseConfig` shows the function definition first, then callers.
+- **Path-based multi-project routing**: multi-project and monorepo sessions can route explicitly with `project` using an absolute repo path, `file://` URI, or a relative subproject path such as `apps/dashboard`.
+- **Project-scoped context resources**: `codebase://context/project/<encoded-project-path>` serves proactive context for a specific configured project and also makes later tool calls deterministic.
 
 ### Refactored
 
@@ -118,6 +135,7 @@
 - **2-hop transitive impact** (PR #50): `search --intent edit` impact now shows direct importers (hop 1) and their importers (hop 2), each labeled with distance. Capped at 20.
 - **Chokidar file watcher** (PR #52): index auto-refreshes in MCP server mode on file save (2 s debounce). No manual `reindex` needed during active editing sessions.
 - **CLI human formatters** (PR #48): all 9 commands now render as structured human-readable output. `--json` flag on every command for agent/pipe consumption.
+- **Multi-project MCP routing**: automatic routing still handles the single-project and already-active-project cases, while ambiguous multi-project sessions now require an explicit path-based `project` selector instead of forcing a selector-first flow.
 - **`status` + `reindex` formatters** (PR #56): status box with index health, progress, and last-built time. ASCII fallback via `CODEBASE_CONTEXT_ASCII=1`.
 - **`docs/cli.md` gallery** (PR #56): command reference with output previews for all 9 CLI commands.
 

diff --git a/README.md b/README.md
@@ -44,14 +44,48 @@ More CLI examples:
 - `metadata` for a quick codebase overview
 - Full gallery in `docs/cli.md`
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Multi-Project and Monorepos](#multi-project-and-monorepos)
+- [Test It Yourself](#test-it-yourself)
+- [Common First Commands](#common-first-commands)
+- [What It Actually Does](#what-it-actually-does)
+- [Evaluation Harness (`npm run eval`)](#evaluation-harness-npm-run-eval)
+- [How the Search Works](#how-the-search-works)
+- [Language Support](#language-support)
+- [Configuration](#configuration)
+- [Performance](#performance)
+- [File Structure](#file-structure)
+- [CLI Reference](#cli-reference)
+- [What to add to your CLAUDE.md / AGENTS.md](#what-to-add-to-your-claudemd--agentsmd)
+- [Links](#links)
+- [License](#license)
+
 ## Quick Start
 
+Start with the default setup:
+
+- Configure one `codebase-context` server with no project path.
+- If a tool call later returns `selection_required`, retry with `project`.
+- If you only use one repo, you can also append that repo path up front.
+
+### Pick the right setup
+
+| Situation | Recommended config |
+| --- | --- |
+| Default setup | Run `npx -y codebase-context` with no project path |
+| Single repo setup | Append one project path or set `CODEBASE_ROOT` |
+| Multi-project call is still ambiguous | Retry with `project`, or keep separate server entries if your client cannot preserve project context |
+
+### Recommended setup
+
 Add it to the configuration of your AI Agent of preference:
 
 ### Claude Code
 
 ```bash
-claude mcp add codebase-context -- npx -y codebase-context /path/to/your/project
+claude mcp add codebase-context -- npx -y codebase-context
 ```
 
 ### Claude Desktop
@@ -63,7 +97,7 @@ Add to `claude_desktop_config.json`:
   "mcpServers": {
     "codebase-context": {
       "command": "npx",
-      "args": ["-y", "codebase-context", "/path/to/your/project"]
+      "args": ["-y", "codebase-context"]
     }
   }
 }
@@ -78,7 +112,7 @@ Add `.vscode/mcp.json` to your project root:
   "servers": {
     "codebase-context": {
       "command": "npx",
-      "args": ["-y", "codebase-context", "/path/to/your/project"] // Or "${workspaceFolder}" if your workspace is one project only
+      "args": ["-y", "codebase-context"] // Or append "${workspaceFolder}" for single-project use
     }
   }
 }
@@ -93,7 +127,7 @@ Add to `.cursor/mcp.json` in your project:
   "mcpServers": {
     "codebase-context": {
       "command": "npx",
-      "args": ["-y", "codebase-context", "/path/to/your/project"]
+      "args": ["-y", "codebase-context"]
     }
   }
 }
@@ -108,7 +142,7 @@ Open Settings > MCP and add:
   "mcpServers": {
     "codebase-context": {
       "command": "npx",
-      "args": ["-y", "codebase-context", "/path/to/your/project"]
+      "args": ["-y", "codebase-context"]
     }
   }
 }
@@ -124,7 +158,7 @@ Add `opencode.json` to your project root:
   "mcp": {
     "codebase-context": {
       "type": "local",
-      "command": ["npx", "-y", "codebase-context", "/path/to/your/project"],
+      "command": ["npx", "-y", "codebase-context"],
       "enabled": true
     }
   }
@@ -135,11 +169,145 @@ OpenCode also supports interactive setup via `opencode mcp add`.
 
 ### Codex
 
+```bash
+codex mcp add codebase-context npx -y codebase-context
+```
+
+That single config entry is the intended starting point.
+
+### Fallback setup for single-project use
+
+If you only use one repo, append a project path:
+
 ```bash
 codex mcp add codebase-context npx -y codebase-context "/path/to/your/project"
 ```
 
-## New to this codebase?
+Or set:
+
+```bash
+CODEBASE_ROOT=/path/to/your/project
+```
+
+## Multi-Project and Monorepos
+
+The MCP server can serve multiple projects in one session without requiring one MCP config entry per repo.
+
+Three cases matter:
+
+| Case | What happens |
+| --- | --- |
+| One project | Routing is automatic |
+| Multiple projects and the client provides enough workspace context | The server can route across those projects in one MCP session |
+| Multiple projects and the target is still ambiguous | The server does not guess. Use `project` explicitly |
+
+Important rules:
+
+- `project` is the explicit override when routing is ambiguous.
+- `project` accepts a project root path, file path, `file://` URI, or a relative subproject path under a configured workspace such as `apps/dashboard`.
+- If a client reads `codebase://context` before any project is active, the server returns a workspace overview instead of guessing.
+- The server does not rely on `cwd` walk-up in MCP mode.
+
+Typical explicit retry in a monorepo:
+
+```json
+{
+  "name": "search_codebase",
+  "arguments": {
+    "query": "auth interceptor",
+    "project": "apps/dashboard"
+  }
+}
+```
+
+Or target a repo directly:
+
+```json
+{
+  "name": "search_codebase",
+  "arguments": {
+    "query": "auth interceptor",
+    "project": "/repos/customer-portal"
+  }
+}
+```
+
+Or pass a file path and let the server resolve the nearest trusted project boundary:
+
+```json
+{
+  "name": "search_codebase",
+  "arguments": {
+    "query": "auth interceptor",
+    "project": "/repos/monorepo/apps/dashboard/src/auth/guard.ts"
+  }
+}
+```
+
+If you see `selection_required`, the server could not tell which project you meant. Retry the call with `project`.
+
+`codebase://context` follows the active project in the session. In unresolved multi-project sessions it returns a workspace overview. Project-scoped resources are also available via the URIs listed in that overview.
+
+The CLI stays intentionally simpler: it targets one repo per invocation via `CODEBASE_ROOT` or the current working directory. Multi-project discovery and routing are MCP-only features, not a second CLI session model.
+
+## Test It Yourself
+
+Build the local branch first:
+
+```bash
+pnpm build
+```
+
+Then point your MCP client at the local build:
+
+```json
+{
+  "mcpServers": {
+    "codebase-context": {
+      "command": "node",
+      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js"]
-      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js"]
+    "args": ["<path-to-local-build>/dist/index.js"]
-      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js"]
+    "args": ["<path-to-local-build>/dist/index.js", "/path/to/your/project"]
-      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js"]
+    "args": ["<path-to-local-build>/dist/index.js"]
-      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js"]
+    "args": ["<path-to-local-build>/dist/index.js", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+If the default setup is not enough for your client, use this instead:
+
+```json
+{
+  "mcpServers": {
+    "codebase-context": {
+      "command": "node",
+      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js", "C:/path/to/your/project"]
+    }
+  }
+}
+```
+
+Check these three flows:
+
+1. Single project
+   Ask for `search_codebase` or `metadata`.
+   Expected: routing is automatic.
+
+2. Multiple projects with one server entry
+   Open two repos or one monorepo workspace.
+   Ask for `codebase://context`.
+   Expected: workspace overview first, then automatic routing once one project is active or unambiguous.
+
+3. Ambiguous project selection
+   Start without a bootstrap path.
+   Ask for `search_codebase`.
+   Expected: `selection_required`.
+   Retry with `project`, for example `apps/dashboard` or `/repos/customer-portal`.
+
+For monorepos, verify all three selector forms:
+
+- relative subproject path: `apps/dashboard`
+- repo path: `/repos/customer-portal`
+- file path: `/repos/monorepo/apps/dashboard/src/auth/guard.ts`
+
+## Common First Commands
 
 Three commands to get what usually takes a new developer weeks to piece together:
 
@@ -342,12 +510,12 @@ Structured filters available: `framework`, `language`, `componentType`, `layer`
 
 ## Configuration
 
-| Variable                 | Default                    | Description                                                                                   |
-| ------------------------ | -------------------------- | --------------------------------------------------------------------------------------------- |
-| `EMBEDDING_PROVIDER`     | `transformers`             | `openai` (fast, cloud) or `transformers` (local, private)                                     |
-| `OPENAI_API_KEY`         | -                          | Required only if using `openai` provider                                                      |
-| `CODEBASE_ROOT`          | -                          | Project root (CLI arg takes precedence)                                                       |
-| `CODEBASE_CONTEXT_DEBUG` | -                          | Set to `1` for verbose logging                                                                |
+| Variable                 | Default                    | Description                                                                                                |
+| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `EMBEDDING_PROVIDER`     | `transformers`             | `openai` (fast, cloud) or `transformers` (local, private)                                                  |
+| `OPENAI_API_KEY`         | -                          | Required only if using `openai` provider                                                                   |
+| `CODEBASE_ROOT`          | -                          | Optional bootstrap root for CLI and single-project MCP clients without roots                              |
+| `CODEBASE_CONTEXT_DEBUG` | -                          | Set to `1` for verbose logging                                                                             |
 | `EMBEDDING_MODEL`        | `Xenova/bge-small-en-v1.5` | Local embedding model override (e.g. `onnx-community/granite-embedding-small-english-r2-ONNX` for Granite) |
 
 ## Performance
@@ -378,7 +546,7 @@ Structured filters available: `framework`, `language`, `componentType`, `layer`
 
 ## CLI Reference
 
-All MCP tools are available as CLI commands — no AI agent required. Useful for onboarding, scripting, debugging, and CI workflows.
+Repo-scoped analysis commands are available via the CLI — no AI agent required. MCP multi-project routing uses the shared `project` selector when needed; the CLI stays one-root-per-invocation.
 For formatted examples and “money shots”, see `docs/cli.md`.
 
 Set `CODEBASE_ROOT` to your project root, or run from the project directory.

diff --git a/docs/capabilities.md b/docs/capabilities.md
@@ -4,7 +4,8 @@ Technical reference for what `codebase-context` ships today. For the user-facing
 
 ## CLI Reference
 
-All shipped capabilities are available locally via the CLI (human-readable by default, `--json` for automation).
+Repo-scoped capabilities are available locally via the CLI (human-readable by default, `--json` for automation).
+Multi-project selection is MCP-only because the CLI already targets one root per invocation.
 For a “gallery” of commands and examples, see `docs/cli.md`.
 
 | Command | Flags | Maps to |
@@ -34,17 +35,24 @@ npx codebase-context reindex --incremental
 
 ## Tool Surface
 
-10 MCP tools + 1 optional resource (`codebase://context`). **Migration:** `get_component_usage` was removed; use `get_symbol_references` for symbol usage evidence.
+10 MCP tools + active/project-scoped context resources.
+
+Shared selector inputs:
+
+- `project` (preferred): project root path, file path, `file://` URI, or relative subproject path under a configured root
+- `project_directory` (compatibility alias): deprecated alias for `project`
+
+**Migration:** `get_component_usage` was removed; use `get_symbol_references` for symbol usage evidence.
 
 ### Core Tools
 
 | Tool                    | Input                                                             | Output                                                                                                                                                                                                                  |
 | ----------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search_codebase`       | `query`, optional `intent`, `limit`, `filters`, `includeSnippets` | Ranked results (`file`, `summary`, `score`, `type`, `trend`, `patternWarning`, `relationships`, `hints`) + `searchQuality` + decision card (`ready`, `nextAction`, `patterns`, `bestExample`, `impact`, `whatWouldHelp`) when `intent="edit"`. Hints capped at 3 per category. |
-| `get_team_patterns`     | optional `category`                                               | Pattern frequencies, trends, golden files, conflicts                                                                                                                                 |
-| `get_symbol_references` | `symbol`, optional `limit`                                        | Concrete symbol usage evidence: `usageCount` + top usage snippets + `confidence` + `isComplete`. `confidence: "syntactic"` means static/source-based only (no runtime or dynamic dispatch). When Tree-sitter + file content are available, comments and string literals are excluded from the scan — the count reflects real identifier nodes only. Replaces the removed `get_component_usage`. |
-| `remember`              | `type`, `category`, `memory`, `reason`                            | Persists to `.codebase-context/memory.json`                                                                                                                                          |
-| `get_memory`            | optional `category`, `type`, `query`, `limit`                     | Memories with confidence decay scoring                                                                                                                                               |
+| `search_codebase`       | `query`, optional `intent`, `limit`, `filters`, `includeSnippets`, shared `project`/`project_directory` | Ranked results (`file`, `summary`, `score`, `type`, `trend`, `patternWarning`, `relationships`, `hints`) + `searchQuality` + decision card (`ready`, `nextAction`, `patterns`, `bestExample`, `impact`, `whatWouldHelp`) when `intent="edit"`. Hints capped at 3 per category. |
+| `get_team_patterns`     | optional `category`, shared `project`/`project_directory`     | Pattern frequencies, trends, golden files, conflicts                                                                                                                                 |
+| `get_symbol_references` | `symbol`, optional `limit`, shared `project`/`project_directory` | Concrete symbol usage evidence: `usageCount` + top usage snippets + `confidence` + `isComplete`. `confidence: "syntactic"` means static/source-based only (no runtime or dynamic dispatch). When Tree-sitter + file content are available, comments and string literals are excluded from the scan — the count reflects real identifier nodes only. Replaces the removed `get_component_usage`. |
+| `remember`              | `type`, `category`, `memory`, `reason`, shared `project`/`project_directory` | Persists to `.codebase-context/memory.json`                                                                                                                                          |
+| `get_memory`            | optional `category`, `type`, `query`, `limit`, shared `project`/`project_directory` | Memories with confidence decay scoring                                                                                                                                               |
 
 ### Utility Tools
 
@@ -56,6 +64,28 @@ npx codebase-context reindex --incremental
 | `refresh_index`                | Full or incremental re-index + git memory extraction |
 | `get_indexing_status`          | Index state, progress, last stats                    |
 
+## Project Routing
+
+Behavior matrix:
+
+| Situation | Server behavior |
+| --- | --- |
+| One known project | Automatic routing |
+| Multiple known projects + active project already set | Automatic routing to the active project |
+| Multiple known projects + no active project | `selection_required` |
+| No workspace context and no bootstrap path | `selection_required` until the caller passes `project` |
+
+Rules:
+
+- If the client provides workspace context, that becomes the trusted workspace boundary for the session. In practice this usually comes from MCP roots.
+- If the server still cannot tell which project to use, a bootstrap path or explicit absolute `project` path remains the fallback.
+- `project` is the canonical explicit selector when routing is ambiguous.
+- `project` may point at a project path, file path, `file://` URI, or relative subproject path.
+- Later tool calls may omit `project`; the server falls back to the active project when one has already been established.
+- The server does not rely on `cwd` walk-up in MCP mode.
+- `codebase://context` serves the active project. Before selection in an unresolved multi-project session, it returns a workspace overview with candidate projects, readiness state, and project-scoped resource URIs.
+- `codebase://context/project/<encoded-project-path>` serves a specific project directly and also makes that project active for later tool calls.
+
 ## Retrieval Pipeline
 
 Ordered by execution: