@foundation0/api 1.1.7 → 1.1.10

package/mcp/cli.ts

@@ -67,9 +67,6 @@ 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 repoName = getArgValue('--repo-name') ?? process.env.MCP_REPO_NAME ?? process.env.F0_REPO_NAME
-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,
 )
@@ -83,11 +80,6 @@ if (hasFlag('--help') || hasFlag('-h')) {
   console.log('  --server-name <name>')
   console.log('  --server-version <version>')
   console.log('  --tools-prefix <prefix>')
-  console.log('  --repo-name <name>')
-  console.log('    Default repoName used by tool calls when omitted. Env: MCP_REPO_NAME or F0_REPO_NAME.')
-  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')
@@ -104,8 +96,6 @@ void runExampleMcpServer({
   serverName: serverName ?? undefined,
   serverVersion: serverVersion ?? undefined,
   toolsPrefix,
-  repoRoot: repoRoot ?? undefined,
-  repoName: repoName ?? undefined,
   allowedRootEndpoints,
   disableWrite,
   enableIssues,

package/mcp/manual.md

@@ -1,161 +1,161 @@
-# 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`, `repoName`) rather than relying on positional `args`.
-4. `repoName` selects the repo workspace on the **server filesystem**. Usually omit it and let the server use its default. Legacy path aliases: `repoRoot` / `processRoot`.
-5. Tool results are returned as a **JSON text envelope**: parse the text as JSON and check `ok`.
-
-Note: If you’re unsure what the server can see (cwd/default repoRoot/available repoName values), call `mcp.workspace`. Multi-repo `repoName` mappings can be configured server-side via `MCP_REPOS` (JSON object or `name=path;name=path`).
-
-## 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 4 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",
-    "repoName": "<repo-name>",
-    "ignoreCase": true,
-    "maxCount": 50
-  }
-}
-```
-
-### D) `mcp.workspace` to debug repoName/repoRoot/cwd issues
-
-Tool call:
-
-```json
-{ "name": "mcp.workspace", "arguments": {} }
-```
-
-## 3) Payload shapes (important)
-
-Most tools accept either:
-
-```json
-{ "args": ["<project-name>"], "options": { "repoName": "<repo-name>" } }
-```
-
-or named keys (recommended). The server merges top-level keys into `options`:
-
-```json
-{ "projectName": "<project-name>", "repoName": "<repo-name>" }
-```
-
-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": { "repoName": "<repo-name>" }
-}
-```
-
-### B) List agents
-
-```json
-{
-  "name": "agents.listAgents",
-  "arguments": { "repoName": "<repo-name>" }
-}
-```
-
-### C) Set an active file (projects)
-
-```json
-{
-  "name": "projects.setActive",
-  "arguments": {
-    "args": ["<project-name>", "/implementation-plan.v0.0.1"],
-    "options": { "repoName": "<repo-name>", "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": { "repoName": "<repo-name>" } }
-    ],
-    "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/...**: call `mcp.workspace` and verify the server repo workspace (default `repoRoot`, and optional `repoName` mapping).
-- **`projects.listProjects()` returns `[]` unexpectedly**: call `mcp.workspace` to confirm the server’s `cwd`/default `repoRoot` and whether `/projects` exists.
-
-## 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.
+# 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`, `repoName`) rather than relying on positional `args`.
+4. `repoName` selects the active Git workspace identity. Use `adl` or `F0/adl`, or omit it to use the server default.
+5. Tool results are returned as a **JSON text envelope**: parse the text as JSON and check `ok`.
+
+Note: If you're unsure what the server can see (cwd/workspaceRoot/available repoName values), call `mcp.workspace`.
+
+## 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 4 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",
+    "repoName": "<repo-name>",
+    "ignoreCase": true,
+    "maxCount": 50
+  }
+}
+```
+
+### D) `mcp.workspace` to debug repoName/workspaceRoot/cwd issues
+
+Tool call:
+
+```json
+{ "name": "mcp.workspace", "arguments": {} }
+```
+
+## 3) Payload shapes (important)
+
+Most tools accept either:
+
+```json
+{ "args": ["<project-name>"], "options": { "repoName": "<repo-name>" } }
+```
+
+or named keys (recommended). The server merges top-level keys into `options`:
+
+```json
+{ "projectName": "<project-name>", "repoName": "<repo-name>" }
+```
+
+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": { "repoName": "<repo-name>" }
+}
+```
+
+### B) List agents
+
+```json
+{
+  "name": "agents.listAgents",
+  "arguments": { "repoName": "<repo-name>" }
+}
+```
+
+### C) Set an active file (projects)
+
+```json
+{
+  "name": "projects.setActive",
+  "arguments": {
+    "args": ["<project-name>", "/implementation-plan.v0.0.1"],
+    "options": { "repoName": "<repo-name>", "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": { "repoName": "<repo-name>" } }
+    ],
+    "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**: call `mcp.workspace` and verify `workspaceRoot` plus `availableRepoNames` (use `adl` or `F0/adl`).
+- **`projects.listProjects()` returns `[]` unexpectedly**: call `mcp.workspace` to confirm the server's `cwd`, `workspaceRoot`, and whether `/projects` exists.
+
+## 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.