@foundation0/api 1.1.5 → 1.1.7

package/mcp/cli.ts

@@ -67,6 +67,9 @@ const parseListArg = (value: string | undefined): string[] => {
 const serverName = getArgValue('--server-name', 'f0-mcp')
 const serverVersion = getArgValue('--server-version', '1.0.0')
 const toolsPrefix = getArgValue('--tools-prefix') ?? process.env.MCP_TOOLS_PREFIX
+const repoName = getArgValue('--repo-name') ?? process.env.MCP_REPO_NAME ?? process.env.F0_REPO_NAME
+const repoRoot =
+  getArgValue('--repo-root') ?? process.env.MCP_REPO_ROOT ?? process.env.F0_REPO_ROOT
 const allowedRootEndpoints = parseListArg(
   getArgValue('--allowed-root-endpoints') ?? process.env.MCP_ALLOWED_ROOT_ENDPOINTS,
 )
@@ -80,6 +83,11 @@ if (hasFlag('--help') || hasFlag('-h')) {
   console.log('  --server-name <name>')
   console.log('  --server-version <version>')
   console.log('  --tools-prefix <prefix>')
+  console.log('  --repo-name <name>')
+  console.log('    Default repoName used by tool calls when omitted. Env: MCP_REPO_NAME or F0_REPO_NAME.')
+  console.log('  --repo-root <path>')
+  console.log('    Default repo root on the server filesystem (contains /api and /projects).')
+  console.log('    Env: MCP_REPO_ROOT or F0_REPO_ROOT.')
   console.log('  --allowed-root-endpoints <csv>')
   console.log('    Example: --allowed-root-endpoints projects')
   console.log('    Example: --allowed-root-endpoints agents,projects')
@@ -96,6 +104,8 @@ void runExampleMcpServer({
   serverName: serverName ?? undefined,
   serverVersion: serverVersion ?? undefined,
   toolsPrefix,
+  repoRoot: repoRoot ?? undefined,
+  repoName: repoName ?? undefined,
   allowedRootEndpoints,
   disableWrite,
   enableIssues,

package/mcp/manual.md

@@ -7,10 +7,12 @@ Assume the server is already configured in your MCP host and you can call its to
 
 1. If you are unsure about a tool name, call `mcp.listTools` first and use the exact name it returns (prefixes vary).
 2. Use `mcp.describeTool` before your first call to a tool to get the input schema + an example payload.
-3. Prefer named keys when possible (e.g. `projectName`, `repoRoot`) rather than relying on positional `args`.
-4. When a tool needs `repoRoot`, it must be the **repo root** containing both `api/` and `projects/` (not a single project folder). (Legacy alias: `processRoot` is still accepted.) If omitted, the server will try to auto-detect a repo root from its current working directory (best effort).
+3. Prefer named keys when possible (e.g. `projectName`, `repoName`) rather than relying on positional `args`.
+4. `repoName` selects the repo workspace on the **server filesystem**. Usually omit it and let the server use its default. Legacy path aliases: `repoRoot` / `processRoot`.
 5. Tool results are returned as a **JSON text envelope**: parse the text as JSON and check `ok`.
 
+Note: If you’re unsure what the server can see (cwd/default repoRoot/available repoName values), call `mcp.workspace`. Multi-repo `repoName` mappings can be configured server-side via `MCP_REPOS` (JSON object or `name=path;name=path`).
+
 ## 1) Tool naming (prefixes + aliases)
 
 Depending on how the server was started, tool names may be:
@@ -24,7 +26,7 @@ Some tools also have OpenAI-safe underscore aliases (no dots). Example:
 
 - `net.curl` may also be available as `net_curl`
 
-## 2) The 3 discovery calls
+## 2) The 4 discovery calls
 
 ### A) List all tools
 
@@ -53,25 +55,33 @@ Tool call:
     "projectName": "<project-name>",
     "section": "spec",
     "pattern": "authentication",
-    "repoRoot": "<repo-root>",
+    "repoName": "<repo-name>",
     "ignoreCase": true,
     "maxCount": 50
   }
 }
 ```
 
+### D) `mcp.workspace` to debug repoName/repoRoot/cwd issues
+
+Tool call:
+
+```json
+{ "name": "mcp.workspace", "arguments": {} }
+```
+
 ## 3) Payload shapes (important)
 
 Most tools accept either:
 
 ```json
-{ "args": ["<project-name>"], "options": { "repoRoot": "<repo-root>" } }
+{ "args": ["<project-name>"], "options": { "repoName": "<repo-name>" } }
 ```
 
 or named keys (recommended). The server merges top-level keys into `options`:
 
 ```json
-{ "projectName": "<project-name>", "repoRoot": "<repo-root>" }
+{ "projectName": "<project-name>", "repoName": "<repo-name>" }
 ```
 
 Guideline: if a tool has a natural named parameter (`projectName`, `agentName`, `target`, `taskRef`), pass it explicitly.
@@ -83,7 +93,7 @@ Guideline: if a tool has a natural named parameter (`projectName`, `agentName`,
 ```json
 {
   "name": "projects.listProjects",
-  "arguments": { "repoRoot": "<repo-root>" }
+  "arguments": { "repoName": "<repo-name>" }
 }
 ```
 
@@ -92,7 +102,7 @@ Guideline: if a tool has a natural named parameter (`projectName`, `agentName`,
 ```json
 {
   "name": "agents.listAgents",
-  "arguments": { "repoRoot": "<repo-root>" }
+  "arguments": { "repoName": "<repo-name>" }
 }
 ```
 
@@ -103,7 +113,7 @@ Guideline: if a tool has a natural named parameter (`projectName`, `agentName`,
   "name": "projects.setActive",
   "arguments": {
     "args": ["<project-name>", "/implementation-plan.v0.0.1"],
-    "options": { "repoRoot": "<repo-root>", "latest": true }
+    "options": { "repoName": "<repo-name>", "latest": true }
   }
 }
 ```
@@ -118,7 +128,7 @@ Call `batch` (or `<prefix>.batch`) to run multiple tool calls:
   "arguments": {
     "calls": [
       { "tool": "projects.usage" },
-      { "tool": "projects.listProjects", "options": { "repoRoot": "<repo-root>" } }
+      { "tool": "projects.listProjects", "options": { "repoName": "<repo-name>" } }
     ],
     "continueOnError": true,
     "maxConcurrency": 4
@@ -137,7 +147,8 @@ If you get:
 
 - **Unknown tool**: use the `suggestions` from the error (when present), or call `mcp.listTools` again and retry.
 - **Missing project name**: pass `projectName` (or set `args[0]`).
-- **Project folder not found: ...projects/.../projects/...**: you likely passed the wrong `repoRoot` (it must be the repo root; legacy alias `processRoot`).
+- **Project folder not found: ...projects/.../projects/...**: call `mcp.workspace` and verify the server repo workspace (default `repoRoot`, and optional `repoName` mapping).
+- **`projects.listProjects()` returns `[]` unexpectedly**: call `mcp.workspace` to confirm the server’s `cwd`/default `repoRoot` and whether `/projects` exists.
 
 ## 6) Tool availability (read/write/admin)
 

package/mcp/server.test.ts

@@ -42,6 +42,7 @@ describe("createExampleMcpServer endpoint whitelist", () => {
 		expect(names).toContain("mcp.usage");
 		expect(names).toContain("mcp.listTools");
 		expect(names).toContain("mcp.describeTool");
+		expect(names).toContain("mcp.workspace");
 		expect(names).not.toContain("mcp.search");
 	});
 
@@ -98,6 +99,7 @@ describe("createExampleMcpServer endpoint whitelist", () => {
 		expect(names).toContain("mcp.usage");
 		expect(names).toContain("mcp.listTools");
 		expect(names).toContain("mcp.describeTool");
+		expect(names).toContain("mcp.workspace");
 		expect(names).not.toContain("mcp.search");
 	});
 
@@ -202,9 +204,9 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
-	it("accepts repoRoot for projects tools (preferred over legacy processRoot)", async () => {
+	it("accepts repoName for projects tools (preferred over legacy repoRoot/processRoot)", async () => {
 		const tempDir = await fs.mkdtemp(
-			path.join(os.tmpdir(), "f0-mcp-server-reporoot-"),
+			path.join(os.tmpdir(), "f0-mcp-server-reponame-"),
 		);
 		try {
 			await fs.mkdir(path.join(tempDir, "api"), { recursive: true });
@@ -215,7 +217,7 @@ describe("createExampleMcpServer request handling", () => {
 				recursive: true,
 			});
 
-			const instance = createExampleMcpServer();
+			const instance = createExampleMcpServer({ repoRoot: tempDir, repoName: "test" });
 			const handler = getToolHandler(instance);
 
 			const result = await handler(
@@ -224,7 +226,7 @@ describe("createExampleMcpServer request handling", () => {
 					params: {
 						name: "projects.listProjects",
 						arguments: {
-							repoRoot: tempDir,
+							repoName: "test",
 						},
 					},
 				},
@@ -241,7 +243,7 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
-	it("auto-detects repoRoot from process.cwd() when repoRoot is omitted", async () => {
+	it("auto-detects repoRoot from process.cwd() when repoName is omitted", async () => {
 		const tempDir = await fs.mkdtemp(
 			path.join(os.tmpdir(), "f0-mcp-server-autoreporoot-"),
 		);
@@ -318,7 +320,7 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
-	it("normalizes repoRoot when caller accidentally passes a project root", async () => {
+	it("normalizes legacy repoRoot when caller accidentally passes a project root", async () => {
 		const tempDir = await fs.mkdtemp(
 			path.join(os.tmpdir(), "f0-mcp-server-reporoot-normalize-"),
 		);
@@ -357,6 +359,79 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
+	it("uses server default repoRoot when repoName is omitted", async () => {
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-default-reporoot-"),
+		);
+		try {
+			await fs.mkdir(path.join(tempDir, "api"), { recursive: true });
+			await fs.mkdir(path.join(tempDir, "projects", "adl", "docs"), {
+				recursive: true,
+			});
+			await fs.mkdir(path.join(tempDir, "projects", "beta", "docs"), {
+				recursive: true,
+			});
+
+			const instance = createExampleMcpServer({ repoRoot: tempDir });
+			const handler = getToolHandler(instance);
+
+			const result = await handler(
+				{
+					method: "tools/call",
+					params: {
+						name: "projects.listProjects",
+						arguments: {},
+					},
+				},
+				{},
+			);
+
+			expect(result.isError).toBe(false);
+			const payload = JSON.parse(result.content?.[0]?.text ?? "{}");
+			expect(payload.ok).toBe(true);
+			expect(payload.result).toContain("adl");
+			expect(payload.result).toContain("beta");
+		} finally {
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it("exposes mcp.workspace to explain server filesystem context", async () => {
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-workspace-"),
+		);
+		try {
+			await fs.mkdir(path.join(tempDir, "api"), { recursive: true });
+			await fs.mkdir(path.join(tempDir, "projects", "adl", "docs"), {
+				recursive: true,
+			});
+
+			const instance = createExampleMcpServer({ repoRoot: tempDir });
+			const handler = getToolHandler(instance);
+
+			const result = await handler(
+				{
+					method: "tools/call",
+					params: {
+						name: "mcp.workspace",
+						arguments: {},
+					},
+				},
+				{},
+			);
+
+			expect(result.isError).toBe(false);
+			const payload = JSON.parse(result.content?.[0]?.text ?? "{}");
+			expect(payload.ok).toBe(true);
+			expect(payload.result.repoRoot).toBe(path.resolve(tempDir));
+			expect(payload.result.defaultRepoRoot).toBe(path.resolve(tempDir));
+			expect(payload.result.hasProjectsDir).toBe(true);
+			expect(Array.isArray(payload.result.projects)).toBe(true);
+		} finally {
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
 	it('parses continueOnError from string "false" (fails fast)', async () => {
 		const instance = createExampleMcpServer();
 		const handler = getToolHandler(instance);

package/mcp/server.ts

@@ -48,7 +48,7 @@ type ApiEndpoint = {
 	mcp: ToolNamespace;
 };
 
-const MCP_HELPER_TOOL_KEYS = ["usage", "listTools", "describeTool"] as const;
+const MCP_HELPER_TOOL_KEYS = ["usage", "listTools", "describeTool", "workspace"] as const;
 type McpHelperToolKey = (typeof MCP_HELPER_TOOL_KEYS)[number];
 const MCP_HELPER_TOOL_NAMES = new Set<string>(
 	MCP_HELPER_TOOL_KEYS.map((key) => `mcp.${key}`),
@@ -63,9 +63,9 @@ const buildProjectsMcpUsage = (toolsPrefix: string | undefined): string => {
 	const tool = (name: string) => formatToolNameForUsage(name, toolsPrefix);
 	return [
 		"MCP Projects usage (tools/call):",
-		`- ${tool("projects.listProjects")}: { options: { repoRoot: \"<repo-root>\" } }`,
-		`- ${tool("projects.generateSpec")}: { args: [\"<projectName>\"], options: { repoRoot: \"<repo-root>\" } }`,
-		`- ${tool("projects.setActive")}: { args: [\"<projectName>\", \"/implementation-plan.v0.0.1\"], options: { repoRoot: \"<repo-root>\", latest: true } }`,
+		`- ${tool("projects.listProjects")}: { options: { repoName: \"<repo-name>\" } }`,
+		`- ${tool("projects.generateSpec")}: { args: [\"<projectName>\"], options: { repoName: \"<repo-name>\" } }`,
+		`- ${tool("projects.setActive")}: { args: [\"<projectName>\", \"/implementation-plan.v0.0.1\"], options: { repoName: \"<repo-name>\", latest: true } }`,
 		"",
 		"Discovery:",
 		`- ${tool("mcp.listTools")}: list available tools (and their schemas)`,
@@ -80,9 +80,9 @@ const buildAgentsMcpUsage = (toolsPrefix: string | undefined): string => {
 	const tool = (name: string) => formatToolNameForUsage(name, toolsPrefix);
 	return [
 		"MCP Agents usage (tools/call):",
-		`- ${tool("agents.listAgents")}: { options: { repoRoot: \"<repo-root>\" } }`,
-		`- ${tool("agents.loadAgent")}: { args: [\"<agentName>\"], options: { repoRoot: \"<repo-root>\" } }`,
-		`- ${tool("agents.setActive")}: { args: [\"<agentName>\", \"/system/boot.v0.0.1\"], options: { repoRoot: \"<repo-root>\", latest: true } }`,
+		`- ${tool("agents.listAgents")}: { options: { repoName: \"<repo-name>\" } }`,
+		`- ${tool("agents.loadAgent")}: { args: [\"<agentName>\"], options: { repoName: \"<repo-name>\" } }`,
+		`- ${tool("agents.setActive")}: { args: [\"<agentName>\", \"/system/boot.v0.0.1\"], options: { repoName: \"<repo-name>\", latest: true } }`,
 		"",
 		"Discovery:",
 		`- ${tool("mcp.listTools")}: list available tools (and their schemas)`,
@@ -176,17 +176,6 @@ const isDir = (candidate: string): boolean => {
 const looksLikeRepoRoot = (candidate: string): boolean =>
 	isDir(path.join(candidate, "projects")) && isDir(path.join(candidate, "api"));
 
-const detectRepoRootFromCwd = (): string | null => {
-	let current = process.cwd();
-	for (let depth = 0; depth < 12; depth += 1) {
-		if (looksLikeRepoRoot(current)) return current;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	return null;
-};
-
 const normalizeRepoRoot = (raw: string): string => {
 	const resolved = path.resolve(raw);
 	if (looksLikeRepoRoot(resolved)) return resolved;
@@ -220,8 +209,10 @@ const normalizeRepoRootOption = (
 	const raw = rawRepoRoot ?? rawProcessRoot;
 
 	if (typeof raw !== "string" || raw.trim().length === 0) {
-		const detected = detectRepoRootFromCwd();
-		return detected ? { ...options, repoRoot: detected } : options;
+		const next = { ...options };
+		delete next.repoRoot;
+		delete next.processRoot;
+		return next;
 	}
 
 	const trimmed = raw.trim();
@@ -235,6 +226,125 @@ const normalizeRepoRootOption = (
 	return alreadyCanonical ? options : next;
 };
 
+const looksLikePathish = (value: string): boolean => {
+	const trimmed = value.trim();
+	if (!trimmed) return false;
+	if (/^[a-zA-Z]:[\\/]/.test(trimmed)) return true;
+	return trimmed.includes("/") || trimmed.includes("\\") || trimmed.startsWith(".");
+};
+
+const parseRepoMap = (raw: string | undefined): Record<string, string> => {
+	const input = typeof raw === "string" ? raw.trim() : "";
+	if (!input) return {};
+
+	if (input.startsWith("{")) {
+		try {
+			const parsed = JSON.parse(input);
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+				return {};
+			}
+			const out: Record<string, string> = {};
+			for (const [name, root] of Object.entries(parsed)) {
+				if (!name || typeof root !== "string" || !root.trim()) continue;
+				out[name.trim()] = root.trim();
+			}
+			return out;
+		} catch {
+			return {};
+		}
+	}
+
+	const entries = input
+		.split(/[;,]/g)
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+
+	const out: Record<string, string> = {};
+	for (const entry of entries) {
+		const [name, root] = entry.split("=", 2);
+		if (!name || !root) continue;
+		const key = name.trim();
+		const value = root.trim();
+		if (!key || !value) continue;
+		out[key] = value;
+	}
+	return out;
+};
+
+type RepoResolutionContext = {
+	defaultRepoRoot: string;
+	defaultRepoName: string;
+	repoMapByKey: Record<string, string>;
+	repoNames: string[];
+};
+
+const resolveRepoSelectorOptions = (
+	options: Record<string, unknown>,
+	ctx: RepoResolutionContext,
+): Record<string, unknown> => {
+	const next: Record<string, unknown> = { ...options };
+
+	const explicitRoot =
+		(typeof next.repoRoot === "string" && next.repoRoot.trim().length > 0
+			? next.repoRoot.trim()
+			: null) ??
+		(typeof next.processRoot === "string" && next.processRoot.trim().length > 0
+			? next.processRoot.trim()
+			: null);
+
+	if (explicitRoot) {
+		next.repoRoot = normalizeRepoRoot(explicitRoot);
+		delete next.processRoot;
+		delete next.repoName;
+		return next;
+	}
+
+	const repoName =
+		typeof next.repoName === "string" && next.repoName.trim().length > 0
+			? next.repoName.trim()
+			: null;
+	if (!repoName) {
+		delete next.processRoot;
+		return next;
+	}
+
+	if (looksLikePathish(repoName)) {
+		next.repoRoot = normalizeRepoRoot(repoName);
+		delete next.processRoot;
+		delete next.repoName;
+		return next;
+	}
+
+	const needle = repoName.toLowerCase();
+	if (needle === ctx.defaultRepoName.toLowerCase()) {
+		next.repoRoot = ctx.defaultRepoRoot;
+		delete next.processRoot;
+		delete next.repoName;
+		return next;
+	}
+
+	const mapped = ctx.repoMapByKey[needle];
+	if (mapped) {
+		next.repoRoot = normalizeRepoRoot(mapped);
+		delete next.processRoot;
+		delete next.repoName;
+		return next;
+	}
+
+	const suggestions = ctx.repoNames
+		.filter((name) => name.toLowerCase().includes(needle))
+		.slice(0, 8);
+	const hint =
+		suggestions.length > 0
+			? ` Did you mean: ${suggestions.join(", ")}?`
+			: ctx.repoNames.length > 0
+				? ` Available repos: ${ctx.repoNames.join(", ")}.`
+				: "";
+	throw new Error(
+		`Unknown repoName: ${repoName}.${hint} Tip: call mcp.workspace to see the server repo context.`,
+	);
+};
+
 type NormalizedToolPayload = {
 	args: unknown[];
 	options: Record<string, unknown>;
@@ -460,7 +570,7 @@ const coercePayloadForTool = (
 
 	switch (toolName) {
 		case "projects.listProjects": {
-			// No positional args. repoRoot is handled via options.repoRoot + buildRepoRootOnly.
+			// No positional args. repoRoot is resolved from repoName/repoRoot/processRoot and passed via buildRepoRootOnly.
 			break;
 		}
 		case "projects.resolveProjectRoot":
@@ -861,7 +971,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				description: "Unused.",
 				additionalProperties: true,
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
 				description: "Unused.",
 			},
@@ -871,10 +981,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		type: "object",
 		additionalProperties: true,
 		properties: {
-			repoRoot: {
+			repoName: {
 				type: "string",
 				description:
-					'Repo root containing /projects and /agents. If you have a project root like ".../projects/adl", omit this or pass its parent.',
+					"Repo selector (LLM-friendly). Omit to use server default. Tip: call mcp.workspace to see available repoName values.",
 			},
 		},
 		required: [],
@@ -887,10 +997,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: 'Project name under /projects (e.g. "adl").',
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
 				description:
-					"Repo root containing /projects and /agents. If omitted, uses server cwd.",
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -913,9 +1023,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: 'Project name under /projects (e.g. "adl").',
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects and /agents.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -943,9 +1054,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				description:
 					'Doc path under docs/, starting with "docs/..." (or a bare filename in catalog).',
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects and /agents.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -1020,9 +1132,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Remote repo override for gitea mode.",
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects and /agents.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -1097,9 +1210,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Remote repo override for gitea mode.",
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects and /agents.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -1213,9 +1327,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "boolean",
 				description: "If true, only return issues with TASK-* IDs.",
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -1254,9 +1369,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "boolean",
 				description: "If true, restrict to issues with TASK-* payloads.",
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -1311,9 +1427,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Optional task signature.",
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -1345,9 +1462,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				items: { type: "string" },
 				description: "Labels to set.",
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
-				description: "Repo root containing /projects.",
+				description:
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -1362,6 +1480,21 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		},
 		required: ["projectName", "title"],
 	},
+	"mcp.workspace": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			repoName: {
+				type: "string",
+				description:
+					"Optional repo selector (LLM-friendly). Omit to use server default. You can also pass a server filesystem path via legacy repoRoot/processRoot.",
+			},
+		},
+		required: [],
+		$comment: safeJsonStringify({
+			example: {},
+		}),
+	},
 	"mcp.search": {
 		type: "object",
 		additionalProperties: true,
@@ -1419,10 +1552,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Optional override cache directory.",
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
 				description:
-					"Repo root containing /projects. If you pass a project root, it will be normalized.",
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 		},
 		$comment: safeJsonStringify({
@@ -1454,7 +1587,7 @@ const buildArgsSchemaFromPlaceholders = (
 const TOOL_ARGS_SCHEMA_OVERRIDES: Record<string, Record<string, unknown>> = {
 	"projects.listProjects": {
 		type: "array",
-		description: "No positional arguments. Use options.repoRoot if needed.",
+		description: "No positional arguments. Use options.repoName if needed.",
 		minItems: 0,
 		maxItems: 0,
 		items: {},
@@ -1588,12 +1721,12 @@ const buildInvocationExample = (toolName: string): Record<string, unknown> => {
 	}
 
 	if (plan === "repoRootOnly") {
-		example.options = { repoRoot: "<repo-root>", ...defaultOptions };
+		example.options = { repoName: "<repo-name>", ...defaultOptions };
 		return example;
 	}
 
 	if (plan === "optionsThenRepoRoot" || plan === "repoRootThenOptions") {
-		example.options = { repoRoot: "<repo-root>", ...defaultOptions };
+		example.options = { repoName: "<repo-name>", ...defaultOptions };
 		return example;
 	}
 
@@ -1624,10 +1757,10 @@ const defaultToolInputSchema = (toolName: string) => ({
 			additionalProperties: true,
 			description: "Named options",
 		},
-		repoRoot: {
+		repoName: {
 			type: "string",
 			description:
-				'Repo root containing /projects and /agents. If you have a project root like ".../projects/adl", omit this or pass its parent.',
+				"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 		},
 	},
 	$comment: safeJsonStringify({
@@ -1743,11 +1876,13 @@ const buildToolList = (
 type ToolInvoker = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ) => unknown[];
 
 const buildOptionsOnly = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	_defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	if (Object.keys(options).length > 0) {
@@ -1759,6 +1894,7 @@ const buildOptionsOnly = (
 const buildOptionsThenRepoRoot = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
@@ -1766,16 +1902,16 @@ const buildOptionsThenRepoRoot = (
 	if (typeof repoRoot === "string") {
 		delete remaining.repoRoot;
 	}
+	const resolvedRepoRoot =
+		typeof repoRoot === "string" ? repoRoot : defaultRepoRoot;
 
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
-	} else if (typeof repoRoot === "string") {
+	} else if (resolvedRepoRoot) {
 		// Preserve positional slot for signatures like fn(projectName, options?, repoRoot?).
 		invocationArgs.push({});
 	}
-	if (typeof repoRoot === "string") {
-		invocationArgs.push(repoRoot);
-	}
+	invocationArgs.push(resolvedRepoRoot);
 
 	return invocationArgs;
 };
@@ -1783,6 +1919,7 @@ const buildOptionsThenRepoRoot = (
 const buildRepoRootThenOptions = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
@@ -1791,9 +1928,7 @@ const buildRepoRootThenOptions = (
 		delete remaining.repoRoot;
 	}
 
-	if (typeof repoRoot === "string") {
-		invocationArgs.push(repoRoot);
-	}
+	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
 	}
@@ -1804,12 +1939,11 @@ const buildRepoRootThenOptions = (
 const buildRepoRootOnly = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const repoRoot = options.repoRoot;
-	if (typeof repoRoot === "string") {
-		invocationArgs.push(repoRoot);
-	}
+	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
 	return invocationArgs;
 };
 
@@ -1828,7 +1962,7 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 	"projects.resolveProjectTargetFile": buildOptionsOnly,
 	"agents.loadAgent": buildRepoRootOnly,
 	"agents.loadAgentPrompt": buildRepoRootOnly,
-	"projects.resolveImplementationPlan": (args, options) => {
+	"projects.resolveImplementationPlan": (args, options, _defaultRepoRoot) => {
 		const invocationArgs: unknown[] = [...args];
 		const remaining = { ...options };
 		const repoRoot = remaining.repoRoot;
@@ -1861,19 +1995,24 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 const invokeTool = async (
 	tool: ToolDefinition,
 	payload: unknown,
+	repoCtx: RepoResolutionContext,
 ): Promise<unknown> => {
 	const normalized = normalizePayload(payload);
-	const { args, options } = coercePayloadForTool(tool.name, normalized);
+	const coerced = coercePayloadForTool(tool.name, normalized);
+	const { args, options } = {
+		args: coerced.args,
+		options: resolveRepoSelectorOptions(coerced.options, repoCtx),
+	};
 	const invoke =
 		toolInvocationPlans[tool.name] ??
-		((rawArgs, rawOptions) => {
+		((rawArgs, rawOptions, _repoRoot) => {
 			const invocationArgs = [...rawArgs];
 			if (Object.keys(rawOptions).length > 0) {
 				invocationArgs.push(rawOptions);
 			}
 			return invocationArgs;
 		});
-	const invocationArgs = invoke(args, options);
+	const invocationArgs = invoke(args, options, repoCtx.defaultRepoRoot);
 
 	return Promise.resolve(tool.method(...invocationArgs));
 };
@@ -1882,6 +2021,16 @@ export interface ExampleMcpServerOptions {
 	serverName?: string;
 	serverVersion?: string;
 	toolsPrefix?: string;
+	/**
+	 * Optional default repo root on the server filesystem.
+	 * If omitted, the server attempts to auto-detect by walking up from cwd.
+	 */
+	repoRoot?: string;
+	/**
+	 * Optional default repo name (LLM-friendly identifier).
+	 * If omitted, defaults to the basename of the resolved repo root.
+	 */
+	repoName?: string;
 	allowedRootEndpoints?: string[];
 	disableWrite?: boolean;
 	enableIssues?: boolean;
@@ -1922,6 +2071,7 @@ const READ_ONLY_TOOL_NAMES = new Set<string>([
 	"mcp.usage",
 	"mcp.listTools",
 	"mcp.describeTool",
+	"mcp.workspace",
 	"mcp.search",
 ]);
 
@@ -2012,6 +2162,31 @@ export const createExampleMcpServer = (
 	options: ExampleMcpServerOptions = {},
 ): ExampleMcpServerInstance => {
 	let toolCatalog: unknown[] = [];
+	const defaultRepoRoot = normalizeRepoRoot(
+		options.repoRoot ??
+			process.env.MCP_REPO_ROOT ??
+			process.env.F0_REPO_ROOT ??
+			process.cwd(),
+	);
+	const defaultRepoName =
+		(options.repoName ?? process.env.MCP_REPO_NAME ?? process.env.F0_REPO_NAME)?.trim() ||
+		path.basename(defaultRepoRoot);
+	const repoMapRaw = process.env.MCP_REPOS ?? process.env.F0_REPOS;
+	const repoMap = {
+		...parseRepoMap(repoMapRaw),
+		[defaultRepoName]: defaultRepoRoot,
+	};
+	const repoNames = Object.keys(repoMap).sort((a, b) => a.localeCompare(b));
+	const repoMapByKey: Record<string, string> = {};
+	for (const [name, root] of Object.entries(repoMap)) {
+		repoMapByKey[name.toLowerCase()] = root;
+	}
+	const repoCtx: RepoResolutionContext = {
+		defaultRepoRoot,
+		defaultRepoName,
+		repoMapByKey,
+		repoNames,
+	};
 
 	const parseString = (value: unknown): string | null => {
 		if (typeof value !== "string") return null;
@@ -2051,11 +2226,73 @@ export const createExampleMcpServer = (
 				"F0 MCP helper tools:",
 				"- mcp.listTools: returns tool catalog with access + invocation hints",
 				"- mcp.describeTool: describe one tool by name (prefixed or unprefixed)",
+				"- mcp.workspace: explain server filesystem context (cwd, repoName/repoRoot, projects)",
 				"- mcp.search: LLM-friendly search over project docs/spec (local-first)",
 				"",
 				'Tip: Prefer mcp.search for "search spec/docs" requests.',
 			].join("\n"),
 		listTools: () => ({ tools: toolCatalog }),
+		workspace: (input?: unknown) => {
+			const payload = isRecord(input) ? input : {};
+			const received = isRecord(input)
+				? {
+						keys: Object.keys(input),
+						repoName: (input as any).repoName ?? null,
+						repoRoot: (input as any).repoRoot ?? null,
+						processRoot: (input as any).processRoot ?? null,
+					}
+				: { keys: [], repoName: null, repoRoot: null, processRoot: null };
+			const requestedRepoName = parseString(payload.repoName);
+			const resolved = resolveRepoSelectorOptions(payload, repoCtx);
+			const repoRoot =
+				typeof resolved.repoRoot === "string"
+					? resolved.repoRoot
+					: repoCtx.defaultRepoRoot;
+			const effectiveRepoName =
+				requestedRepoName && !looksLikePathish(requestedRepoName)
+					? requestedRepoName
+					: repoCtx.defaultRepoName;
+
+			const projectsDir = path.join(repoRoot, "projects");
+			const apiDir = path.join(repoRoot, "api");
+			const agentsDir = path.join(repoRoot, "agents");
+			const hasProjectsDir = isDir(projectsDir);
+			const hasApiDir = isDir(apiDir);
+			const hasAgentsDir = isDir(agentsDir);
+
+			const projects = hasProjectsDir ? projectsApi.listProjects(repoRoot) : [];
+			const hint = (() => {
+				if (!hasProjectsDir) {
+					return [
+						"Repo does not contain /projects on the server filesystem.",
+						"Start the MCP server from the monorepo root (the folder that contains both /api and /projects), or configure the server with --repo-root / MCP_REPO_ROOT.",
+						"Tool callers should usually omit repoName and let the server use its default workspace.",
+					].join(" ");
+				}
+				if (hasProjectsDir && projects.length === 0) {
+					return [
+						"Found /projects, but no projects with docs/ were detected.",
+						"Each project folder must contain a docs/ directory to be listed.",
+					].join(" ");
+				}
+				return null;
+			})();
+
+			return {
+				received,
+				cwd: process.cwd(),
+				defaultRepoName: repoCtx.defaultRepoName,
+				defaultRepoRoot: repoCtx.defaultRepoRoot,
+				repoName: effectiveRepoName,
+				repoRoot,
+				availableRepoNames: repoCtx.repoNames,
+				hasProjectsDir,
+				hasApiDir,
+				hasAgentsDir,
+				projects,
+				hint,
+			};
+		},
 		describeTool: (toolName: string) => {
 			const normalized = typeof toolName === "string" ? toolName.trim() : "";
 			if (!normalized) {
@@ -2096,11 +2333,11 @@ export const createExampleMcpServer = (
 		},
 		search: async (input: unknown) => {
 			const payload = isRecord(input) ? input : {};
-			const repoRoot = (() => {
-				const raw =
-					parseString(payload.repoRoot) ?? parseString(payload.processRoot);
-				return raw ? normalizeRepoRoot(raw) : process.cwd();
-			})();
+			const resolved = resolveRepoSelectorOptions(payload, repoCtx);
+			const repoRoot =
+				typeof resolved.repoRoot === "string"
+					? resolved.repoRoot
+					: repoCtx.defaultRepoRoot;
 
 			const sectionRaw = parseString(payload.section)?.toLowerCase();
 			const section = sectionRaw === "docs" ? "docs" : "spec";
@@ -2295,7 +2532,7 @@ export const createExampleMcpServer = (
 					tool: prefix
 						? `${prefix}.projects.listProjects`
 						: "projects.listProjects",
-					options: { repoRoot: "<repo-root>" },
+					options: { repoName: "<repo-name>" },
 				},
 			],
 			continueOnError: true,
@@ -2474,7 +2711,24 @@ export const createExampleMcpServer = (
 			/projects[\\/].+projects[\\/]/i.test(message)
 		) {
 			details.hint =
-				"You likely passed a project root as repoRoot. repoRoot should be the repo root containing /projects. (Legacy alias: processRoot.)";
+				"You likely passed a project root as repoName (or legacy repoRoot/processRoot). Repo selection should point at the monorepo root that contains /projects.";
+			details.suggestion =
+				"Call mcp.workspace to see the server’s cwd/default repoRoot, then omit repoName or pass the correct repoName.";
+		}
+
+		if (
+			/Project folder not found:/i.test(message) &&
+			!details.hint &&
+			/projects[\\/]/i.test(message)
+		) {
+			details.hint =
+				"Repo selection might be wrong, or the server filesystem does not contain /projects for this workspace.";
+			details.suggestion =
+				"Call mcp.workspace to see the server’s cwd/default repoRoot and available repoName values.";
+			details.example = {
+				tool: prefix ? `${prefix}.mcp.workspace` : "mcp.workspace",
+				arguments: {},
+			};
 		}
 
 		if (/Missing search pattern\./i.test(message)) {
@@ -2538,7 +2792,7 @@ export const createExampleMcpServer = (
 					}
 
 					try {
-						const data = await invokeTool(toolDefinition, { args, options });
+						const data = await invokeTool(toolDefinition, { args, options }, repoCtx);
 						return { index, tool, isError: false, data };
 					} catch (error) {
 						const message =
@@ -2590,7 +2844,7 @@ export const createExampleMcpServer = (
 		}
 
 		try {
-			const data = await invokeTool(tool, request.params.arguments);
+			const data = await invokeTool(tool, request.params.arguments, repoCtx);
 			return toolOk(data);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundation0/api",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Foundation 0 API",
   "type": "module",
   "bin": {
@@ -35,6 +35,7 @@
   "scripts": {
     "mcp": "bun run mcp/cli.ts",
     "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov",
     "deploy": "pnpm publish --access public",
     "version:patch": "pnpm version patch && git commit -am \"Bump version to %s\"",
     "version:minor": "pnpm version minor && git commit -am \"Bump version to %s\"",