@foundation0/api 1.1.3 → 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 () => {