@foundation0/api 1.1.5 → 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

@@ -11,6 +11,8 @@ Assume the server is already configured in your MCP host and you can call its to
 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:
@@ -24,7 +26,7 @@ Some tools also have OpenAI-safe underscore aliases (no dots). Example:
 
 - `net.curl` may also be available as `net_curl`
 
-## 2) The 3 discovery calls
+## 2) The 4 discovery calls
 
 ### A) List all tools
 
@@ -60,6 +62,14 @@ Tool call:
 }
 ```
 
+### D) `mcp.workspace` to debug repoRoot/cwd issues
+
+Tool call:
+
+```json
+{ "name": "mcp.workspace", "arguments": {} }
+```
+
 ## 3) Payload shapes (important)
 
 Most tools accept either:
@@ -138,6 +148,7 @@ 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)
 

package/mcp/server.test.ts

@@ -42,6 +42,7 @@ describe("createExampleMcpServer endpoint whitelist", () => {
 		expect(names).toContain("mcp.usage");
 		expect(names).toContain("mcp.listTools");
 		expect(names).toContain("mcp.describeTool");
+		expect(names).toContain("mcp.workspace");
 		expect(names).not.toContain("mcp.search");
 	});
 
@@ -98,6 +99,7 @@ describe("createExampleMcpServer endpoint whitelist", () => {
 		expect(names).toContain("mcp.usage");
 		expect(names).toContain("mcp.listTools");
 		expect(names).toContain("mcp.describeTool");
+		expect(names).toContain("mcp.workspace");
 		expect(names).not.toContain("mcp.search");
 	});
 
@@ -357,6 +359,78 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
+	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);

package/mcp/server.ts

@@ -48,7 +48,7 @@ type ApiEndpoint = {
 	mcp: ToolNamespace;
 };
 
-const MCP_HELPER_TOOL_KEYS = ["usage", "listTools", "describeTool"] as const;
+const MCP_HELPER_TOOL_KEYS = ["usage", "listTools", "describeTool", "workspace"] as const;
 type McpHelperToolKey = (typeof MCP_HELPER_TOOL_KEYS)[number];
 const MCP_HELPER_TOOL_NAMES = new Set<string>(
 	MCP_HELPER_TOOL_KEYS.map((key) => `mcp.${key}`),
@@ -176,17 +176,6 @@ const isDir = (candidate: string): boolean => {
 const looksLikeRepoRoot = (candidate: string): boolean =>
 	isDir(path.join(candidate, "projects")) && isDir(path.join(candidate, "api"));
 
-const detectRepoRootFromCwd = (): string | null => {
-	let current = process.cwd();
-	for (let depth = 0; depth < 12; depth += 1) {
-		if (looksLikeRepoRoot(current)) return current;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	return null;
-};
-
 const normalizeRepoRoot = (raw: string): string => {
 	const resolved = path.resolve(raw);
 	if (looksLikeRepoRoot(resolved)) return resolved;
@@ -220,8 +209,10 @@ const normalizeRepoRootOption = (
 	const raw = rawRepoRoot ?? rawProcessRoot;
 
 	if (typeof raw !== "string" || raw.trim().length === 0) {
-		const detected = detectRepoRootFromCwd();
-		return detected ? { ...options, repoRoot: detected } : options;
+		const next = { ...options };
+		delete next.repoRoot;
+		delete next.processRoot;
+		return next;
 	}
 
 	const trimmed = raw.trim();
@@ -890,7 +881,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			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",
@@ -1362,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,
@@ -1627,7 +1633,7 @@ const defaultToolInputSchema = (toolName: string) => ({
 		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({
@@ -1743,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) {
@@ -1759,6 +1767,7 @@ const buildOptionsOnly = (
 const buildOptionsThenRepoRoot = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
@@ -1766,16 +1775,16 @@ const buildOptionsThenRepoRoot = (
 	if (typeof repoRoot === "string") {
 		delete remaining.repoRoot;
 	}
+	const resolvedRepoRoot =
+		typeof repoRoot === "string" ? repoRoot : defaultRepoRoot;
 
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
-	} else if (typeof repoRoot === "string") {
+	} else if (resolvedRepoRoot) {
 		// Preserve positional slot for signatures like fn(projectName, options?, repoRoot?).
 		invocationArgs.push({});
 	}
-	if (typeof repoRoot === "string") {
-		invocationArgs.push(repoRoot);
-	}
+	invocationArgs.push(resolvedRepoRoot);
 
 	return invocationArgs;
 };
@@ -1783,6 +1792,7 @@ const buildOptionsThenRepoRoot = (
 const buildRepoRootThenOptions = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
@@ -1791,9 +1801,7 @@ const buildRepoRootThenOptions = (
 		delete remaining.repoRoot;
 	}
 
-	if (typeof repoRoot === "string") {
-		invocationArgs.push(repoRoot);
-	}
+	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
 	}
@@ -1804,12 +1812,11 @@ const buildRepoRootThenOptions = (
 const buildRepoRootOnly = (
 	args: unknown[],
 	options: Record<string, unknown>,
+	defaultRepoRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const repoRoot = options.repoRoot;
-	if (typeof repoRoot === "string") {
-		invocationArgs.push(repoRoot);
-	}
+	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
 	return invocationArgs;
 };
 
@@ -1828,7 +1835,7 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 	"projects.resolveProjectTargetFile": buildOptionsOnly,
 	"agents.loadAgent": buildRepoRootOnly,
 	"agents.loadAgentPrompt": buildRepoRootOnly,
-	"projects.resolveImplementationPlan": (args, options) => {
+	"projects.resolveImplementationPlan": (args, options, _defaultRepoRoot) => {
 		const invocationArgs: unknown[] = [...args];
 		const remaining = { ...options };
 		const repoRoot = remaining.repoRoot;
@@ -1861,19 +1868,20 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 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));
 };
@@ -1882,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;
@@ -1922,6 +1935,7 @@ const READ_ONLY_TOOL_NAMES = new Set<string>([
 	"mcp.usage",
 	"mcp.listTools",
 	"mcp.describeTool",
+	"mcp.workspace",
 	"mcp.search",
 ]);
 
@@ -2012,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;
@@ -2051,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) {
@@ -2099,7 +2171,7 @@ export const createExampleMcpServer = (
 			const repoRoot = (() => {
 				const raw =
 					parseString(payload.repoRoot) ?? parseString(payload.processRoot);
-				return raw ? normalizeRepoRoot(raw) : process.cwd();
+				return raw ? normalizeRepoRoot(raw) : defaultRepoRoot;
 			})();
 
 			const sectionRaw = parseString(payload.section)?.toLowerCase();
@@ -2475,6 +2547,21 @@ export const createExampleMcpServer = (
 		) {
 			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.";
+		}
+
+		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)) {
@@ -2538,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 =
@@ -2590,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.5",
+  "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\"",