@foundation0/api 1.1.11 → 1.1.12

package/mcp/manual.md

@@ -44,23 +44,27 @@ Tool call (prefixed or unprefixed names both work here):
 { "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",
-    "repoName": "<repo-name>",
-    "ignoreCase": true,
-    "maxCount": 50
-  }
-}
-```
+### C) `mcp.search` for "search docs/spec" requests
+
+Tool call:
+
+```json
+{
+  "name": "mcp.search",
+  "arguments": {
+    "section": "spec",
+    "pattern": "authentication",
+    "paths": ["."],
+    "repoName": "<repo-name>",
+    "ignoreCase": true,
+    "maxCount": 50
+  }
+}
+```
+
+Notes:
+- If only one project exists in the workspace, `projectName` is optional and will be inferred.
+- If multiple projects exist, pass `projectName` explicitly.
 
 ### D) `mcp.workspace` to debug repoName/workspaceRoot/cwd issues
 
@@ -88,14 +92,28 @@ Guideline: if a tool has a natural named parameter (`projectName`, `agentName`,
 
 ## 4) Common calls (examples)
 
-### A) List projects
+### A) List projects
 
 ```json
-{
-  "name": "projects.listProjects",
-  "arguments": { "repoName": "<repo-name>" }
-}
-```
+{
+  "name": "projects.listProjects",
+  "arguments": { "repoName": "<repo-name>" }
+}
+```
+
+### E) Search specs without `projectName` (single-project workspaces)
+
+```json
+{
+  "name": "projects.searchSpecs",
+  "arguments": {
+    "pattern": "TASK-003",
+    "paths": ["07_roadmap/phases.md"],
+    "repoName": "<repo-name>",
+    "source": "auto"
+  }
+}
+```
 
 ### B) List agents
 

package/mcp/server.test.ts

@@ -272,6 +272,103 @@ describe("createExampleMcpServer request handling", () => {
 		}
 	});
 
+	it("runs projects.searchSpecs without projectName when only one project exists", async () => {
+		const originalCwd = process.cwd();
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-searchspecs-no-project-"),
+		);
+		try {
+			await fs.mkdir(path.join(tempDir, ".git"), { recursive: true });
+			await fs.writeFile(
+				path.join(tempDir, ".git", "config"),
+				[
+					'[remote "origin"]',
+					"\turl = https://example.com/F0/adl.git",
+					"",
+				].join("\n"),
+				"utf8",
+			);
+			await fs.mkdir(path.join(tempDir, "spec", "07_roadmap"), {
+				recursive: true,
+			});
+			await fs.writeFile(
+				path.join(tempDir, "spec", "07_roadmap", "phases.md"),
+				"# Phases\n\n- TASK-003 deliver search fallback\n",
+				"utf8",
+			);
+
+			process.chdir(tempDir);
+			const instance = createExampleMcpServer();
+			const handler = getToolHandler(instance);
+
+			const result = await handler(
+				{
+					method: "tools/call",
+					params: {
+						name: "projects.searchSpecs",
+						arguments: {
+							pattern: "TASK-003",
+							paths: ["07_roadmap/phases.md"],
+							source: "auto",
+						},
+					},
+				},
+				{},
+			);
+
+			expect(result.isError).toBe(false);
+			const payload = JSON.parse(result.content?.[0]?.text ?? "{}");
+			expect(payload.ok).toBe(true);
+			expect(payload.result.section).toBe("spec");
+			expect(payload.result.source).toBe("local");
+			expect(payload.result.filesMatched).toBe(1);
+			expect(payload.result.output).toContain("TASK-003");
+		} finally {
+			process.chdir(originalCwd);
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('accepts owner/repo projectName selectors when /projects exists', async () => {
+		const originalCwd = process.cwd();
+		const tempDir = await fs.mkdtemp(
+			path.join(os.tmpdir(), "f0-mcp-server-projectname-leaf-"),
+		);
+		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, ".git"), { recursive: true });
+			await fs.writeFile(path.join(tempDir, ".git", "config"), "", "utf8");
+
+			process.chdir(tempDir);
+			const instance = createExampleMcpServer();
+			const handler = getToolHandler(instance);
+
+			const result = await handler(
+				{
+					method: "tools/call",
+					params: {
+						name: "projects.resolveProjectRoot",
+						arguments: {
+							projectName: "F0/adl",
+						},
+					},
+				},
+				{},
+			);
+
+			expect(result.isError).toBe(false);
+			const payload = JSON.parse(result.content?.[0]?.text ?? "{}");
+			expect(payload.ok).toBe(true);
+			expect(payload.result).toBe(path.join(path.resolve(tempDir), "projects", "adl"));
+		} finally {
+			process.chdir(originalCwd);
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
 	it("parses owner/repo repoName into repo segment even without full-name metadata", async () => {
 		const originalCwd = process.cwd();
 		const tempDir = await fs.mkdtemp(

package/mcp/server.ts

@@ -602,9 +602,23 @@ const coercePayloadForTool = (
 		)
 			return;
 		const name = popStringOption(options, "projectName", "project");
-		if (name) {
-			if (args.length === 0) args.push(name);
-			else args[0] = name;
+		const fallback = (() => {
+			if (name) return null;
+			const repoName =
+				typeof options.repoName === "string" ? options.repoName.trim() : "";
+			if (!repoName) return null;
+			const leaf = repoName
+				.split(/[\\/]/)
+				.map((part) => part.trim())
+				.filter((part) => part.length > 0)
+				.at(-1);
+			if (!leaf || leaf === "." || leaf === "..") return null;
+			return leaf;
+		})();
+		const resolvedName = name ?? fallback;
+		if (resolvedName) {
+			if (args.length === 0) args.push(resolvedName);
+			else args[0] = resolvedName;
 		}
 	};
 
@@ -664,7 +678,12 @@ const coercePayloadForTool = (
 		rgArgs.push(pattern, ...(paths.length > 0 ? paths : ["."]));
 
 		if (args.length === 0) {
-			// Can't build without projectName; leave for underlying error.
+			// If projectName is omitted, preserve the rg args via options.args so
+			// projects.searchDocs/searchSpecs can run in seed-options mode.
+			// (projectName will be inferred when only one project exists).
+			if (!Array.isArray(options.args) || options.args.length === 0) {
+				options.args = rgArgs;
+			}
 			return;
 		}
 
@@ -673,13 +692,17 @@ const coercePayloadForTool = (
 		}
 	};
 
-	switch (toolName) {
-		case "projects.listProjects": {
-			// No positional args. processRoot is injected from the selected repoName.
+		switch (toolName) {
+			case "projects.listProjects": {
+				// No positional args. processRoot is injected from the selected repoName.
+				break;
+			}
+		case "projects.resolveProjectRoot":
+		case "projects.listProjectDocs": {
+			coerceProjectName();
+			ensureArg0(null);
 			break;
 		}
-		case "projects.resolveProjectRoot":
-		case "projects.listProjectDocs":
 		case "projects.fetchGitTasks":
 		case "projects.createGitIssue": {
 			coerceProjectName();
@@ -695,7 +718,11 @@ const coercePayloadForTool = (
 				"docPath",
 			);
 			if (requestPath) {
-				ensureArgs(args[0] ?? undefined, requestPath);
+				if (args.length === 0) {
+					args.push(null, requestPath);
+				} else if (args.length === 1) {
+					args.push(requestPath);
+				}
 			}
 			break;
 		}
@@ -1100,7 +1127,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		properties: {
 			projectName: {
 				type: "string",
-				description: 'Project name under /projects (e.g. "adl").',
+				description:
+					'Project name. In a monorepo: folder under /projects (e.g. "adl"). Optional when only one project exists.',
 			},
 			repoName: {
 				type: "string",
@@ -1118,7 +1146,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				additionalProperties: true,
 			},
 		},
-		required: ["projectName"],
+		required: [],
 	},
 	"projects.listProjectDocs": {
 		type: "object",
@@ -1126,7 +1154,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		properties: {
 			projectName: {
 				type: "string",
-				description: 'Project name under /projects (e.g. "adl").',
+				description:
+					'Project name. In a monorepo: folder under /projects (e.g. "adl"). Optional when only one project exists.',
 			},
 			repoName: {
 				type: "string",
@@ -1144,7 +1173,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				additionalProperties: true,
 			},
 		},
-		required: ["projectName"],
+		required: [],
 	},
 	"projects.readProjectDoc": {
 		type: "object",
@@ -1152,7 +1181,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		properties: {
 			projectName: {
 				type: "string",
-				description: 'Project name under /projects (e.g. "adl").',
+				description:
+					'Project name. In a monorepo: folder under /projects (e.g. "adl"). Optional when only one project exists.',
 			},
 			requestPath: {
 				type: "string",
@@ -1175,7 +1205,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				additionalProperties: true,
 			},
 		},
-		required: ["projectName", "requestPath"],
+		required: ["requestPath"],
 	},
 	"projects.searchDocs": {
 		type: "object",
@@ -1183,7 +1213,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		properties: {
 			projectName: {
 				type: "string",
-				description: 'Project name under /projects (e.g. "adl").',
+				description:
+					'Project name. In a monorepo: folder under /projects (e.g. "adl"). Optional when only one project exists.',
 			},
 			pattern: {
 				type: "string",
@@ -1244,7 +1275,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			},
 			args: {
 				type: "array",
-				description: "Legacy rg-like args (projectName, PATTERN, [PATH...]).",
+				description:
+					"Legacy rg-like args ([projectName], PATTERN, [PATH...]). projectName may be omitted when only one project exists.",
 				items: {},
 			},
 			options: {
@@ -1253,7 +1285,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				additionalProperties: true,
 			},
 		},
-		required: ["projectName"],
+		required: [],
 	},
 	"projects.searchSpecs": {
 		type: "object",
@@ -1261,7 +1293,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		properties: {
 			projectName: {
 				type: "string",
-				description: 'Project name under /projects (e.g. "adl").',
+				description:
+					'Project name. In a monorepo: folder under /projects (e.g. "adl"). Optional when only one project exists.',
 			},
 			pattern: {
 				type: "string",
@@ -1322,7 +1355,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			},
 			args: {
 				type: "array",
-				description: "Legacy rg-like args (projectName, PATTERN, [PATH...]).",
+				description:
+					"Legacy rg-like args ([projectName], PATTERN, [PATH...]). projectName may be omitted when only one project exists.",
 				items: {},
 			},
 			options: {
@@ -1331,7 +1365,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 				additionalProperties: true,
 			},
 		},
-		required: ["projectName"],
+		required: [],
 	},
 	"projects.parseProjectTargetSpec": {
 		type: "object",
@@ -1606,7 +1640,8 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 		properties: {
 			projectName: {
 				type: "string",
-				description: 'Project name under /projects (e.g. "adl").',
+				description:
+					'Project name. In a monorepo: folder under /projects (e.g. "adl"). Optional when only one project exists.',
 			},
 			section: {
 				type: "string",
@@ -2365,9 +2400,9 @@ export const createExampleMcpServer = (
 			const hint = (() => {
 				if (!hasProjectsDir) {
 					return [
-						"Git workspace does not contain /projects.",
-						"Pass repoName as \"adl\" or \"F0/adl\".",
-						"For single-repo layouts, use source:\"auto\" or source:\"gitea\" on search tools.",
+						"Git workspace does not contain /projects (single-repo layout).",
+						"Search tools can omit projectName; it will be inferred when only one project exists.",
+						'Use repoName like "adl" or "F0/adl" when needed.',
 					].join(" ");
 				}
 				if (hasProjectsDir && projects.length === 0) {

package/package.json

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

package/projects.ts

@@ -304,31 +304,46 @@ export function usage(): string {
     `The active file created is [file].active.<ext>.\n`
 }
 
-export function resolveProjectRoot(projectName: string, processRoot: string = process.cwd()): string {
-  if (!projectName || projectName.trim().length === 0) {
+export function resolveProjectRoot(projectNameInput: string, processRoot: string = process.cwd()): string {
+  const resolvedProcessRoot = path.resolve(processRoot)
+
+  const rawProjectName = typeof projectNameInput === 'string' ? projectNameInput.trim() : ''
+  const inferredProjectName = rawProjectName.length > 0 ? rawProjectName : null
+  const projectName = inferredProjectName ?? (() => {
+    const projects = listProjects(resolvedProcessRoot)
+    if (projects.length === 1) {
+      return projects[0]
+    }
+    if (projects.length > 1) {
+      throw new Error(`project-name is required. Available projects: ${projects.join(', ')}`)
+    }
     throw new Error('project-name is required.')
-  }
+  })()
 
-  const normalized = projectName.trim().replace(/[\\/]+/g, path.sep)
+  const normalized = projectName.replace(/[\\/]+/g, path.sep)
   if (normalized === '.' || normalized === '..' || normalized.includes(path.sep + '..') || normalized.includes('..')) {
     throw new Error('project-name may not include path traversal.')
   }
 
-  const resolvedProcessRoot = path.resolve(processRoot)
-  const projectRoot = path.join(resolveProjectsRoot(resolvedProcessRoot), normalized)
+  const projectsRoot = resolveProjectsRoot(resolvedProcessRoot)
+  const projectRoot = path.join(projectsRoot, normalized)
   if (!existsDir(projectRoot)) {
-    const identity = resolveProjectRepoIdentity(resolvedProcessRoot)
-    const normalizedKey = normalized.replace(/\\/g, '/').toLowerCase()
-    const normalizedLeaf = normalized.split(path.sep).filter(Boolean).at(-1)?.toLowerCase() ?? null
-    const aliases = [
-      identity?.repo?.toLowerCase() ?? null,
-      identity?.owner && identity?.repo ? `${identity.owner}/${identity.repo}`.toLowerCase() : null,
-      path.basename(resolvedProcessRoot).toLowerCase(),
-    ].filter((value): value is string => Boolean(value))
-    const hasAliasMatch = aliases.some((alias) => alias === normalizedKey || alias === normalizedLeaf)
+    if (normalized.includes(path.sep)) {
+      const leaf = normalized.split(path.sep).filter(Boolean).at(-1)
+      if (leaf && leaf !== normalized) {
+        const leafRoot = path.join(projectsRoot, leaf)
+        if (existsDir(leafRoot)) {
+          return leafRoot
+        }
+      }
+    }
 
-    if (hasAliasMatch) {
-      return resolvedProcessRoot
+    if (!existsDir(projectsRoot)) {
+      const hasSingleRepoDocs = existsDir(path.join(resolvedProcessRoot, 'docs'))
+      const hasSingleRepoSpec = existsDir(path.join(resolvedProcessRoot, 'spec'))
+      if (hasSingleRepoDocs || hasSingleRepoSpec) {
+        return resolvedProcessRoot
+    }
     }
 
     throw new Error(`Project folder not found: ${projectRoot}`)
@@ -411,11 +426,18 @@ async function searchProjectSection(
   const optionProjectName = parseStringOption(options.projectName) ?? ''
   const sourcePreference = parseSearchSourceOption(options.source, options.remote)
 
-  if (!positionalProjectName && !optionProjectName) {
-    throw new Error('Missing project name. Pass it as first arg or options.projectName.')
-  }
-
   let projectName = positionalProjectName || optionProjectName
+
+  if (!projectName) {
+    const candidates = listProjects(processRoot)
+    if (candidates.length === 1) {
+      projectName = candidates[0]
+    } else if (candidates.length > 1) {
+      throw new Error(`Missing project name. Available projects: ${candidates.join(', ')}`)
+    } else {
+      throw new Error('Missing project name. Pass it as first arg or options.projectName.')
+    }
+  }
   let projectRoot: string | null = null
 
   if (positionalProjectName && optionProjectName && positionalProjectName !== optionProjectName) {