@foundation0/api 1.1.2 → 1.1.4

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.