@foundation0/api 1.1.11 → 1.1.13

package/README.md

@@ -1,128 +1,128 @@
-# example-org MCP Server
-
-Install and register the example-org MCP server with the MCP-enabled agent/tooling you use.
-
-## 1) Install
-
-Option A: install from npm (recommended for agent machines)
-
-```bash
-pnpm add -g @foundation0/api
-```
-
-Option B: run from npm without installing
-
-```bash
-pnpm dlx @foundation0/api f0-mcp --help
-```
-
-The runnable entrypoint is `f0-mcp` (available from `bin` when installed globally).
-
-## 2) Environment
-
-The server supports:
-
-- `GITEA_HOST` (recommended, required by git-backed tools)
-- `FALLBACK_GITEA_HOST` (fallback host variable)
-- `GITEA_TOKEN` (for authenticated actions)
-- `MCP_TOOLS_PREFIX` (or `--tools-prefix`) to namespace tools in clients
-- `MCP_ALLOWED_ROOT_ENDPOINTS` (or `--allowed-root-endpoints`) to whitelist API root endpoints
-- `MCP_DISABLE_WRITE` (or `--disable-write`) to expose read-only tools only
-- `MCP_ENABLE_ISSUES` (or `--enable-issues`) to allow issue endpoints when write mode is disabled
-- `MCP_ADMIN` (or `--admin`) to expose admin-only destructive endpoints
-
-Useful defaults:
-
-- default server name: `f0-mcp`
-- default server version: `1.0.0`
-
-## 3) Registering with different MCP agents
-
-### A) `.codex/config.toml`
-
-```toml
-[mcp_servers.example]
-command = "bun"
-  args = ["x", "@foundation0/api", "f0-mcp"]
-enabled = true
-startup_timeout_ms = 20_000
-env = {
-  GITEA_HOST = "https://gitea.example.com",
-  GITEA_TOKEN = "your-token",
-  MCP_TOOLS_PREFIX = "example"
-}
-```
-
-If you installed globally with `pnpm add -g`, swap `command` to:
-
-```toml
-command = "f0-mcp"
-args = []
-```
-
-### B) Claude Desktop (`claude_desktop_config.json`)
-
-```json
-{
-  "mcpServers": {
-    "example": {
-      "command": "bun",
-      "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
-      "env": {
-        "GITEA_HOST": "https://gitea.example.com",
-        "GITEA_TOKEN": "your-token"
-      }
-    }
-  }
-}
-```
-
-Use `command: "f0-mcp"` instead of `bun run ...` if you prefer the global install.
-
-### C) Cursor
-
-Use the same command/args/env block in your MCP server configuration area:
-
-```json
-{
-  "command": "bun",
-  "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
-  "env": {
-    "GITEA_HOST": "https://gitea.example.com",
-    "GITEA_TOKEN": "your-token"
-  }
-}
-```
-
-### D) Any MCP-capable client
-
-For any MCP client, register a command-based server with:
-
-- `command: "bun"` and `args: ["x", "@foundation0/api", "f0-mcp", ...flags]`, or
-- `command: "f0-mcp"` if installed globally.
-
-Add environment variables for host/token and optional `MCP_TOOLS_PREFIX`.
-
-## 4) Optional server flags
-
-```bash
-f0-mcp --help
-
-# examples
-f0-mcp --tools-prefix=example --server-name=my-example
-f0-mcp --tools-prefix api --server-version 1.2.3
-f0-mcp --allowed-root-endpoints projects
-f0-mcp --allowed-root-endpoints agents,projects
-f0-mcp --disable-write
-f0-mcp --allowed-root-endpoints projects --disable-write
-f0-mcp --disable-write --enable-issues
-f0-mcp --admin
-f0-mcp --admin --disable-write --enable-issues
-```
-
-- `--tools-prefix` is useful when running multiple MCP servers side-by-side.
-- `--server-name` and `--server-version` are mostly metadata but can help identify logs and client tool sets.
-- `--allowed-root-endpoints` restricts exposed tools to selected root namespaces (`agents`, `projects`).
-- `--disable-write` removes write-capable tools (for example create/update/delete/sync/set/main/run operations).
-- `--enable-issues` is a special-case override for `--disable-write`: issue endpoints remain enabled (`fetchGitTasks`, `readGitTask`, `writeGitTask`).
-- `projects.syncTasks` and `projects.clearIssues` are admin-only and hidden by default; they are exposed only with `--admin` (or `MCP_ADMIN=true`).
+# example-org MCP Server
+
+Install and register the example-org MCP server with the MCP-enabled agent/tooling you use.
+
+## 1) Install
+
+Option A: install from npm (recommended for agent machines)
+
+```bash
+pnpm add -g @foundation0/api
+```
+
+Option B: run from npm without installing
+
+```bash
+pnpm dlx @foundation0/api f0-mcp --help
+```
+
+The runnable entrypoint is `f0-mcp` (available from `bin` when installed globally).
+
+## 2) Environment
+
+The server supports:
+
+- `GITEA_HOST` (recommended, required by git-backed tools)
+- `FALLBACK_GITEA_HOST` (fallback host variable)
+- `GITEA_TOKEN` (for authenticated actions)
+- `MCP_TOOLS_PREFIX` (or `--tools-prefix`) to namespace tools in clients
+- `MCP_ALLOWED_ROOT_ENDPOINTS` (or `--allowed-root-endpoints`) to whitelist API root endpoints
+- `MCP_DISABLE_WRITE` (or `--disable-write`) to expose read-only tools only
+- `MCP_ENABLE_ISSUES` (or `--enable-issues`) to allow issue endpoints when write mode is disabled
+- `MCP_ADMIN` (or `--admin`) to expose admin-only destructive endpoints
+
+Useful defaults:
+
+- default server name: `f0-mcp`
+- default server version: `1.0.0`
+
+## 3) Registering with different MCP agents
+
+### A) `.codex/config.toml`
+
+```toml
+[mcp_servers.example]
+command = "bun"
+  args = ["x", "@foundation0/api", "f0-mcp"]
+enabled = true
+startup_timeout_ms = 20_000
+env = {
+  GITEA_HOST = "https://gitea.example.com",
+  GITEA_TOKEN = "your-token",
+  MCP_TOOLS_PREFIX = "example"
+}
+```
+
+If you installed globally with `pnpm add -g`, swap `command` to:
+
+```toml
+command = "f0-mcp"
+args = []
+```
+
+### B) Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "command": "bun",
+      "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
+      "env": {
+        "GITEA_HOST": "https://gitea.example.com",
+        "GITEA_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+Use `command: "f0-mcp"` instead of `bun run ...` if you prefer the global install.
+
+### C) Cursor
+
+Use the same command/args/env block in your MCP server configuration area:
+
+```json
+{
+  "command": "bun",
+  "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
+  "env": {
+    "GITEA_HOST": "https://gitea.example.com",
+    "GITEA_TOKEN": "your-token"
+  }
+}
+```
+
+### D) Any MCP-capable client
+
+For any MCP client, register a command-based server with:
+
+- `command: "bun"` and `args: ["x", "@foundation0/api", "f0-mcp", ...flags]`, or
+- `command: "f0-mcp"` if installed globally.
+
+Add environment variables for host/token and optional `MCP_TOOLS_PREFIX`.
+
+## 4) Optional server flags
+
+```bash
+f0-mcp --help
+
+# examples
+f0-mcp --tools-prefix=example --server-name=my-example
+f0-mcp --tools-prefix api --server-version 1.2.3
+f0-mcp --allowed-root-endpoints projects
+f0-mcp --allowed-root-endpoints agents,projects
+f0-mcp --disable-write
+f0-mcp --allowed-root-endpoints projects --disable-write
+f0-mcp --disable-write --enable-issues
+f0-mcp --admin
+f0-mcp --admin --disable-write --enable-issues
+```
+
+- `--tools-prefix` is useful when running multiple MCP servers side-by-side.
+- `--server-name` and `--server-version` are mostly metadata but can help identify logs and client tool sets.
+- `--allowed-root-endpoints` restricts exposed tools to selected root namespaces (`agents`, `projects`).
+- `--disable-write` removes write-capable tools (for example create/update/delete/sync/set/main/run operations).
+- `--enable-issues` is a special-case override for `--disable-write`: issue endpoints remain enabled (`fetchGitTasks`, `readGitTask`, `writeGitTask`).
+- `projects.syncTasks` and `projects.clearIssues` are admin-only and hidden by default; they are exposed only with `--admin` (or `MCP_ADMIN=true`).