@foundation0/api 1.1.4 → 1.1.5

package/mcp/manual.md

@@ -0,0 +1,150 @@
+# 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`.
+
+## 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 3 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
+  }
+}
+```
+
+## 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`).
+
+## 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,17 @@ 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).not.toContain("mcp.search");
 	});
 
 	it("throws on unknown root endpoints", () => {
@@ -77,12 +85,20 @@ 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).not.toContain("mcp.search");
 	});
 
 	it("re-enables issue write endpoints when enableIssues=true with disableWrite", () => {
@@ -186,6 +202,161 @@ 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('parses continueOnError from string "false" (fails fast)', async () => {
 		const instance = createExampleMcpServer();
 		const handler = getToolHandler(instance);
@@ -256,7 +427,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"] 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,22 @@ 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 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;
 
-	// 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 +211,28 @@ 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 detected = detectRepoRootFromCwd();
+		return detected ? { ...options, repoRoot: detected } : options;
+	}
+
+	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 +353,7 @@ const normalizePayload = (payload: unknown): NormalizedToolPayload => {
 
 	return {
 		args,
-		options: normalizeProcessRootOption(options),
+		options: normalizeRepoRootOption(options),
 	};
 };
 
@@ -390,7 +460,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 +550,7 @@ const coercePayloadForTool = (
 			break;
 	}
 
-	return { args, options: normalizeProcessRootOption(options) };
+	return { args, options: normalizeRepoRootOption(options) };
 };
 
 const normalizeBatchToolCall = (
@@ -791,7 +861,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				description: "Unused.",
 				additionalProperties: true,
 			},
-			processRoot: {
+			repoRoot: {
 				type: "string",
 				description: "Unused.",
 			},
@@ -801,7 +871,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,7 +887,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. If omitted, uses server cwd.",
@@ -843,7 +913,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 +943,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 +1020,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 +1097,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 +1213,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 +1254,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 +1311,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 +1345,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.",
 			},
@@ -1349,7 +1419,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 +1454,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 +1569,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 +1583,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,7 +1624,7 @@ 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.',
@@ -1686,43 +1756,43 @@ const buildOptionsOnly = (
 	return invocationArgs;
 };
 
-const buildOptionsThenProcessRoot = (
+const buildOptionsThenRepoRoot = (
 	args: unknown[],
 	options: Record<string, unknown>,
 ): 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 (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 (typeof repoRoot === "string") {
+		// Preserve positional slot for signatures like fn(projectName, options?, repoRoot?).
 		invocationArgs.push({});
 	}
-	if (typeof processRoot === "string") {
-		invocationArgs.push(processRoot);
+	if (typeof repoRoot === "string") {
+		invocationArgs.push(repoRoot);
 	}
 
 	return invocationArgs;
 };
 
-const buildProcessRootThenOptions = (
+const buildRepoRootThenOptions = (
 	args: unknown[],
 	options: Record<string, unknown>,
 ): 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);
+	if (typeof repoRoot === "string") {
+		invocationArgs.push(repoRoot);
 	}
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
@@ -1731,39 +1801,39 @@ const buildProcessRootThenOptions = (
 	return invocationArgs;
 };
 
-const buildProcessRootOnly = (
+const buildRepoRootOnly = (
 	args: unknown[],
 	options: Record<string, unknown>,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
-	const processRoot = options.processRoot;
-	if (typeof processRoot === "string") {
-		invocationArgs.push(processRoot);
+	const repoRoot = options.repoRoot;
+	if (typeof repoRoot === "string") {
+		invocationArgs.push(repoRoot);
 	}
 	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,
+	"agents.loadAgent": buildRepoRootOnly,
+	"agents.loadAgentPrompt": buildRepoRootOnly,
 	"projects.resolveImplementationPlan": (args, options) => {
 		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,17 +1845,17 @@ 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 (
@@ -2026,9 +2096,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) : process.cwd();
 			})();
 
 			const sectionRaw = parseString(payload.section)?.toLowerCase();
@@ -2076,11 +2147,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 +2177,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 +2217,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 +2295,7 @@ export const createExampleMcpServer = (
 					tool: prefix
 						? `${prefix}.projects.listProjects`
 						: "projects.listProjects",
-					options: { processRoot: "<repo-root>" },
+					options: { repoRoot: "<repo-root>" },
 				},
 			],
 			continueOnError: true,
@@ -2386,7 +2474,7 @@ 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.)";
 		}
 
 		if (/Missing search pattern\./i.test(message)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundation0/api",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Foundation 0 API",
   "type": "module",
   "bin": {