@foundation0/api 1.1.1 → 1.1.3

package/agents.ts

@@ -39,7 +39,7 @@ interface ActiveConfigInput {
   required: boolean
 }
 
-const CLI_NAME = 'example'
+const CLI_NAME = 'f0'
 const AGENT_INITIAL_VERSION = 'v0.0.1'
 const DEFAULT_SKILL_NAME = 'coding-standards'
 const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
@@ -58,7 +58,7 @@ export function usage(): string {
     `Use --latest to resolve /file-name to the latest version.\n` +
     `The active file created is [file].active.<ext>.\n` +
     `Use "run" to start codex with developer_instructions from system/prompt.ts.\n` +
-    `Set EXAMPLE_CODEX_BIN to pin a specific codex binary.\n`
+    `Set F0_CODEX_BIN (or EXAMPLE_CODEX_BIN) to pin a specific codex binary.\n`
 }
 
 export function resolveAgentsRoot(processRoot: string = process.cwd()): string {
@@ -460,9 +460,9 @@ export function setActiveLink(sourceFile: string, activeFile: string): 'symlink'
 
   fs.mkdirSync(path.dirname(activeFile), { recursive: true })
 
-  if (fs.existsSync(activeFile)) {
-    fs.rmSync(activeFile, { force: true })
-  }
+  // Remove the active pointer first. Using rmSync directly (instead of existsSync)
+  // ensures we also clear broken symlinks (existsSync returns false for them).
+  fs.rmSync(activeFile, { force: true })
 
   const linkTarget = path.relative(path.dirname(activeFile), sourceFile)
 
@@ -643,7 +643,7 @@ type SpawnCodexResult = {
 type SpawnCodexFn = (args: string[]) => SpawnCodexResult
 
 function getCodexCommand(): string {
-  const override = process.env.EXAMPLE_CODEX_BIN?.trim()
+  const override = process.env.F0_CODEX_BIN?.trim() ?? process.env.EXAMPLE_CODEX_BIN?.trim()
   if (override) {
     return override
   }
@@ -666,6 +666,7 @@ const defaultSpawnCodex: SpawnCodexFn = (args) => {
     const err = primary.error as NodeJS.ErrnoException
     if (
       process.platform === 'win32'
+      && !process.env.F0_CODEX_BIN
       && !process.env.EXAMPLE_CODEX_BIN
       && primaryCommand === 'codex.cmd'
       && err.code === 'ENOENT'

package/git.ts

@@ -5,7 +5,7 @@ export type {
   GitServiceApi,
   GitServiceApiExecutionResult,
   GitServiceApiMethod,
-} from '../git/packages/git/src/index.ts'
+} from '@foundation0/git'
 
 export {
   attachGitLabelManagementApi,
@@ -17,4 +17,4 @@ export {
   extractDependencyIssueNumbers,
   resolveProjectRepoIdentity,
   syncIssueDependencies,
-} from '../git/packages/git/src/index.ts'
+} from '@foundation0/git'

package/mcp/AGENTS.md

@@ -0,0 +1,130 @@
+# MCP Endpoint Design (LLM-Friendly)
+
+This folder contains the Foundation0 MCP server (`api/mcp/server.ts`) and CLI (`api/mcp/cli.ts`).
+
+These notes exist because the most common “LLM friction” issues are predictable:
+- tool name/prefix confusion (duplicate names, “tool not found”),
+- payload-shape confusion (positional `args` vs object options, or proxy tools that require JSON strings),
+- oversized responses (truncation → extra tool calls),
+- weak errors (not actionable → retries and wasted calls).
+
+Use this doc when adding or modifying MCP endpoints so models can succeed in **one call**.
+
+## 1) Avoid Tool Prefix Double-Wrapping
+
+If your agent uses `pi-mcp-adapter` (or any MCP proxy that already prefixes tools), do **not** also run the server with `--tools-prefix`.
+
+Bad (creates confusing duplicates like `f0_f0_net_curl` and `f0_net_curl`):
+- Agent tool prefixing: `toolPrefix: "server"` (adds `f0_...`)
+- Server tool prefixing: `--tools-prefix f0` (adds `f0....`)
+
+Good (single predictable name):
+- Agent: `toolPrefix: "server"`
+- Server: no `--tools-prefix`
+
+## 2) Prefer Direct Tools for Hot Paths (Fewer Calls, Fewer Errors)
+
+Proxy-based MCP gateways often require passing `args` as a **JSON string** (not an object), which LLMs frequently get wrong.
+
+If a tool is used often (HTTP, search, file ops), expose it as a **direct tool** in the agent config:
+
+```json
+{
+  "mcp": {
+    "mcpServers": {
+      "f0": {
+        "directTools": ["net_curl", "batch"]
+      }
+    }
+  }
+}
+```
+
+Note: Direct tool names must be OpenAI-tool-name-safe (no dots). Use the underscore aliases (e.g., `net_curl`) when exposing direct tools.
+
+Benefits:
+- The model calls `f0_net_curl` directly (no gateway wrapper).
+- The model passes a normal JSON object (no “args must be a JSON string” confusion).
+- Tool discoverability improves (tool appears in the system prompt).
+
+Guideline: keep direct tools to a focused set (5–20). Use proxy for large catalogs.
+
+## 3) Always Support a “Structured Mode” (Don’t Force Curl-CLI Literacy)
+
+LLMs naturally try:
+```json
+{ "url": "https://…", "method": "GET", "headers": { "accept": "application/json" } }
+```
+
+If your tool only accepts positional CLI-like args (e.g. `{ "args": ["-L", "…"] }`), the model will often:
+- guess the wrong shape,
+- call `describe`,
+- retry,
+- and burn multiple tool calls.
+
+Best practice:
+- support **both** shapes:
+  - Curl-style: `{ "args": ["-L", "https://…"] }`
+  - Structured: `{ "url": "https://…", "method": "GET", ... }`
+
+For `net.curl` (alias `net_curl`), structured mode should accept the common fields:
+- `url`/`urls`, `method`, `headers`, `body`/`data`/`json`, `followRedirects`, `includeHeaders`,
+- `fail`, `silent`, `verbose`, `writeOut`,
+- `timeoutMs`, `maxTimeSeconds`, `maxRedirects`,
+- `output`/`remoteName`, `user`.
+
+Also: keep field names intuitive (`url`, `method`, `headers`, `body`) even if internally you translate to an `args[]` array.
+
+## 4) Write a Tight Schema + Examples (Make the First Call Succeed)
+
+Tool schemas are often the only thing an LLM sees.
+
+Do:
+- Provide a schema that shows **both** modes (positional `args[]` + structured keys).
+- Add short descriptions that include **an example payload**.
+- Prefer `additionalProperties: true` to allow forwards-compatible additions.
+
+Avoid:
+- schemas that only describe `args` but not recommended “structured mode”.
+- schema-required fields that don’t exist for the other mode.
+
+## 5) Make Errors Actionable (Self-Correct in One Retry)
+
+When rejecting input:
+- Use clear “what you passed / what I expected” wording.
+- Include a copy/paste example.
+- Provide likely tool-name suggestions when tool lookup fails.
+
+If you control the gateway layer:
+- Treat argument-shape failures as `isError: true` so the LLM knows to correct (not continue).
+
+## 6) Keep Outputs Small by Default (Prevent Truncation)
+
+Large outputs cause:
+- truncation (the model misses the answer),
+- follow-up calls,
+- and sometimes tool-call loops.
+
+Do:
+- omit base64-encoded blobs by default (make them opt-in),
+- provide `-o/--output` style file outputs for large bodies,
+- include lightweight metadata (status code, headers, elapsed time).
+
+## 7) Add Tests that Simulate “LLM Mistakes”
+
+Every new endpoint should include tests that cover:
+- structured payload success (`{ url, method }`),
+- curl-style args success (`{ args: [...] }`),
+- invalid shape failure (missing URL),
+- “tool not found” suggestion behavior (server-side).
+
+Tests belong next to the server/tool code (Bun tests under `api/`).
+
+## 8) Endpoint Implementation Checklist
+
+When adding `root.namespace.tool`:
+- Add it under an explicit namespace (`net.*`, `projects.*`, etc.), not the root.
+- Add/adjust `TOOL_INPUT_SCHEMA_OVERRIDES[toolName]` with examples.
+- Ensure tool access is correct (read vs write vs admin).
+- Ensure agent configs include the root endpoint in `--allowed-root-endpoints` when needed.
+- Consider `directTools` for high-frequency tools.

package/mcp/cli.mjs

@@ -32,6 +32,6 @@ try {
     process.exit(1)
   }
 
-  console.error('Failed to launch example-org MCP server', error)
+  console.error('Failed to launch f0-mcp server', error)
   process.exit(1)
 }

package/mcp/cli.ts

@@ -101,6 +101,6 @@ void runExampleMcpServer({
   enableIssues,
   admin,
 }).catch((error) => {
-  console.error('Failed to start example-org MCP server', error)
-  process.exit(1)
-})
+  console.error('Failed to start f0-mcp server', error)
+  process.exit(1)
+})

package/mcp/client.test.ts

@@ -126,4 +126,17 @@ describe('ExampleMcpClient git file guard', () => {
     expect(response.isError).toBe(false)
     expect(response.data).toEqual({ ok: true, body: { result: 'pass-through' } })
   })
+
+  it('keeps plain-text tool responses as data when JSON parsing fails', async () => {
+    stubRequests(() => ({
+      isError: false,
+      content: [{ type: 'text', text: 'not-json' }],
+    }))
+
+    const response = await client.call('projects.listProjects')
+
+    expect(response.isError).toBe(false)
+    expect(response.text).toBe('not-json')
+    expect(response.data).toBe('not-json')
+  })
 })

package/mcp/client.ts

@@ -151,11 +151,19 @@ const decodeFileContent = (content: string, encoding: string): string => {
 }
 
 const extractGitFileContent = (data: unknown): ExtractedGitFileContent | null => {
-  if (!isRecord(data) || !isRecord(data.body)) {
+  const unwrapped = (() => {
+    if (!isRecord(data)) return data
+    if (typeof data.ok === 'boolean' && 'result' in data) {
+      return (data as any).result
+    }
+    return data
+  })()
+
+  if (!isRecord(unwrapped) || !isRecord(unwrapped.body)) {
     return null
   }
 
-  const body = data.body
+  const body = unwrapped.body
   if (typeof body.content !== 'string') {
     return null
   }
@@ -366,7 +374,7 @@ export class ExampleMcpClient {
     return {
       isError: Boolean(response.isError),
       text: parsed.text,
-      data: parsed.parsed,
+      data: parsed.parsed ?? parsed.text,
     }
   }
 
@@ -547,7 +555,7 @@ export class ExampleMcpClient {
     methodArgs: unknown[] = [],
     methodOptions: Record<string, unknown> = {},
   ): Promise<ExampleMcpCallResponse> {
-    const args = { args: methodArgs.map((value) => String(value)), options: methodOptions }
+    const args = { args: methodArgs, options: methodOptions }
     return this.call(path, args)
   }
 }