@foundation0/api 1.1.11 → 1.1.13

package/mcp/AGENTS.md

@@ -1,130 +0,0 @@
-# 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/client.test.ts

@@ -1,142 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import fs from 'node:fs/promises'
-import os from 'node:os'
-import path from 'node:path'
-import { ExampleMcpClient } from './client'
-
-type RawToolResponse = {
-  isError?: boolean
-  content: Array<{ type: 'text'; text: string }>
-}
-
-const toRawToolResponse = (data: unknown, isError = false): RawToolResponse => ({
-  isError,
-  content: [
-    {
-      type: 'text',
-      text: JSON.stringify(data),
-    },
-  ],
-})
-
-const toGitFileToolData = (content: string) => ({
-  ok: true,
-  status: 200,
-  body: {
-    path: 'README.md',
-    type: 'file',
-    encoding: 'base64',
-    size: Buffer.byteLength(content, 'utf8'),
-    content: Buffer.from(content, 'utf8').toString('base64'),
-  },
-})
-
-describe('ExampleMcpClient git file guard', () => {
-  let cacheDir: string
-  let client: ExampleMcpClient
-  let capturedRequests: unknown[]
-
-  beforeEach(async () => {
-    cacheDir = await fs.mkdtemp(path.join(os.tmpdir(), 'f0-mcp-client-test-'))
-    capturedRequests = []
-    client = new ExampleMcpClient({
-      maxInlineFileLines: 3,
-      fileCacheDir: cacheDir,
-      requestTimeoutMs: 1_000,
-    })
-  })
-
-  afterEach(async () => {
-    await fs.rm(cacheDir, { recursive: true, force: true })
-  })
-
-  const stubRequests = (handler: (request: any) => RawToolResponse): void => {
-    const internalClient = (client as any).client
-    internalClient.request = async (request: any) => {
-      capturedRequests.push(request)
-      return handler(request)
-    }
-  }
-
-  it('blocks large file responses unless allowLargeSize is set', async () => {
-    const content = ['line 1', 'line 2', 'line 3', 'line 4'].join('\n')
-    stubRequests(() => toRawToolResponse(toGitFileToolData(content)))
-
-    const response = await client.call('repo.contents.view', {
-      args: ['owner', 'repo', 'README.md'],
-    })
-
-    expect(response.isError).toBe(true)
-    expect((response.data as any).hint).toContain('allowLargeSize')
-    expect((response.data as any).stats.lines).toBe(4)
-  })
-
-  it('allows large file responses when allowLargeSize=true and strips client-only options', async () => {
-    const content = ['line 1', 'line 2', 'line 3', 'line 4'].join('\n')
-    stubRequests(() => toRawToolResponse(toGitFileToolData(content)))
-
-    const response = await client.call('repo.contents.view', {
-      args: ['owner', 'repo', 'README.md'],
-      options: {
-        allowLargeSize: true,
-      },
-    })
-
-    expect(response.isError).toBe(false)
-    expect((response.data as any).body.path).toBe('README.md')
-    expect((capturedRequests[0] as any).params.arguments.options).toBeUndefined()
-  })
-
-  it('downloads once and serves line-by-line reads from local cache', async () => {
-    const content = ['line 1', 'line 2', 'line 3', 'line 4'].join('\n')
-    stubRequests(() => toRawToolResponse(toGitFileToolData(content)))
-
-    const first = await client.call('repo.contents.view', {
-      args: ['owner', 'repo', 'README.md'],
-      options: {
-        line: 2,
-      },
-    })
-
-    expect(first.isError).toBe(false)
-    expect((first.data as any).lines).toEqual([{ line: 2, text: 'line 2' }])
-    expect(capturedRequests.length).toBe(1)
-
-    const second = await client.call('repo.contents.view', {
-      args: ['owner', 'repo', 'README.md'],
-      options: {
-        line: 3,
-      },
-    })
-
-    expect(second.isError).toBe(false)
-    expect((second.data as any).lines).toEqual([{ line: 3, text: 'line 3' }])
-    expect(capturedRequests.length).toBe(1)
-
-    const cacheEntries = await fs.readdir(cacheDir)
-    expect(cacheEntries.some((entry) => entry.endsWith('.txt'))).toBe(true)
-    expect(cacheEntries.some((entry) => entry.endsWith('.json'))).toBe(true)
-  })
-
-  it('keeps non-file tool calls unchanged', async () => {
-    stubRequests(() => toRawToolResponse({ ok: true, body: { result: 'pass-through' } }))
-
-    const response = await client.call('projects.listProjects')
-
-    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/manual.md

@@ -1,161 +0,0 @@
-# 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.