@foundation0/api 1.1.8 → 1.1.10

package/mcp/server.ts

@@ -174,9 +174,6 @@ const isDir = (candidate: string): boolean => {
 	}
 };
 
-const looksLikeRepoRoot = (candidate: string): boolean =>
-	isDir(path.join(candidate, "projects")) && isDir(path.join(candidate, "api"));
-
 const fileExists = (candidate: string): boolean => {
 	try {
 		fs.statSync(candidate);
@@ -198,8 +195,8 @@ const findGitRepoRoot = (startDir: string): string | null => {
 	return null;
 };
 
-const resolveGitDir = (repoRoot: string): string | null => {
-	const dotGit = path.join(repoRoot, ".git");
+const resolveGitDir = (workspaceRoot: string): string | null => {
+	const dotGit = path.join(workspaceRoot, ".git");
 	if (isDir(dotGit)) return dotGit;
 	if (!fileExists(dotGit)) return null;
 
@@ -209,14 +206,22 @@ const resolveGitDir = (repoRoot: string): string | null => {
 		if (!match) return null;
 		const raw = match[1].trim();
 		if (!raw) return null;
-		const resolved = path.resolve(repoRoot, raw);
+		const resolved = path.resolve(workspaceRoot, raw);
 		return isDir(resolved) ? resolved : null;
 	} catch {
 		return null;
 	}
 };
 
-const parseRepoNameFromRemoteUrl = (remoteUrl: string): string | null => {
+type GitRemoteIdentity = {
+	owner: string | null;
+	repo: string;
+	fullName: string | null;
+};
+
+const parseGitRemoteIdentityFromUrl = (
+	remoteUrl: string,
+): GitRemoteIdentity | null => {
 	const trimmed = remoteUrl.trim();
 	if (!trimmed) return null;
 
@@ -225,11 +230,34 @@ const parseRepoNameFromRemoteUrl = (remoteUrl: string): string | null => {
 	const withoutGit = withoutQuery.endsWith(".git")
 		? withoutQuery.slice(0, -4)
 		: withoutQuery;
+	const normalized = withoutGit.replace(/\\/g, "/");
+	const scpPathMatch = normalized.match(/^[^@]+@[^:]+:(.+)$/);
+	let pathPart = scpPathMatch?.[1] ?? normalized;
 
-	const lastSep = Math.max(withoutGit.lastIndexOf("/"), withoutGit.lastIndexOf(":"));
-	const candidate = (lastSep >= 0 ? withoutGit.slice(lastSep + 1) : withoutGit).trim();
-	if (!candidate) return null;
-	return candidate;
+	if (!scpPathMatch) {
+		try {
+			const url = new URL(normalized);
+			pathPart = url.pathname;
+		} catch {
+			// Keep normalized value as-is.
+		}
+	}
+
+	const cleanPath = pathPart.replace(/^\/+|\/+$/g, "");
+	if (!cleanPath) return null;
+	const segments = cleanPath
+		.split("/")
+		.map((segment) => segment.trim())
+		.filter((segment) => segment.length > 0);
+	if (segments.length === 0) return null;
+	const repo = segments[segments.length - 1];
+	if (!repo) return null;
+	const owner = segments.length > 1 ? segments[segments.length - 2] : null;
+	return {
+		owner,
+		repo,
+		fullName: owner ? `${owner}/${repo}` : null,
+	};
 };
 
 const readGitRemoteUrl = (gitDir: string): string | null => {
@@ -267,114 +295,55 @@ const readGitRemoteUrl = (gitDir: string): string | null => {
 	}
 };
 
-const detectRepoNameFromGitConfig = (repoRoot: string): string | null => {
-	const gitDir = resolveGitDir(repoRoot);
+const detectRepoIdentityFromGitConfig = (
+	workspaceRoot: string,
+): GitRemoteIdentity | null => {
+	const gitDir = resolveGitDir(workspaceRoot);
 	if (!gitDir) return null;
 	const remoteUrl = readGitRemoteUrl(gitDir);
 	if (!remoteUrl) return null;
-	return parseRepoNameFromRemoteUrl(remoteUrl);
+	return parseGitRemoteIdentityFromUrl(remoteUrl);
 };
 
-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 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) {
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		if (looksLikeRepoRoot(parent)) return parent;
-		current = parent;
-	}
-
-	const parts = resolved.split(path.sep).filter((part) => part.length > 0);
-	const projectsIndex = parts.lastIndexOf("projects");
-	if (projectsIndex >= 0) {
-		const candidate = parts.slice(0, projectsIndex).join(path.sep);
-		if (candidate && looksLikeRepoRoot(candidate)) return candidate;
-	}
-
-	return resolved;
-};
-
-const normalizeRepoRootOption = (
-	options: Record<string, unknown>,
-): Record<string, unknown> => {
-	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;
-};
-
-const looksLikePathish = (value: string): boolean => {
-	const trimmed = value.trim();
-	if (!trimmed) return false;
-	if (/^[a-zA-Z]:[\\/]/.test(trimmed)) return true;
-	return trimmed.includes("/") || trimmed.includes("\\") || trimmed.startsWith(".");
+type RepoResolutionContext = {
+	defaultProcessRoot: string;
+	defaultRepoName: string;
+	defaultRepoFullName: string | null;
+	repoNames: string[];
+	repoNameByKey: Record<string, string>;
 };
 
-const parseRepoMap = (raw: string | undefined): Record<string, string> => {
-	const input = typeof raw === "string" ? raw.trim() : "";
-	if (!input) return {};
-
-	if (input.startsWith("{")) {
-		try {
-			const parsed = JSON.parse(input);
-			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-				return {};
-			}
-			const out: Record<string, string> = {};
-			for (const [name, root] of Object.entries(parsed)) {
-				if (!name || typeof root !== "string" || !root.trim()) continue;
-				out[name.trim()] = root.trim();
-			}
-			return out;
-		} catch {
-			return {};
-		}
-	}
+const repoNameKey = (value: string): string => value.trim().toLowerCase();
 
-	const entries = input
-		.split(/[;,]/g)
-		.map((entry) => entry.trim())
-		.filter((entry) => entry.length > 0);
-
-	const out: Record<string, string> = {};
-	for (const entry of entries) {
-		const [name, root] = entry.split("=", 2);
-		if (!name || !root) continue;
-		const key = name.trim();
-		const value = root.trim();
-		if (!key || !value) continue;
-		out[key] = value;
+const uniqueStrings = (values: Array<string | null | undefined>): string[] => {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const value of values) {
+		if (!value) continue;
+		const trimmed = value.trim();
+		if (!trimmed) continue;
+		const key = repoNameKey(trimmed);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(trimmed);
 	}
 	return out;
 };
 
-type RepoResolutionContext = {
-	defaultRepoRoot: string;
-	defaultRepoName: string;
-	repoMapByKey: Record<string, string>;
-	repoNames: string[];
+const buildRepoNameContext = (
+	defaultRepoName: string,
+	defaultRepoFullName: string | null,
+): { repoNames: string[]; repoNameByKey: Record<string, string> } => {
+	const repoNames = uniqueStrings([
+		defaultRepoName,
+		defaultRepoFullName,
+		defaultRepoFullName?.split("/").at(-1) ?? null,
+	]);
+	const repoNameByKey: Record<string, string> = {};
+	for (const name of repoNames) {
+		repoNameByKey[repoNameKey(name)] = name;
+	}
+	return { repoNames, repoNameByKey };
 };
 
 const resolveRepoSelectorOptions = (
@@ -382,68 +351,100 @@ const resolveRepoSelectorOptions = (
 	ctx: RepoResolutionContext,
 ): Record<string, unknown> => {
 	const next: Record<string, unknown> = { ...options };
-
-	const explicitRoot =
-		(typeof next.repoRoot === "string" && next.repoRoot.trim().length > 0
-			? next.repoRoot.trim()
-			: null) ??
-		(typeof next.processRoot === "string" && next.processRoot.trim().length > 0
-			? next.processRoot.trim()
-			: null);
-
-	if (explicitRoot) {
-		next.repoRoot = normalizeRepoRoot(explicitRoot);
-		delete next.processRoot;
-		delete next.repoName;
-		return next;
-	}
+	delete next.repoRoot;
+	delete next.processRoot;
 
 	const repoName =
 		typeof next.repoName === "string" && next.repoName.trim().length > 0
 			? next.repoName.trim()
 			: null;
 	if (!repoName) {
-		delete next.processRoot;
+		next.processRoot = ctx.defaultProcessRoot;
 		return next;
 	}
 
-	if (looksLikePathish(repoName)) {
-		next.repoRoot = normalizeRepoRoot(repoName);
-		delete next.processRoot;
-		delete next.repoName;
+	const needle = repoNameKey(repoName);
+	const canonical = ctx.repoNameByKey[needle];
+	if (canonical) {
+		next.processRoot = ctx.defaultProcessRoot;
+		next.repoName = canonical;
 		return next;
 	}
 
-	const needle = repoName.toLowerCase();
-	if (needle === ctx.defaultRepoName.toLowerCase()) {
-		next.repoRoot = ctx.defaultRepoRoot;
-		delete next.processRoot;
-		delete next.repoName;
+	if (ctx.defaultRepoFullName && needle === repoNameKey(ctx.defaultRepoFullName)) {
+		next.processRoot = ctx.defaultProcessRoot;
+		next.repoName = ctx.defaultRepoFullName;
 		return next;
 	}
 
-	const mapped = ctx.repoMapByKey[needle];
-	if (mapped) {
-		next.repoRoot = normalizeRepoRoot(mapped);
-		delete next.processRoot;
-		delete next.repoName;
+	if (needle === repoNameKey(ctx.defaultRepoName)) {
+		next.processRoot = ctx.defaultProcessRoot;
+		next.repoName = ctx.defaultRepoName;
 		return next;
 	}
 
+	const slashParts = repoName.split("/").filter((part) => part.trim().length > 0);
+	if (slashParts.length >= 2) {
+		const repoSegment = slashParts[slashParts.length - 1]?.trim();
+		if (repoSegment) {
+			const matched = ctx.repoNameByKey[repoNameKey(repoSegment)];
+			if (matched) {
+				next.processRoot = ctx.defaultProcessRoot;
+				next.repoName = matched;
+				return next;
+			}
+		}
+	}
+
 	const suggestions = ctx.repoNames
-		.filter((name) => name.toLowerCase().includes(needle))
+		.filter((name) => repoNameKey(name).includes(needle))
 		.slice(0, 8);
 	const hint =
 		suggestions.length > 0
 			? ` Did you mean: ${suggestions.join(", ")}?`
-			: ctx.repoNames.length > 0
-				? ` Available repos: ${ctx.repoNames.join(", ")}.`
-				: "";
+			: ` Available repoName values: ${ctx.repoNames.join(", ")}.`;
 	throw new Error(
-		`Unknown repoName: ${repoName}.${hint} Tip: call mcp.workspace to see the server repo context.`,
+		`Unknown repoName: ${repoName}.${hint} Tip: use "adl" or "F0/adl" style selectors.`,
 	);
 };
 
+const normalizeRepoNameForDisplay = (
+	requestedRepoName: string | null,
+	ctx: RepoResolutionContext,
+): string => {
+	if (!requestedRepoName) return ctx.defaultRepoName;
+	const canonical = ctx.repoNameByKey[repoNameKey(requestedRepoName)];
+	return canonical ?? requestedRepoName;
+};
+
+const resolveProcessRootFromGit = (fallbackDir: string): string => {
+	const cwdRoot = findGitRepoRoot(process.cwd());
+	if (cwdRoot) return cwdRoot;
+	const fallbackRoot = findGitRepoRoot(fallbackDir);
+	if (fallbackRoot) return fallbackRoot;
+	return path.resolve(process.cwd());
+};
+
+const resolveRepoIdentityFromGit = (
+	processRoot: string,
+): {
+	defaultRepoName: string;
+	defaultRepoFullName: string | null;
+} => {
+	const gitIdentity = detectRepoIdentityFromGitConfig(processRoot);
+	if (gitIdentity) {
+		return {
+			defaultRepoName: gitIdentity.repo,
+			defaultRepoFullName: gitIdentity.fullName,
+		};
+	}
+
+	return {
+		defaultRepoName: path.basename(processRoot),
+		defaultRepoFullName: null,
+	};
+};
+
 type NormalizedToolPayload = {
 	args: unknown[];
 	options: Record<string, unknown>;
@@ -562,7 +563,7 @@ const normalizePayload = (payload: unknown): NormalizedToolPayload => {
 
 	return {
 		args,
-		options: normalizeRepoRootOption(options),
+		options,
 	};
 };
 
@@ -669,7 +670,7 @@ const coercePayloadForTool = (
 
 	switch (toolName) {
 		case "projects.listProjects": {
-			// No positional args. repoRoot is resolved from repoName/repoRoot/processRoot and passed via buildRepoRootOnly.
+			// No positional args. processRoot is injected from the selected repoName.
 			break;
 		}
 		case "projects.resolveProjectRoot":
@@ -759,7 +760,7 @@ const coercePayloadForTool = (
 			break;
 	}
 
-	return { args, options: normalizeRepoRootOption(options) };
+	return { args, options };
 };
 
 const normalizeBatchToolCall = (
@@ -1099,7 +1100,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1125,7 +1126,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1156,7 +1157,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1234,7 +1235,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1312,7 +1313,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1429,7 +1430,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1471,7 +1472,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1529,7 +1530,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1564,7 +1565,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 			args: {
 				type: "array",
@@ -1586,7 +1587,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Optional repo selector (LLM-friendly). Omit to use server default. You can also pass a server filesystem path via legacy repoRoot/processRoot.",
+					'Optional repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 		},
 		required: [],
@@ -1654,7 +1655,7 @@ const TOOL_INPUT_SCHEMA_OVERRIDES: Record<string, unknown> = {
 			repoName: {
 				type: "string",
 				description:
-					"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+					'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 			},
 		},
 		$comment: safeJsonStringify({
@@ -1801,9 +1802,9 @@ const getInvocationPlanName = (toolName: string): string => {
 	const plan = toolInvocationPlans[toolName];
 	if (!plan) return "default";
 	if (plan === buildOptionsOnly) return "optionsOnly";
-	if (plan === buildOptionsThenRepoRoot) return "optionsThenRepoRoot";
-	if (plan === buildRepoRootThenOptions) return "repoRootThenOptions";
-	if (plan === buildRepoRootOnly) return "repoRootOnly";
+	if (plan === buildOptionsThenProcessRoot) return "optionsThenProcessRoot";
+	if (plan === buildProcessRootThenOptions) return "processRootThenOptions";
+	if (plan === buildProcessRootOnly) return "processRootOnly";
 	return "custom";
 };
 
@@ -1815,16 +1816,16 @@ const buildInvocationExample = (toolName: string): Record<string, unknown> => {
 	const example: Record<string, unknown> = {};
 	if (requiredArgs && requiredArgs.length > 0) {
 		example.args = [...requiredArgs];
-	} else if (plan !== "repoRootOnly") {
+	} else if (plan !== "processRootOnly") {
 		example.args = ["<arg0>"];
 	}
 
-	if (plan === "repoRootOnly") {
+	if (plan === "processRootOnly") {
 		example.options = { repoName: "<repo-name>", ...defaultOptions };
 		return example;
 	}
 
-	if (plan === "optionsThenRepoRoot" || plan === "repoRootThenOptions") {
+	if (plan === "optionsThenProcessRoot" || plan === "processRootThenOptions") {
 		example.options = { repoName: "<repo-name>", ...defaultOptions };
 		return example;
 	}
@@ -1859,7 +1860,7 @@ const defaultToolInputSchema = (toolName: string) => ({
 		repoName: {
 			type: "string",
 			description:
-				"Repo selector (LLM-friendly). Omit to use server default. Legacy path aliases: repoRoot/processRoot.",
+				'Repo selector. Accepts "<repo>" or "<owner>/<repo>". Omit to use the current Git workspace.',
 		},
 	},
 	$comment: safeJsonStringify({
@@ -1975,13 +1976,13 @@ const buildToolList = (
 type ToolInvoker = (
 	args: unknown[],
 	options: Record<string, unknown>,
-	defaultRepoRoot: string,
+	defaultProcessRoot: string,
 ) => unknown[];
 
 const buildOptionsOnly = (
 	args: unknown[],
 	options: Record<string, unknown>,
-	_defaultRepoRoot: string,
+	_defaultProcessRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	if (Object.keys(options).length > 0) {
@@ -1990,44 +1991,48 @@ const buildOptionsOnly = (
 	return invocationArgs;
 };
 
-const buildOptionsThenRepoRoot = (
+const buildOptionsThenProcessRoot = (
 	args: unknown[],
 	options: Record<string, unknown>,
-	defaultRepoRoot: string,
+	defaultProcessRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
-	const repoRoot = remaining.repoRoot;
-	if (typeof repoRoot === "string") {
-		delete remaining.repoRoot;
+	const processRoot = remaining.processRoot;
+	if (typeof processRoot === "string") {
+		delete remaining.processRoot;
 	}
-	const resolvedRepoRoot =
-		typeof repoRoot === "string" ? repoRoot : defaultRepoRoot;
+	delete remaining.repoRoot;
+	const resolvedProcessRoot =
+		typeof processRoot === "string" ? processRoot : defaultProcessRoot;
 
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
-	} else if (resolvedRepoRoot) {
-		// Preserve positional slot for signatures like fn(projectName, options?, repoRoot?).
+	} else if (resolvedProcessRoot) {
+		// Preserve positional slot for signatures like fn(projectName, options?, processRoot?).
 		invocationArgs.push({});
 	}
-	invocationArgs.push(resolvedRepoRoot);
+	invocationArgs.push(resolvedProcessRoot);
 
 	return invocationArgs;
 };
 
-const buildRepoRootThenOptions = (
+const buildProcessRootThenOptions = (
 	args: unknown[],
 	options: Record<string, unknown>,
-	defaultRepoRoot: string,
+	defaultProcessRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
 	const remaining = { ...options };
-	const repoRoot = remaining.repoRoot;
-	if (typeof repoRoot === "string") {
-		delete remaining.repoRoot;
+	const processRoot = remaining.processRoot;
+	if (typeof processRoot === "string") {
+		delete remaining.processRoot;
 	}
+	delete remaining.repoRoot;
 
-	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
+	invocationArgs.push(
+		typeof processRoot === "string" ? processRoot : defaultProcessRoot,
+	);
 	if (Object.keys(remaining).length > 0) {
 		invocationArgs.push(remaining);
 	}
@@ -2035,39 +2040,42 @@ const buildRepoRootThenOptions = (
 	return invocationArgs;
 };
 
-const buildRepoRootOnly = (
+const buildProcessRootOnly = (
 	args: unknown[],
 	options: Record<string, unknown>,
-	defaultRepoRoot: string,
+	defaultProcessRoot: string,
 ): unknown[] => {
 	const invocationArgs: unknown[] = [...args];
-	const repoRoot = options.repoRoot;
-	invocationArgs.push(typeof repoRoot === "string" ? repoRoot : defaultRepoRoot);
+	const processRoot = options.processRoot;
+	invocationArgs.push(
+		typeof processRoot === "string" ? processRoot : defaultProcessRoot,
+	);
 	return invocationArgs;
 };
 
 const toolInvocationPlans: Record<string, ToolInvoker> = {
-	"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.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.resolveTargetFile": buildOptionsOnly,
 	"projects.resolveProjectTargetFile": buildOptionsOnly,
-	"agents.loadAgent": buildRepoRootOnly,
-	"agents.loadAgentPrompt": buildRepoRootOnly,
-	"projects.resolveImplementationPlan": (args, options, _defaultRepoRoot) => {
+	"agents.loadAgent": buildProcessRootOnly,
+	"agents.loadAgentPrompt": buildProcessRootOnly,
+	"projects.resolveImplementationPlan": (args, options, _defaultProcessRoot) => {
 		const invocationArgs: unknown[] = [...args];
 		const remaining = { ...options };
-		const repoRoot = remaining.repoRoot;
-		if (typeof repoRoot === "string") {
-			delete remaining.repoRoot;
+		const processRoot = remaining.processRoot;
+		if (typeof processRoot === "string") {
+			delete remaining.processRoot;
 		}
+		delete remaining.repoRoot;
 
 		// This tool is a low-level helper: projects.resolveImplementationPlan(projectRoot, inputFile?, options?)
 		// If the caller provides options but no inputFile, preserve the positional slot.
@@ -2078,17 +2086,17 @@ const toolInvocationPlans: Record<string, ToolInvoker> = {
 			invocationArgs.push(remaining);
 		}
 
-		// Intentionally do NOT append repoRoot: projectRoot is the first positional argument.
+		// Intentionally do NOT append processRoot: projectRoot is the first positional argument.
 		return invocationArgs;
 	},
-	"agents.main": buildRepoRootOnly,
-	"agents.resolveAgentsRoot": buildRepoRootOnly,
-	"agents.listAgents": buildRepoRootOnly,
-	"projects.resolveProjectRoot": buildRepoRootOnly,
-	"projects.listProjects": buildRepoRootOnly,
-	"projects.listProjectDocs": buildRepoRootOnly,
-	"projects.readProjectDoc": buildRepoRootOnly,
-	"projects.main": buildRepoRootOnly,
+	"agents.main": buildProcessRootOnly,
+	"agents.resolveAgentsRoot": buildProcessRootOnly,
+	"agents.listAgents": buildProcessRootOnly,
+	"projects.resolveProjectRoot": buildProcessRootOnly,
+	"projects.listProjects": buildProcessRootOnly,
+	"projects.listProjectDocs": buildProcessRootOnly,
+	"projects.readProjectDoc": buildProcessRootOnly,
+	"projects.main": buildProcessRootOnly,
 };
 
 const invokeTool = async (
@@ -2104,14 +2112,14 @@ const invokeTool = async (
 	};
 	const invoke =
 		toolInvocationPlans[tool.name] ??
-		((rawArgs, rawOptions, _repoRoot) => {
+		((rawArgs, rawOptions, _processRoot) => {
 			const invocationArgs = [...rawArgs];
 			if (Object.keys(rawOptions).length > 0) {
 				invocationArgs.push(rawOptions);
 			}
 			return invocationArgs;
 		});
-	const invocationArgs = invoke(args, options, repoCtx.defaultRepoRoot);
+	const invocationArgs = invoke(args, options, repoCtx.defaultProcessRoot);
 
 	return Promise.resolve(tool.method(...invocationArgs));
 };
@@ -2121,13 +2129,8 @@ export interface ExampleMcpServerOptions {
 	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;
-	/**
-	 * Optional default repo name (LLM-friendly identifier).
-	 * If omitted, defaults to the basename of the resolved repo root.
+	 * Optional default repo selector (for MCP repoName matching).
+	 * If omitted, auto-detected from git remote (fallback: workspace folder name).
 	 */
 	repoName?: string;
 	allowedRootEndpoints?: string[];
@@ -2262,48 +2265,23 @@ export const createExampleMcpServer = (
 ): ExampleMcpServerInstance => {
 	let toolCatalog: unknown[] = [];
 
-	const configuredRepoRoot =
-		options.repoRoot ?? process.env.MCP_REPO_ROOT ?? process.env.F0_REPO_ROOT;
-	const cwd = process.cwd();
-	const cwdNormalized = normalizeRepoRoot(cwd);
-	const cwdLooksLikeRepoRoot = looksLikeRepoRoot(cwdNormalized);
-	const cwdGitRoot = findGitRepoRoot(cwd);
 	const serverFileDir = path.dirname(fileURLToPath(import.meta.url));
-	const serverFileGitRoot = findGitRepoRoot(serverFileDir);
-
-	const rawDefaultRepoRoot =
-		configuredRepoRoot ??
-		(cwdLooksLikeRepoRoot ? cwdNormalized : null) ??
-		cwdGitRoot ??
-		serverFileGitRoot ??
-		cwd ??
-		serverFileDir;
-	const defaultRepoRoot = normalizeRepoRoot(rawDefaultRepoRoot);
-
-	const configuredRepoName =
-		(options.repoName ?? process.env.MCP_REPO_NAME ?? process.env.F0_REPO_NAME)?.trim() ||
-		null;
-	const gitDerivedRepoName =
-		detectRepoNameFromGitConfig(defaultRepoRoot) ??
-		(cwdGitRoot ? detectRepoNameFromGitConfig(cwdGitRoot) : null) ??
-		(serverFileGitRoot ? detectRepoNameFromGitConfig(serverFileGitRoot) : null);
-	const defaultRepoName =
-		configuredRepoName || gitDerivedRepoName || path.basename(defaultRepoRoot);
-	const repoMapRaw = process.env.MCP_REPOS ?? process.env.F0_REPOS;
-	const repoMap = {
-		...parseRepoMap(repoMapRaw),
-		[defaultRepoName]: defaultRepoRoot,
-	};
-	const repoNames = Object.keys(repoMap).sort((a, b) => a.localeCompare(b));
-	const repoMapByKey: Record<string, string> = {};
-	for (const [name, root] of Object.entries(repoMap)) {
-		repoMapByKey[name.toLowerCase()] = root;
-	}
+	const defaultProcessRoot = resolveProcessRootFromGit(serverFileDir);
+	const configuredRepoName = options.repoName?.trim() || null;
+	const resolvedRepoIdentity = resolveRepoIdentityFromGit(defaultProcessRoot);
+	const defaultRepoName = configuredRepoName || resolvedRepoIdentity.defaultRepoName;
+	const defaultRepoFullName = resolvedRepoIdentity.defaultRepoFullName;
+	const { repoNames, repoNameByKey } = buildRepoNameContext(
+		defaultRepoName,
+		defaultRepoFullName,
+	);
+
 	const repoCtx: RepoResolutionContext = {
-		defaultRepoRoot,
+		defaultProcessRoot,
 		defaultRepoName,
-		repoMapByKey,
+		defaultRepoFullName,
 		repoNames,
+		repoNameByKey,
 	};
 
 	const parseString = (value: unknown): string | null => {
@@ -2344,7 +2322,7 @@ 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, repoName/repoRoot, projects)",
+				"- mcp.workspace: explain Git workspace context (cwd, repoName selectors, projects)",
 				"- mcp.search: LLM-friendly search over project docs/spec (local-first)",
 				"",
 				'Tip: Prefer mcp.search for "search spec/docs" requests.',
@@ -2356,35 +2334,35 @@ export const createExampleMcpServer = (
 				? {
 						keys: Object.keys(input),
 						repoName: (input as any).repoName ?? null,
-						repoRoot: (input as any).repoRoot ?? null,
-						processRoot: (input as any).processRoot ?? null,
 					}
-				: { keys: [], repoName: null, repoRoot: null, processRoot: null };
+				: { keys: [], repoName: null };
 			const requestedRepoName = parseString(payload.repoName);
 			const resolved = resolveRepoSelectorOptions(payload, repoCtx);
-			const repoRoot =
-				typeof resolved.repoRoot === "string"
-					? resolved.repoRoot
-					: repoCtx.defaultRepoRoot;
-			const effectiveRepoName =
-				requestedRepoName && !looksLikePathish(requestedRepoName)
-					? requestedRepoName
-					: repoCtx.defaultRepoName;
-
-			const projectsDir = path.join(repoRoot, "projects");
-			const apiDir = path.join(repoRoot, "api");
-			const agentsDir = path.join(repoRoot, "agents");
+			const processRoot =
+				typeof resolved.processRoot === "string"
+					? resolved.processRoot
+					: repoCtx.defaultProcessRoot;
+			const effectiveRepoName = normalizeRepoNameForDisplay(
+				requestedRepoName,
+				repoCtx,
+			);
+
+			const projectsDir = path.join(processRoot, "projects");
+			const apiDir = path.join(processRoot, "api");
+			const agentsDir = path.join(processRoot, "agents");
 			const hasProjectsDir = isDir(projectsDir);
 			const hasApiDir = isDir(apiDir);
 			const hasAgentsDir = isDir(agentsDir);
 
-			const projects = hasProjectsDir ? projectsApi.listProjects(repoRoot) : [];
+			const projects = hasProjectsDir
+				? projectsApi.listProjects(processRoot)
+				: [];
 			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 configure the server with --repo-root / MCP_REPO_ROOT.",
-						"Tool callers should usually omit repoName and let the server use its default workspace.",
+						"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.",
 					].join(" ");
 				}
 				if (hasProjectsDir && projects.length === 0) {
@@ -2400,9 +2378,10 @@ export const createExampleMcpServer = (
 				received,
 				cwd: process.cwd(),
 				defaultRepoName: repoCtx.defaultRepoName,
-				defaultRepoRoot: repoCtx.defaultRepoRoot,
+				defaultRepoFullName: repoCtx.defaultRepoFullName,
+				workspaceRoot: repoCtx.defaultProcessRoot,
 				repoName: effectiveRepoName,
-				repoRoot,
+				processRoot,
 				availableRepoNames: repoCtx.repoNames,
 				hasProjectsDir,
 				hasApiDir,
@@ -2452,10 +2431,10 @@ export const createExampleMcpServer = (
 		search: async (input: unknown) => {
 			const payload = isRecord(input) ? input : {};
 			const resolved = resolveRepoSelectorOptions(payload, repoCtx);
-			const repoRoot =
-				typeof resolved.repoRoot === "string"
-					? resolved.repoRoot
-					: repoCtx.defaultRepoRoot;
+			const processRoot =
+				typeof resolved.processRoot === "string"
+					? resolved.processRoot
+					: repoCtx.defaultProcessRoot;
 
 			const sectionRaw = parseString(payload.section)?.toLowerCase();
 			const section = sectionRaw === "docs" ? "docs" : "spec";
@@ -2502,11 +2481,11 @@ export const createExampleMcpServer = (
 
 			const projectName = ensureProjectName(
 				parseString(payload.projectName),
-				repoRoot,
+				processRoot,
 			);
 
 			const searchOptions: Record<string, unknown> = {
-				processRoot: repoRoot,
+				processRoot,
 			};
 
 			const source = parseString(payload.source)?.toLowerCase();
@@ -2829,9 +2808,9 @@ export const createExampleMcpServer = (
 			/projects[\\/].+projects[\\/]/i.test(message)
 		) {
 			details.hint =
-				"You likely passed a project root as repoName (or legacy repoRoot/processRoot). Repo selection should point at the monorepo root that contains /projects.";
+				'Repo selection is invalid. repoName must be "<repo>" or "<owner>/<repo>", for example "adl" or "F0/adl".';
 			details.suggestion =
-				"Call mcp.workspace to see the server’s cwd/default repoRoot, then omit repoName or pass the correct repoName.";
+				"Call mcp.workspace to see accepted repoName selectors.";
 		}
 
 		if (
@@ -2842,7 +2821,7 @@ export const createExampleMcpServer = (
 			details.hint =
 				"Repo selection might be wrong, or the server filesystem does not contain /projects for this workspace.";
 			details.suggestion =
-				"Call mcp.workspace to see the server’s cwd/default repoRoot and available repoName values.";
+				"Call mcp.workspace to see workspaceRoot and available repoName values.";
 			details.example = {
 				tool: prefix ? `${prefix}.mcp.workspace` : "mcp.workspace",
 				arguments: {},