@foundation0/api 1.1.4 → 1.1.6

package/mcp/cli.ts

@@ -67,6 +67,8 @@ 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 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 +82,9 @@ if (hasFlag('--help') || hasFlag('-h')) {
   console.log('  --server-name <name>')
   console.log('  --server-version <version>')
   console.log('  --tools-prefix <prefix>')
+  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 +101,7 @@ void runExampleMcpServer({
   serverName: serverName ?? undefined,
   serverVersion: serverVersion ?? undefined,
   toolsPrefix,
+  repoRoot: repoRoot ?? undefined,
   allowedRootEndpoints,
   disableWrite,
   enableIssues,

package/mcp/manual.md

@@ -0,0 +1,161 @@
+# Foundation0 MCP Tool-Calling Manual (for LLMs)
+
+This is a **tool-calling guide** for the Foundation0 MCP server in `api/mcp/*`.
+Assume the server is already configured in your MCP host and you can call its tools.
+
+## 0) Golden rules
+
+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).
+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`.
+
+## 1) Tool naming (prefixes + aliases)
+
+Depending on how the server was started, tool names may be:
+
+- unprefixed: `projects.listProjects`
+- prefixed: `api.projects.listProjects`
+
+The server usually exposes both when a prefix is set, but do not assume: **discover at runtime** via `mcp.listTools`.
+
+Some tools also have OpenAI-safe underscore aliases (no dots). Example:
+
+- `net.curl` may also be available as `net_curl`
+
+## 2) The 4 discovery calls
+
+### A) List all tools
+
+Tool call:
+
+```json
+{ "name": "mcp.listTools", "arguments": {} }
+```
+
+### B) Describe one tool (schema + example)
+
+Tool call (prefixed or unprefixed names both work here):
+
+```json
+{ "name": "mcp.describeTool", "arguments": { "args": ["projects.listProjects"] } }
+```
+
+### C) `mcp.search` for "search docs/spec" requests
+
+Tool call:
+
+```json
+{
+  "name": "mcp.search",
+  "arguments": {
+    "projectName": "<project-name>",
+    "section": "spec",
+    "pattern": "authentication",
+    "repoRoot": "<repo-root>",
+    "ignoreCase": true,
+    "maxCount": 50
+  }
+}
+```
+
+### D) `mcp.workspace` to debug 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>" } }
+```
+
+or named keys (recommended). The server merges top-level keys into `options`:
+
+```json
+{ "projectName": "<project-name>", "repoRoot": "<repo-root>" }
+```
+
+Guideline: if a tool has a natural named parameter (`projectName`, `agentName`, `target`, `taskRef`), pass it explicitly.
+
+## 4) Common calls (examples)
+
+### A) List projects
+
+```json
+{
+  "name": "projects.listProjects",
+  "arguments": { "repoRoot": "<repo-root>" }
+}
+```
+
+### B) List agents
+
+```json
+{
+  "name": "agents.listAgents",
+  "arguments": { "repoRoot": "<repo-root>" }
+}
+```
+
+### C) Set an active file (projects)
+
+```json
+{
+  "name": "projects.setActive",
+  "arguments": {
+    "args": ["<project-name>", "/implementation-plan.v0.0.1"],
+    "options": { "repoRoot": "<repo-root>", "latest": true }
+  }
+}
+```
+
+### D) Batch multiple calls
+
+Call `batch` (or `<prefix>.batch`) to run multiple tool calls:
+
+```json
+{
+  "name": "batch",
+  "arguments": {
+    "calls": [
+      { "tool": "projects.usage" },
+      { "tool": "projects.listProjects", "options": { "repoRoot": "<repo-root>" } }
+    ],
+    "continueOnError": true,
+    "maxConcurrency": 4
+  }
+}
+```
+
+## 5) Reading responses (envelopes + errors)
+
+Tool results are returned as text containing JSON like:
+
+- success: `{ "ok": true, "result": ... }`
+- error: `{ "ok": false, "error": { "message": "...", "details": { ... } } }`
+
+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.
+
+## 6) Tool availability (read/write/admin)
+
+The server can be started in modes that hide tools:
+
+- read-only mode removes write-capable tools
+- admin-only tools are hidden unless the server is started in admin mode
+- root namespaces can be whitelisted (so entire namespaces may be missing)
+
+If a tool is not listed by `mcp.listTools`, you cannot call it in the current server configuration.

package/mcp/server.test.ts

@@ -32,9 +32,18 @@ describe("createExampleMcpServer endpoint whitelist", () => {
 		const names = instance.tools.map((tool) => tool.name);
 
 		expect(names.length).toBeGreaterThan(0);
-		expect(names.every((name) => name.startsWith("projects."))).toBe(true);
+		expect(
+			names.every(
+				(name) => name.startsWith("projects.") || name.startsWith("mcp."),
+			),
+		).toBe(true);
 		expect(names.some((name) => name.startsWith("agents."))).toBe(false);
 		expect(names.some((name) => name.startsWith("net."))).toBe(false);
+		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");
 	});
 
 	it("throws on unknown root endpoints", () => {
@@ -77,12 +86,21 @@ describe("createExampleMcpServer endpoint whitelist", () => {
 		const names = instance.tools.map((tool) => tool.name);
 
 		expect(names.length).toBeGreaterThan(0);
-		expect(names.every((name) => name.startsWith("projects."))).toBe(true);
+		expect(
+			names.every(
+				(name) => name.startsWith("projects.") || name.startsWith("mcp."),
+			),
+		).toBe(true);
 		expect(names).toContain("projects.readGitTask");
 		expect(names).toContain("projects.fetchGitTasks");
 		expect(names).not.toContain("projects.createGitIssue");
 		expect(names).not.toContain("projects.writeGitTask");
 		expect(names).not.toContain("projects.syncTasks");
+		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");
 	});
 
 	it("re-enables issue write endpoints when enableIssues=true with disableWrite", () => {
@@ -186,6 +204,233 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
+	it("accepts repoRoot for projects tools (preferred over legacy processRoot)", async () => {
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-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();
+			const handler = getToolHandler(instance);
+
+			const result = await handler(
+				{
+					method: "tools/call",
+					params: {
+						name: "projects.listProjects",
+						arguments: {
+							repoRoot: tempDir,
+						},
+					},
+				},
+				{},
+			);
+
+			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("auto-detects repoRoot from process.cwd() when repoRoot is omitted", async () => {
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-autoreporoot-"),
+		);
+		const originalCwd = process.cwd();
+
+		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,
+			});
+
+			process.chdir(tempDir);
+
+			const instance = createExampleMcpServer();
+			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 {
+			process.chdir(originalCwd);
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it("still accepts legacy processRoot for backwards compatibility", async () => {
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-processroot-"),
+		);
+		try {
+			await fs.mkdir(path.join(tempDir, "api"), { recursive: true });
+			await fs.mkdir(path.join(tempDir, "projects", "adl", "docs"), {
+				recursive: true,
+			});
+
+			const instance = createExampleMcpServer();
+			const handler = getToolHandler(instance);
+
+			const result = await handler(
+				{
+					method: "tools/call",
+					params: {
+						name: "projects.listProjects",
+						arguments: {
+							processRoot: tempDir,
+						},
+					},
+				},
+				{},
+			);
+
+			expect(result.isError).toBe(false);
+			const payload = JSON.parse(result.content?.[0]?.text ?? "{}");
+			expect(payload.ok).toBe(true);
+			expect(payload.result).toContain("adl");
+		} finally {
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it("normalizes repoRoot when caller accidentally passes a project root", async () => {
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-reporoot-normalize-"),
+		);
+		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();
+			const handler = getToolHandler(instance);
+
+			const result = await handler(
+				{
+					method: "tools/call",
+					params: {
+						name: "projects.listProjects",
+						arguments: {
+							repoRoot: path.join(tempDir, "projects", "adl"),
+						},
+					},
+				},
+				{},
+			);
+
+			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("uses server default repoRoot when repoRoot 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.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);
@@ -256,7 +501,10 @@ describe("createExampleMcpServer request handling", () => {
 		const payload = JSON.parse(result.content?.[0]?.text ?? "{}");
 		expect(payload.ok).toBe(true);
 		expect(typeof payload.result).toBe("string");
-		expect(payload.result).toContain("Usage");
+		expect(payload.result).toContain("MCP");
+		expect(payload.result).toContain("projects.listProjects");
+		expect(payload.result).not.toContain("f0 projects");
+		expect(payload.result).not.toContain("--generate-spec");
 	});
 
 	it("exposes mcp.describeTool for tool discovery", async () => {

package/mcp/server.ts

@@ -48,6 +48,51 @@ type ApiEndpoint = {
 	mcp: ToolNamespace;
 };
 
+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}`),
+);
+
+const formatToolNameForUsage = (
+	toolName: string,
+	toolsPrefix: string | undefined,
+): string => (toolsPrefix ? `${toolsPrefix}.${toolName}` : toolName);
+
+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 } }`,
+		"",
+		"Discovery:",
+		`- ${tool("mcp.listTools")}: list available tools (and their schemas)`,
+		`- ${tool("mcp.describeTool")}: { args: [\"projects.generateSpec\"] } for schema + example`,
+		"",
+		"Payload shape:",
+		"- Prefer { args: [...], options: {...} }. Top-level keys are also treated as options.",
+	].join("\n");
+};
+
+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 } }`,
+		"",
+		"Discovery:",
+		`- ${tool("mcp.listTools")}: list available tools (and their schemas)`,
+		`- ${tool("mcp.describeTool")}: { args: [\"agents.setActive\"] } for schema + example`,
+		"",
+		"Payload shape:",
+		"- Prefer { args: [...], options: {...} }. Top-level keys are also treated as options.",
+	].join("\n");
+};
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
 	typeof value === "object" && value !== null && !Array.isArray(value);
 
@@ -131,11 +176,11 @@ const isDir = (candidate: string): boolean => {
 const looksLikeRepoRoot = (candidate: string): boolean =>
 	isDir(path.join(candidate, "projects")) && isDir(path.join(candidate, "api"));
 
-const normalizeProcessRoot = (raw: string): string => {
+const normalizeRepoRoot = (raw: string): string => {
 	const resolved = path.resolve(raw);
 	if (looksLikeRepoRoot(resolved)) return resolved;
 
-	// Common mistake: passing a project root like ".../projects/adl" as processRoot.
+	// Common mistake: passing a project root like ".../projects/adl" as repoRoot.
 	// Try to find the containing repo root by walking up a few levels.
 	let current = resolved;
 	for (let depth = 0; depth < 8; depth += 1) {
@@ -155,14 +200,30 @@ const normalizeProcessRoot = (raw: string): string => {
 	return resolved;
 };
 
-const normalizeProcessRootOption = (
+const normalizeRepoRootOption = (
 	options: Record<string, unknown>,
 ): Record<string, unknown> => {
-	const raw = options.processRoot;
-	if (typeof raw !== "string" || raw.trim().length === 0) return options;
-	const normalized = normalizeProcessRoot(raw.trim());
-	if (normalized === raw) return options;
-	return { ...options, processRoot: normalized };
+	const rawRepoRoot = typeof options.repoRoot === "string" ? options.repoRoot : null;
+	const rawProcessRoot =
+		typeof options.processRoot === "string" ? options.processRoot : null;
+	const raw = rawRepoRoot ?? rawProcessRoot;
+
+	if (typeof raw !== "string" || raw.trim().length === 0) {
+		const next = { ...options };
+		delete next.repoRoot;
+		delete next.processRoot;
+		return next;
+	}
+
+	const trimmed = raw.trim();
+	const normalized = normalizeRepoRoot(trimmed);
+
+	const next: Record<string, unknown> = { ...options, repoRoot: normalized };
+	delete next.processRoot;
+
+	const alreadyCanonical =
+		rawRepoRoot !== null && rawRepoRoot === normalized && !("processRoot" in options);
+	return alreadyCanonical ? options : next;
 };
 
 type NormalizedToolPayload = {
@@ -283,7 +344,7 @@ const normalizePayload = (payload: unknown): NormalizedToolPayload => {
 
 	return {
 		args,
-		options: normalizeProcessRootOption(options),
+		options: normalizeRepoRootOption(options),
 	};
 };
 
@@ -390,7 +451,7 @@ const coercePayloadForTool = (
 
 	switch (toolName) {
 		case "projects.listProjects": {
-			// No positional args. processRoot is handled via options.processRoot + buildProcessRootOnly.
+			// No positional args. repoRoot is handled via options.repoRoot + buildRepoRootOnly.
 			break;
 		}
 		case "projects.resolveProjectRoot":
@@ -480,7 +541,7 @@ const coercePayloadForTool = (
 			break;
 	}
 
-	return { args, options: normalizeProcessRootOption(options) };
+	return { args, options: normalizeRepoRootOption(options) };
 };
 
 const normalizeBatchToolCall = (
@@ -791,7 +852,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				description: "Unused.",
 				additionalProperties: true,
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Unused.",
 			},
@@ -801,7 +862,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		type: "object",
 		additionalProperties: true,
 		properties: {
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description:
 					'Repo root containing /projects and /agents. If you have a project root like ".../projects/adl", omit this or pass its parent.',
@@ -817,10 +878,10 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: 'Project name under /projects (e.g. "adl").',
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description:
-					"Repo root containing /projects and /agents. If omitted, uses server cwd.",
+					"Repo root on the server filesystem (contains /projects and /agents). If omitted, uses the server default (auto-detected from cwd).",
 			},
 			args: {
 				type: "array",
@@ -843,7 +904,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: 'Project name under /projects (e.g. "adl").',
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects and /agents.",
 			},
@@ -873,7 +934,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				description:
 					'Doc path under docs/, starting with "docs/..." (or a bare filename in catalog).',
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects and /agents.",
 			},
@@ -950,7 +1011,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Remote repo override for gitea mode.",
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects and /agents.",
 			},
@@ -1027,7 +1088,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Remote repo override for gitea mode.",
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects and /agents.",
 			},
@@ -1143,7 +1204,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "boolean",
 				description: "If true, only return issues with TASK-* IDs.",
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects.",
 			},
@@ -1184,7 +1245,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "boolean",
 				description: "If true, restrict to issues with TASK-* payloads.",
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects.",
 			},
@@ -1241,7 +1302,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Optional task signature.",
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects.",
 			},
@@ -1275,7 +1336,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				items: { type: "string" },
 				description: "Labels to set.",
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Repo root containing /projects.",
 			},
@@ -1292,6 +1353,21 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		},
 		required: ["projectName", "title"],
 	},
+	"mcp.workspace": {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			repoRoot: {
+				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.",
+			},
+		},
+		required: [],
+		$comment: safeJsonStringify({
+			example: {},
+		}),
+	},
 	"mcp.search": {
 		type: "object",
 		additionalProperties: true,
@@ -1349,7 +1425,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				type: "string",
 				description: "Optional override cache directory.",
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description:
 					"Repo root containing /projects. If you pass a project root, it will be normalized.",
@@ -1384,7 +1460,7 @@ const buildArgsSchemaFromPlaceholders = (
 const TOOL_ARGS_SCHEMA_OVERRIDES: Record<string, Record<string, unknown>> = {
 	"projects.listProjects": {
 		type: "array",
-		description: "No positional arguments. Use options.processRoot if needed.",
+		description: "No positional arguments. Use options.repoRoot if needed.",
 		minItems: 0,
 		maxItems: 0,
 		items: {},
@@ -1499,9 +1575,9 @@ const getInvocationPlanName = (toolName: string): string => {
 	const plan = toolInvocationPlans[toolName];
 	if (!plan) return "default";
 	if (plan === buildOptionsOnly) return "optionsOnly";
-	if (plan === buildOptionsThenProcessRoot) return "optionsThenProcessRoot";
-	if (plan === buildProcessRootThenOptions) return "processRootThenOptions";
-	if (plan === buildProcessRootOnly) return "processRootOnly";
+	if (plan === buildOptionsThenRepoRoot) return "optionsThenRepoRoot";
+	if (plan === buildRepoRootThenOptions) return "repoRootThenOptions";
+	if (plan === buildRepoRootOnly) return "repoRootOnly";
 	return "custom";
 };
 
@@ -1513,17 +1589,17 @@ const buildInvocationExample = (toolName: string): Record<string, unknown> => {
 	const example: Record<string, unknown> = {};
 	if (requiredArgs && requiredArgs.length > 0) {
 		example.args = [...requiredArgs];
-	} else if (plan !== "processRootOnly") {
+	} else if (plan !== "repoRootOnly") {
 		example.args = ["<arg0>"];
 	}
 
-	if (plan === "processRootOnly") {
-		example.options = { processRoot: "<repo-root>", ...defaultOptions };
+	if (plan === "repoRootOnly") {
+		example.options = { repoRoot: "<repo-root>", ...defaultOptions };
 		return example;
 	}
 
-	if (plan === "optionsThenProcessRoot" || plan === "processRootThenOptions") {
-		example.options = { processRoot: "<repo-root>", ...defaultOptions };
+	if (plan === "optionsThenRepoRoot" || plan === "repoRootThenOptions") {
+		example.options = { repoRoot: "<repo-root>", ...defaultOptions };
 		return example;
 	}
 
@@ -1554,10 +1630,10 @@ const defaultToolInputSchema = (toolName: string) => ({
 			additionalProperties: true,
 			description: "Named options",
 		},
-		processRoot: {
+		repoRoot: {
 			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 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.',
 		},
 	},
 	$comment: safeJsonStringify({
@@ -1673,11 +1749,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) {
@@ -1686,44 +1764,44 @@ const buildOptionsOnly = (
 	return invocationArgs;
 };
 
-const buildOptionsThenProcessRoot = (
+const buildOptionsThenRepoRoot = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
-	const processRoot = remaining.processRoot;
-	if (typeof processRoot === "string") {
-		delete remaining.processRoot;
+	const repoRoot = remaining.repoRoot;
+	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 processRoot === "string") {
-		// Preserve positional slot for signatures like fn(projectName, options?, processRoot?).
+	} else if (resolvedRepoRoot) {
+		// Preserve positional slot for signatures like fn(projectName, options?, repoRoot?).
 		invocationArgs.push({});
 	}
-	if (typeof processRoot === "string") {
-		invocationArgs.push(processRoot);
-	}
+	invocationArgs.push(resolvedRepoRoot);
 
 	return invocationArgs;
 };
 
-const buildProcessRootThenOptions = (
+const buildRepoRootThenOptions = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
-	const processRoot = remaining.processRoot;
-	if (typeof processRoot === "string") {
-		delete remaining.processRoot;
+	const repoRoot = remaining.repoRoot;
+	if (typeof repoRoot === "string") {
+		delete remaining.repoRoot;
 	}
 
-	if (typeof processRoot === "string") {
-		invocationArgs.push(processRoot);
-	}
+	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
 	}
@@ -1731,39 +1809,38 @@ const buildProcessRootThenOptions = (
 	return invocationArgs;
 };
 
-const buildProcessRootOnly = (
+const buildRepoRootOnly = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
-	const processRoot = options.processRoot;
-	if (typeof processRoot === "string") {
-		invocationArgs.push(processRoot);
-	}
+	const repoRoot = options.repoRoot;
+	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
 	return invocationArgs;
 };
 
 const toolInvocationPlans: Record<string, ToolInvoker> = {
-	"agents.setActive": buildProcessRootThenOptions,
-	"agents.resolveAgentsRootFrom": buildProcessRootOnly,
-	"projects.setActive": buildProcessRootThenOptions,
-	"projects.generateSpec": buildOptionsThenProcessRoot,
-	"projects.syncTasks": buildOptionsThenProcessRoot,
-	"projects.clearIssues": buildOptionsThenProcessRoot,
-	"projects.fetchGitTasks": buildOptionsThenProcessRoot,
-	"projects.createGitIssue": buildOptionsThenProcessRoot,
-	"projects.readGitTask": buildOptionsThenProcessRoot,
-	"projects.writeGitTask": buildOptionsThenProcessRoot,
+	"agents.setActive": buildRepoRootThenOptions,
+	"agents.resolveAgentsRootFrom": buildRepoRootOnly,
+	"projects.setActive": buildRepoRootThenOptions,
+	"projects.generateSpec": buildOptionsThenRepoRoot,
+	"projects.syncTasks": buildOptionsThenRepoRoot,
+	"projects.clearIssues": buildOptionsThenRepoRoot,
+	"projects.fetchGitTasks": buildOptionsThenRepoRoot,
+	"projects.createGitIssue": buildOptionsThenRepoRoot,
+	"projects.readGitTask": buildOptionsThenRepoRoot,
+	"projects.writeGitTask": buildOptionsThenRepoRoot,
 	"agents.resolveTargetFile": buildOptionsOnly,
 	"projects.resolveProjectTargetFile": buildOptionsOnly,
-	"agents.loadAgent": buildProcessRootOnly,
-	"agents.loadAgentPrompt": buildProcessRootOnly,
-	"projects.resolveImplementationPlan": (args, options) => {
+	"agents.loadAgent": buildRepoRootOnly,
+	"agents.loadAgentPrompt": buildRepoRootOnly,
+	"projects.resolveImplementationPlan": (args, options, _defaultRepoRoot) => {
 		const invocationArgs: unknown[] = [...args];
 		const remaining = { ...options };
-		const processRoot = remaining.processRoot;
-		if (typeof processRoot === "string") {
-			delete remaining.processRoot;
+		const repoRoot = remaining.repoRoot;
+		if (typeof repoRoot === "string") {
+			delete remaining.repoRoot;
 		}
 
 		// This tool is a low-level helper: projects.resolveImplementationPlan(projectRoot, inputFile?, options?)
@@ -1775,35 +1852,36 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 			invocationArgs.push(remaining);
 		}
 
-		// Intentionally do NOT append processRoot: projectRoot is the first positional argument.
+		// Intentionally do NOT append repoRoot: projectRoot is the first positional argument.
 		return invocationArgs;
 	},
-	"agents.main": buildProcessRootOnly,
-	"agents.resolveAgentsRoot": buildProcessRootOnly,
-	"agents.listAgents": buildProcessRootOnly,
-	"projects.resolveProjectRoot": buildProcessRootOnly,
-	"projects.listProjects": buildProcessRootOnly,
-	"projects.listProjectDocs": buildProcessRootOnly,
-	"projects.readProjectDoc": buildProcessRootOnly,
-	"projects.main": buildProcessRootOnly,
+	"agents.main": buildRepoRootOnly,
+	"agents.resolveAgentsRoot": buildRepoRootOnly,
+	"agents.listAgents": buildRepoRootOnly,
+	"projects.resolveProjectRoot": buildRepoRootOnly,
+	"projects.listProjects": buildRepoRootOnly,
+	"projects.listProjectDocs": buildRepoRootOnly,
+	"projects.readProjectDoc": buildRepoRootOnly,
+	"projects.main": buildRepoRootOnly,
 };
 
 const invokeTool = async (
 	tool: ToolDefinition,
 	payload: unknown,
+	defaultRepoRoot: string,
 ): Promise<unknown> => {
 	const normalized = normalizePayload(payload);
 	const { args, options } = coercePayloadForTool(tool.name, normalized);
 	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, defaultRepoRoot);
 
 	return Promise.resolve(tool.method(...invocationArgs));
 };
@@ -1812,6 +1890,11 @@ 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;
 	allowedRootEndpoints?: string[];
 	disableWrite?: boolean;
 	enableIssues?: boolean;
@@ -1852,6 +1935,7 @@ const READ_ONLY_TOOL_NAMES = new Set<string>([
 	"mcp.usage",
 	"mcp.listTools",
 	"mcp.describeTool",
+	"mcp.workspace",
 	"mcp.search",
 ]);
 
@@ -1942,6 +2026,12 @@ 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 parseString = (value: unknown): string | null => {
 		if (typeof value !== "string") return null;
@@ -1981,11 +2071,63 @@ 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.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),
+						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;
+
+			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 pass repoRoot explicitly.",
+						"repoRoot is a server-side path, not a client/LLM path.",
+					].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(),
+				configuredRepoRoot: options.repoRoot ?? null,
+				defaultRepoRoot,
+				repoRoot,
+				hasProjectsDir,
+				hasApiDir,
+				hasAgentsDir,
+				projects,
+				hint,
+			};
+		},
 		describeTool: (toolName: string) => {
 			const normalized = typeof toolName === "string" ? toolName.trim() : "";
 			if (!normalized) {
@@ -2026,9 +2168,10 @@ export const createExampleMcpServer = (
 		},
 		search: async (input: unknown) => {
 			const payload = isRecord(input) ? input : {};
-			const processRoot = (() => {
-				const raw = parseString(payload.processRoot);
-				return raw ? normalizeProcessRoot(raw) : process.cwd();
+			const repoRoot = (() => {
+				const raw =
+					parseString(payload.repoRoot) ?? parseString(payload.processRoot);
+				return raw ? normalizeRepoRoot(raw) : defaultRepoRoot;
 			})();
 
 			const sectionRaw = parseString(payload.section)?.toLowerCase();
@@ -2076,11 +2219,11 @@ export const createExampleMcpServer = (
 
 			const projectName = ensureProjectName(
 				parseString(payload.projectName),
-				processRoot,
+				repoRoot,
 			);
 
 			const searchOptions: Record<string, unknown> = {
-				processRoot,
+				processRoot: repoRoot,
 			};
 
 			const source = parseString(payload.source)?.toLowerCase();
@@ -2106,9 +2249,15 @@ export const createExampleMcpServer = (
 	} satisfies ToolNamespace;
 
 	const api: ApiEndpoint = {
-		agents: agentsApi,
+		agents: {
+			...agentsApi,
+			usage: () => buildAgentsMcpUsage(options.toolsPrefix),
+		},
 		net: netApi,
-		projects: projectsApi,
+		projects: {
+			...projectsApi,
+			usage: () => buildProjectsMcpUsage(options.toolsPrefix),
+		},
 		mcp: mcpApi,
 	};
 
@@ -2140,7 +2289,18 @@ export const createExampleMcpServer = (
 	const selectedTools = selectedRoots.flatMap((root) =>
 		collectTools(api[root], [root]),
 	);
-	const selectedToolsWithAliases = applyToolAliases(selectedTools);
+	const selectedToolsWithMcpHelpers = (() => {
+		if (selectedRoots.includes("mcp")) return selectedTools;
+		const helperApi: Partial<Record<McpHelperToolKey, unknown>> = {};
+		for (const key of MCP_HELPER_TOOL_KEYS) {
+			helperApi[key] = (mcpApi as any)[key];
+		}
+		const helperTools = collectTools(helperApi as ToolNamespace, ["mcp"]).filter(
+			(tool) => MCP_HELPER_TOOL_NAMES.has(tool.name),
+		);
+		return [...helperTools, ...selectedTools];
+	})();
+	const selectedToolsWithAliases = applyToolAliases(selectedToolsWithMcpHelpers);
 	buildToolMeta(selectedToolsWithAliases);
 	const adminFilteredTools = Boolean(options.admin)
 		? selectedToolsWithAliases
@@ -2207,7 +2367,7 @@ export const createExampleMcpServer = (
 					tool: prefix
 						? `${prefix}.projects.listProjects`
 						: "projects.listProjects",
-					options: { processRoot: "<repo-root>" },
+					options: { repoRoot: "<repo-root>" },
 				},
 			],
 			continueOnError: true,
@@ -2386,7 +2546,22 @@ export const createExampleMcpServer = (
 			/projects[\\/].+projects[\\/]/i.test(message)
 		) {
 			details.hint =
-				"You likely passed a project root as processRoot. processRoot should be the repo root containing /projects.";
+				"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.";
+		}
+
+		if (
+			/Project folder not found:/i.test(message) &&
+			!details.hint &&
+			/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.";
+			details.example = {
+				tool: prefix ? `${prefix}.mcp.workspace` : "mcp.workspace",
+				arguments: {},
+			};
 		}
 
 		if (/Missing search pattern\./i.test(message)) {
@@ -2450,7 +2625,11 @@ export const createExampleMcpServer = (
 					}
 
 					try {
-						const data = await invokeTool(toolDefinition, { args, options });
+						const data = await invokeTool(
+							toolDefinition,
+							{ args, options },
+							defaultRepoRoot,
+						);
 						return { index, tool, isError: false, data };
 					} catch (error) {
 						const message =
@@ -2502,7 +2681,7 @@ export const createExampleMcpServer = (
 		}
 
 		try {
-			const data = await invokeTool(tool, request.params.arguments);
+			const data = await invokeTool(tool, request.params.arguments, defaultRepoRoot);
 			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.4",
+  "version": "1.1.6",
   "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\"",