@foundation0/api 1.1.6 → 1.1.7

package/mcp/cli.ts

@@ -67,6 +67,7 @@ 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(
@@ -82,6 +83,8 @@ 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.')
@@ -102,6 +105,7 @@ void runExampleMcpServer({
   serverVersion: serverVersion ?? undefined,
   toolsPrefix,
   repoRoot: repoRoot ?? undefined,
+  repoName: repoName ?? undefined,
   allowedRootEndpoints,
   disableWrite,
   enableIssues,

package/mcp/manual.md

@@ -7,11 +7,11 @@ 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: `repoRoot` is a path on the **server's filesystem** (not the client/LLM). If you're unsure what the server can see, call `mcp.workspace`.
+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)
 
@@ -55,14 +55,14 @@ Tool call:
     "projectName": "<project-name>",
     "section": "spec",
     "pattern": "authentication",
-    "repoRoot": "<repo-root>",
+    "repoName": "<repo-name>",
     "ignoreCase": true,
     "maxCount": 50
   }
 }
 ```
 
-### D) `mcp.workspace` to debug repoRoot/cwd issues
+### D) `mcp.workspace` to debug repoName/repoRoot/cwd issues
 
 Tool call:
 
@@ -75,13 +75,13 @@ Tool call:
 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.
@@ -93,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>" }
 }
 ```
 
@@ -102,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>" }
 }
 ```
 
@@ -113,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 }
   }
 }
 ```
@@ -128,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
@@ -147,8 +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`).
-- **`projects.listProjects()` returns `[]` unexpectedly**: call `mcp.workspace` to confirm the server’s `cwd`/`repoRoot` and whether `/projects` exists.
+- **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

@@ -204,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 });
@@ -217,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(
@@ -226,7 +226,7 @@ describe("createExampleMcpServer request handling", () => {
 					params: {
 						name: "projects.listProjects",
 						arguments: {
-							repoRoot: tempDir,
+							repoName: "test",
 						},
 					},
 				},
@@ -243,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-"),
 		);
@@ -320,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-"),
 		);
@@ -359,7 +359,7 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
-	it("uses server default repoRoot when repoRoot is omitted", async () => {
+	it("uses server default repoRoot when repoName is omitted", async () => {
 		const tempDir = await fs.mkdtemp(
 			path.join(os.tmpdir(), "f0-mcp-server-default-reporoot-"),
 		);
@@ -424,6 +424,7 @@ describe("createExampleMcpServer request handling", () => {
 			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 {

package/mcp/server.ts

@@ -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)`,
@@ -226,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>;
@@ -451,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":
@@ -852,7 +971,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				description: "Unused.",
 				additionalProperties: true,
 			},
-			repoRoot: {
+			repoName: {
 				type: "string",
 				description: "Unused.",
 			},
@@ -862,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: [],
@@ -878,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 on the server filesystem (contains /projects and /agents). If omitted, uses the server default (auto-detected from cwd).",
+					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
 			},
 			args: {
 				type: "array",
@@ -904,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",
@@ -934,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",
@@ -1011,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",
@@ -1088,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",
@@ -1204,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",
@@ -1245,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",
@@ -1302,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",
@@ -1336,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",
@@ -1357,10 +1484,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		type: "object",
 		additionalProperties: true,
 		properties: {
-			repoRoot: {
+			repoName: {
 				type: "string",
 				description:
-					"Optional repo root on the server filesystem. If omitted, uses the server default (auto-detected by walking up from cwd). Legacy alias: processRoot.",
+					"Optional repo selector (LLM-friendly). Omit to use server default. You can also pass a server filesystem path via legacy repoRoot/processRoot.",
 			},
 		},
 		required: [],
@@ -1425,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({
@@ -1460,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: {},
@@ -1594,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;
 	}
 
@@ -1630,10 +1757,10 @@ const defaultToolInputSchema = (toolName: string) => ({
 			additionalProperties: true,
 			description: "Named options",
 		},
-		repoRoot: {
+		repoName: {
 			type: "string",
 			description:
-				'Repo root on the server filesystem (contains /projects and /agents). If omitted, uses the server default (auto-detected from cwd). 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({
@@ -1868,10 +1995,14 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 const invokeTool = async (
 	tool: ToolDefinition,
 	payload: unknown,
-	defaultRepoRoot: string,
+	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, _repoRoot) => {
@@ -1881,7 +2012,7 @@ const invokeTool = async (
 			}
 			return invocationArgs;
 		});
-	const invocationArgs = invoke(args, options, defaultRepoRoot);
+	const invocationArgs = invoke(args, options, repoCtx.defaultRepoRoot);
 
 	return Promise.resolve(tool.method(...invocationArgs));
 };
@@ -1895,6 +2026,11 @@ export interface ExampleMcpServerOptions {
 	 * 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;
@@ -2032,6 +2168,25 @@ export const createExampleMcpServer = (
 			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;
@@ -2071,7 +2226,7 @@ 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, repoRoot, projects)",
+				"- 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.',
@@ -2082,13 +2237,21 @@ export const createExampleMcpServer = (
 			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: [], repoRoot: null, processRoot: null };
-			const raw =
-				parseString(payload.repoRoot) ?? parseString(payload.processRoot);
-			const repoRoot = raw ? normalizeRepoRoot(raw) : defaultRepoRoot;
+				: { 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");
@@ -2102,8 +2265,8 @@ export const createExampleMcpServer = (
 				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 pass repoRoot explicitly.",
-						"repoRoot is a server-side path, not a client/LLM path.",
+						"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) {
@@ -2118,9 +2281,11 @@ export const createExampleMcpServer = (
 			return {
 				received,
 				cwd: process.cwd(),
-				configuredRepoRoot: options.repoRoot ?? null,
-				defaultRepoRoot,
+				defaultRepoName: repoCtx.defaultRepoName,
+				defaultRepoRoot: repoCtx.defaultRepoRoot,
+				repoName: effectiveRepoName,
 				repoRoot,
+				availableRepoNames: repoCtx.repoNames,
 				hasProjectsDir,
 				hasApiDir,
 				hasAgentsDir,
@@ -2168,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) : defaultRepoRoot;
-			})();
+			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";
@@ -2367,7 +2532,7 @@ export const createExampleMcpServer = (
 					tool: prefix
 						? `${prefix}.projects.listProjects`
 						: "projects.listProjects",
-					options: { repoRoot: "<repo-root>" },
+					options: { repoName: "<repo-name>" },
 				},
 			],
 			continueOnError: true,
@@ -2546,8 +2711,9 @@ 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.)";
-			details.suggestion = "Call mcp.workspace to see cwd/repoRoot on the server.";
+				"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 (
@@ -2556,8 +2722,9 @@ export const createExampleMcpServer = (
 			/projects[\\/]/i.test(message)
 		) {
 			details.hint =
-				"repoRoot might be wrong, or the server filesystem does not contain /projects for this repoRoot.";
-			details.suggestion = "Call mcp.workspace to see cwd/repoRoot on the server.";
+				"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: {},
@@ -2625,11 +2792,7 @@ export const createExampleMcpServer = (
 					}
 
 					try {
-						const data = await invokeTool(
-							toolDefinition,
-							{ args, options },
-							defaultRepoRoot,
-						);
+						const data = await invokeTool(toolDefinition, { args, options }, repoCtx);
 						return { index, tool, isError: false, data };
 					} catch (error) {
 						const message =
@@ -2681,7 +2844,7 @@ export const createExampleMcpServer = (
 		}
 
 		try {
-			const data = await invokeTool(tool, request.params.arguments, defaultRepoRoot);
+			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.6",
+  "version": "1.1.7",
   "description": "Foundation 0 API",
   "type": "module",
   "bin": {