From 368e66396594fa55ab06a5c0d4f211786f28c859 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sat, 13 Jun 2026 19:29:31 +0200 Subject: [PATCH 1/3] Stage colibri-mcp in operator USB by default (Sam & Codex) Makes colibri-mcp a required Colibri artifact for the live operator USB, copies it into the image, documents the read-only default and explicit trusted COLIBRI_MCP_WRITE profile, and updates ISO build handoff docs.\n\nChecks: ./scripts/check-format.sh; sh -n build.sh scripts/stage-colibri-iso.sh; git diff --check --- AGENTS.md | 5 +++-- BUILD.md | 5 +++++ README.md | 1 + build.sh | 6 ++++-- docs/POUDRIERE-BUILD-SERVER.md | 1 + live/operator-session/bootstrap.html | 3 +++ scripts/stage-colibri-iso.sh | 3 +++ skills/iso-build/SKILL.md | 7 +++++-- 8 files changed, 25 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e18bc01a..ee9f9862 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,9 +104,10 @@ the ISO does **not** build Rust while the image is mounted. skill (§Colibri artifact preflight). - Staging layout (installed paths, rc.d, directory ownership) is owned by Colibri `docs/ISO-INTEGRATION-PLAN.md`. -- Required by ISO preflight: `colibri-daemon`, `colibri`, `colibri-smoke-agent`. +- Required by ISO preflight: `colibri-daemon`, `colibri`, `colibri-smoke-agent`, + and `colibri-mcp`. `colibri-tui` is optional in staging code but desired for this USB target and - should be verified alongside the other three. + should be verified alongside the required binaries. **Invariant:** do not `cargo clean` `/home/clawdie/ai/colibri` until the ISO preflight/build has consumed `/home/clawdie/ai/colibri/target/release`. diff --git a/BUILD.md b/BUILD.md index b44b40e5..ca5dd03a 100644 --- a/BUILD.md +++ b/BUILD.md @@ -83,6 +83,7 @@ Colibri-backed. The image includes: /usr/local/bin/colibri-daemon /usr/local/bin/colibri /usr/local/bin/colibri-smoke-agent +/usr/local/bin/colibri-mcp # MCP bridge for Zed/Claude Code/Cursor /usr/local/bin/colibri-tui # if present in the artifact dir /usr/local/etc/rc.d/colibri_daemon /var/db/colibri @@ -95,6 +96,10 @@ values for `colibri_daemon_enable`, paths, and `colibri_cost_mode`. Operator USB validation builds enable `colibri_daemon_enable=YES`; the service starts after the login milestone and is the lightweight control plane for the live USB. +`colibri-mcp` is staged out of the box for MCP-capable editors and assistants. +It defaults to read-only tools; launch it with `COLIBRI_MCP_WRITE=1` only for a +trusted write-capable MCP profile. + ### Colibri vs. Clawdie service names ```text diff --git a/README.md b/README.md index 3dec0d7b..5c1ab99b 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ Live operator USB SDDM/XFCE desktop └── colibri_daemon # lightweight control plane, enabled on USB ├── colibri CLI / colibri-tui + ├── colibri-mcp # MCP bridge for editor/assistant clients └── agent harness # Colibri's bundled agent (staged with the # daemon); pi available as a spawnable backend diff --git a/build.sh b/build.sh index 214a324a..a04be321 100755 --- a/build.sh +++ b/build.sh @@ -325,7 +325,7 @@ preflight_colibri_artifacts() { echo " Set COLIBRI_REPO=/path/to/colibri or FEATURE_COLIBRI=NO." exit 1 fi - for _colibri_bin in colibri-daemon colibri colibri-smoke-agent; do + for _colibri_bin in colibri-daemon colibri colibri-smoke-agent colibri-mcp; do if [ ! -x "${_resolved_colibri_artifact_dir}/${_colibri_bin}" ]; then echo "ERROR: Colibri release binary missing: ${_resolved_colibri_artifact_dir}/${_colibri_bin}" echo " Build first: (cd ${_resolved_colibri_repo} && cargo build --workspace --release)" @@ -802,7 +802,9 @@ install_colibri_service() { set_config_line "${MOUNT_POINT}/etc/rc.conf" 'colibri_daemon_host="$(hostname)"' set_config_line "${MOUNT_POINT}/etc/rc.conf" "colibri_cost_mode=\"${COLIBRI_COST_MODE:-smart}\"" - if [ ! -x "${MOUNT_POINT}/usr/local/bin/colibri-daemon" ] || [ ! -x "${MOUNT_POINT}/usr/local/bin/colibri" ]; then + if [ ! -x "${MOUNT_POINT}/usr/local/bin/colibri-daemon" ] || \ + [ ! -x "${MOUNT_POINT}/usr/local/bin/colibri" ] || \ + [ ! -x "${MOUNT_POINT}/usr/local/bin/colibri-mcp" ]; then echo "ERROR: Colibri binaries missing from live image" exit 1 fi diff --git a/docs/POUDRIERE-BUILD-SERVER.md b/docs/POUDRIERE-BUILD-SERVER.md index a4b475f4..ee4cdeac 100644 --- a/docs/POUDRIERE-BUILD-SERVER.md +++ b/docs/POUDRIERE-BUILD-SERVER.md @@ -231,6 +231,7 @@ This gives us: - `colibri-daemon` - `colibri-tui` - `colibri-smoke-agent` +- `colibri-mcp` All with proper pkg metadata, upgradeable, with dependencies tracked. diff --git a/live/operator-session/bootstrap.html b/live/operator-session/bootstrap.html index 803c9350..f3344e00 100644 --- a/live/operator-session/bootstrap.html +++ b/live/operator-session/bootstrap.html @@ -89,6 +89,7 @@
  • XFCE desktop — dual-monitor, panel, wallpaper
  • colibri-daemon — agent supervisor, skills catalog, Glasspane state machine
  • colibri-tui — live ratatui dashboard (agent states, spawn/kill, sessions)
    • +
  • colibri-mcp — MCP bridge for Zed, Claude Code, Cursor, and other MCP clients
  • Firefox browser
  • Tailscale package (needs auth key)
  • pi coding agent harness (npm global)
    • @@ -117,6 +118,8 @@ colibri status colibri snapshot # Glasspane agent states colibri list-tasks # Coordination board colibri list-skills # Skills catalog +colibri-mcp tools # MCP bridge, read-only by default +COLIBRI_MCP_WRITE=1 colibri-mcp tools # trusted write-capable profile colibri create-task --title "check network" colibri list-tasks --status queued diff --git a/scripts/stage-colibri-iso.sh b/scripts/stage-colibri-iso.sh index 9cdc4391..10fce5ba 100755 --- a/scripts/stage-colibri-iso.sh +++ b/scripts/stage-colibri-iso.sh @@ -61,6 +61,7 @@ mkdir -p "${BIN_DIR}" "${RC_DIR}" "${ETC_DIR}" "${NEWSYSLOG_DIR}" "${DB_DIR}" "$ copy_bin colibri-daemon copy_bin colibri copy_bin colibri-smoke-agent +copy_bin colibri-mcp if [ "${COLIBRI_STAGE_INCLUDE_TUI}" != "0" ] && [ -x "${COLIBRI_ARTIFACT_DIR}/colibri-tui" ]; then copy_bin colibri-tui @@ -142,6 +143,8 @@ Runtime validation: colibri status colibri create-task --title "iso smoke" colibri list-tasks --status queued + colibri-mcp tools + COLIBRI_MCP_WRITE=1 colibri-mcp tools # trusted write-capable MCP profile service colibri_daemon stop EOF diff --git a/skills/iso-build/SKILL.md b/skills/iso-build/SKILL.md index da1b24ae..056e5d98 100644 --- a/skills/iso-build/SKILL.md +++ b/skills/iso-build/SKILL.md @@ -151,11 +151,13 @@ cargo build --workspace --release ls -lh target/release/colibri-daemon \ target/release/colibri \ target/release/colibri-smoke-agent \ + target/release/colibri-mcp \ target/release/colibri-tui file target/release/colibri-daemon \ target/release/colibri \ target/release/colibri-smoke-agent \ + target/release/colibri-mcp \ target/release/colibri-tui target/release/colibri --help | head @@ -183,8 +185,9 @@ cargo clean rm -rf /tmp/colibri-* ``` -`colibri-tui` is optional in the staging script, but desired for this operator -USB target and should be verified with the other three binaries. +`colibri-mcp` is part of the out-of-the-box operator USB. `colibri-tui` is +optional in the staging script, but desired for this operator USB target and +should be verified with the required binaries. ### Deployed-system Clawdie service boundary -- 2.45.3 From 72cfcec91a8d0572d08ae7a1c5479bbae3f2c9ca Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sat, 13 Jun 2026 19:36:03 +0200 Subject: [PATCH 2/3] Add Colibri MCP client examples to live image (Sam & Codex) Installs read-only and trusted-write MCP client config examples under /usr/local/share/clawdie-iso/mcp-examples and links them from the bootstrap page.\n\nChecks: ./scripts/check-format.sh; sh -n build.sh scripts/stage-colibri-iso.sh; python3 -m json.tool MCP examples; git diff --check --- BUILD.md | 3 +- build.sh | 7 +++ live/operator-session/bootstrap.html | 4 ++ live/operator-session/mcp-examples/README.md | 58 +++++++++++++++++++ .../mcp-examples/mcp-readonly.json | 9 +++ .../mcp-examples/mcp-trusted-write.json | 11 ++++ 6 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 live/operator-session/mcp-examples/README.md create mode 100644 live/operator-session/mcp-examples/mcp-readonly.json create mode 100644 live/operator-session/mcp-examples/mcp-trusted-write.json diff --git a/BUILD.md b/BUILD.md index ca5dd03a..e3911b5b 100644 --- a/BUILD.md +++ b/BUILD.md @@ -98,7 +98,8 @@ the login milestone and is the lightweight control plane for the live USB. `colibri-mcp` is staged out of the box for MCP-capable editors and assistants. It defaults to read-only tools; launch it with `COLIBRI_MCP_WRITE=1` only for a -trusted write-capable MCP profile. +trusted write-capable MCP profile. Example MCP client configs are installed at +`/usr/local/share/clawdie-iso/mcp-examples/`. ### Colibri vs. Clawdie service names diff --git a/build.sh b/build.sh index a04be321..85be7d35 100755 --- a/build.sh +++ b/build.sh @@ -1465,6 +1465,13 @@ EOF mkdir -p "${MOUNT_POINT}/usr/local/share/clawdie-iso/bootstrap" install -m 0644 "${LIVE_SESSION_DIR}/bootstrap.html" \ "${MOUNT_POINT}/usr/local/share/clawdie-iso/bootstrap/index.html" + if [ -d "${LIVE_SESSION_DIR}/mcp-examples" ]; then + mkdir -p "${MOUNT_POINT}/usr/local/share/clawdie-iso/mcp-examples" + cp -R "${LIVE_SESSION_DIR}/mcp-examples/." \ + "${MOUNT_POINT}/usr/local/share/clawdie-iso/mcp-examples/" + find "${MOUNT_POINT}/usr/local/share/clawdie-iso/mcp-examples" \ + -type f -exec chmod 0644 {} + + fi chroot "$MOUNT_POINT" chown -R clawdie:clawdie /home/clawdie/Desktop chmod 0755 "${MOUNT_POINT}/home/clawdie/Desktop" chmod 0644 \ diff --git a/live/operator-session/bootstrap.html b/live/operator-session/bootstrap.html index f3344e00..f20d6205 100644 --- a/live/operator-session/bootstrap.html +++ b/live/operator-session/bootstrap.html @@ -122,6 +122,10 @@ colibri-mcp tools # MCP bridge, read-only by default COLIBRI_MCP_WRITE=1 colibri-mcp tools # trusted write-capable profile colibri create-task --title "check network" colibri list-tasks --status queued +

    + MCP client examples are installed under + /usr/local/share/clawdie-iso/mcp-examples/. +

    pi assistant

    diff --git a/live/operator-session/mcp-examples/README.md b/live/operator-session/mcp-examples/README.md
new file mode 100644
index 00000000..1ff30f04
--- /dev/null
+++ b/live/operator-session/mcp-examples/README.md
@@ -0,0 +1,58 @@
+# Colibri MCP client examples
+
+The live USB includes `/usr/local/bin/colibri-mcp`, an MCP server that exposes
+Colibri status, glasspane snapshots, task lists, and skills to MCP-capable
+editors/assistants.
+
+Default posture is read-only. Write tools are available only when the MCP server
+process is launched with `COLIBRI_MCP_WRITE=1`.
+
+## Generic MCP client config
+
+Most MCP clients accept a config shaped like `mcpServers`. Use one of:
+
+- `mcp-readonly.json` — safe default profile
+- `mcp-trusted-write.json` — explicit trusted profile with write tools enabled
+
+## Quick checks
+
+```sh
+colibri-mcp tools
+COLIBRI_MCP_WRITE=1 colibri-mcp tools
+colibri-mcp socket-path
+```
+
+## Claude Code example
+
+If your Claude Code version supports `claude mcp add`, adapt:
+
+```sh
+claude mcp add colibri /usr/local/bin/colibri-mcp
+claude mcp add colibri-write --env COLIBRI_MCP_WRITE=1 /usr/local/bin/colibri-mcp
+```
+
+If your version uses a JSON config file instead, copy the matching object from
+`mcp-readonly.json` or `mcp-trusted-write.json`.
+
+## Zed / Cursor example
+
+Zed, Cursor, and other MCP-capable editors may use slightly different config
+file paths or wrapper keys by version. The server object is the important part:
+
+```json
+{
+  "command": "/usr/local/bin/colibri-mcp",
+  "args": [],
+  "env": {}
+}
+```
+
+For a write-capable profile, add:
+
+```json
+{
+  "env": { "COLIBRI_MCP_WRITE": "1" }
+}
+```
+
+Only enable the write profile for trusted workspaces/sessions.
diff --git a/live/operator-session/mcp-examples/mcp-readonly.json b/live/operator-session/mcp-examples/mcp-readonly.json
new file mode 100644
index 00000000..56617b39
--- /dev/null
+++ b/live/operator-session/mcp-examples/mcp-readonly.json
@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "colibri": {
+      "command": "/usr/local/bin/colibri-mcp",
+      "args": [],
+      "env": {}
+    }
+  }
+}
diff --git a/live/operator-session/mcp-examples/mcp-trusted-write.json b/live/operator-session/mcp-examples/mcp-trusted-write.json
new file mode 100644
index 00000000..68151d90
--- /dev/null
+++ b/live/operator-session/mcp-examples/mcp-trusted-write.json
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "colibri-write": {
+      "command": "/usr/local/bin/colibri-mcp",
+      "args": [],
+      "env": {
+        "COLIBRI_MCP_WRITE": "1"
+      }
+    }
+  }
+}
-- 
2.45.3


From 47b0db16e448d4364c31975468020ab24e06410a Mon Sep 17 00:00:00 2001
From: Sam & Claude 
Date: Sat, 13 Jun 2026 19:54:17 +0200
Subject: [PATCH 3/3] docs: add external MCP profile examples to ISO (Sam &
 Codex)

Adds sample external MCP registry and explicit external-call client profile alongside the default read-only Colibri MCP examples.\n\nChecks: ./scripts/check-format.sh; sh -n build.sh scripts/stage-colibri-iso.sh; python3 -m json.tool MCP examples; git diff --check
---
 live/operator-session/mcp-examples/README.md  | 42 +++++++++++++++++--
 .../mcp-examples/external-mcp.sample.json     | 16 +++++++
 .../mcp-examples/mcp-external-call.json       | 11 +++++
 3 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 live/operator-session/mcp-examples/external-mcp.sample.json
 create mode 100644 live/operator-session/mcp-examples/mcp-external-call.json

diff --git a/live/operator-session/mcp-examples/README.md b/live/operator-session/mcp-examples/README.md
index 1ff30f04..a02c8e54 100644
--- a/live/operator-session/mcp-examples/README.md
+++ b/live/operator-session/mcp-examples/README.md
@@ -4,15 +4,18 @@ The live USB includes `/usr/local/bin/colibri-mcp`, an MCP server that exposes
 Colibri status, glasspane snapshots, task lists, and skills to MCP-capable
 editors/assistants.
 
-Default posture is read-only. Write tools are available only when the MCP server
-process is launched with `COLIBRI_MCP_WRITE=1`.
+Default posture is read-only. Colibri write tools are available only when the
+MCP server process is launched with `COLIBRI_MCP_WRITE=1`. External MCP tool
+calls are available only when launched with `COLIBRI_MCP_EXTERNAL_CALL=1`.
 
 ## Generic MCP client config
 
 Most MCP clients accept a config shaped like `mcpServers`. Use one of:
 
 - `mcp-readonly.json` — safe default profile
-- `mcp-trusted-write.json` — explicit trusted profile with write tools enabled
+- `mcp-trusted-write.json` — explicit trusted profile with Colibri write tools enabled
+- `mcp-external-call.json` — explicit trusted profile for external MCP tool calls
+- `external-mcp.sample.json` — example external MCP server registry
 
 ## Quick checks
 
@@ -20,6 +23,8 @@ Most MCP clients accept a config shaped like `mcpServers`. Use one of:
 colibri-mcp tools
 COLIBRI_MCP_WRITE=1 colibri-mcp tools
 colibri-mcp socket-path
+COLIBRI_MCP_EXTERNAL_CONFIG=/usr/local/share/clawdie-iso/mcp-examples/external-mcp.sample.json \
+  colibri-mcp tools
 ```
 
 ## Claude Code example
@@ -56,3 +61,34 @@ For a write-capable profile, add:
 ```
 
 Only enable the write profile for trusted workspaces/sessions.
+
+## External MCP server prototype
+
+Newer Colibri builds can also use `colibri-mcp` as a small MCP host/client for
+other stdio MCP servers. Copy the sample registry into the live config path and
+edit it for the servers you actually want:
+
+```sh
+mdo -u root mkdir -p /usr/local/etc/colibri
+mdo -u root cp /usr/local/share/clawdie-iso/mcp-examples/external-mcp.sample.json \
+  /usr/local/etc/colibri/external-mcp.json
+```
+
+Read-only discovery works by default through these tools:
+
+- `colibri_external_mcp_servers`
+- `colibri_external_mcp_list_tools`
+
+Calling external MCP tools requires an explicit trusted profile:
+
+```json
+{
+  "command": "/usr/local/bin/colibri-mcp",
+  "args": [],
+  "env": {
+    "COLIBRI_MCP_EXTERNAL_CALL": "1"
+  }
+}
+```
+
+External MCP tool calls are intentionally separate from `COLIBRI_MCP_WRITE=1`.
diff --git a/live/operator-session/mcp-examples/external-mcp.sample.json b/live/operator-session/mcp-examples/external-mcp.sample.json
new file mode 100644
index 00000000..079057b4
--- /dev/null
+++ b/live/operator-session/mcp-examples/external-mcp.sample.json
@@ -0,0 +1,16 @@
+{
+  "servers": {
+    "demo": {
+      "command": "/usr/local/bin/demo-mcp-server",
+      "args": ["--stdio"],
+      "env": {
+        "DEMO_MODE": "1"
+      }
+    },
+    "filesystem-example": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/clawdie"],
+      "env": {}
+    }
+  }
+}
diff --git a/live/operator-session/mcp-examples/mcp-external-call.json b/live/operator-session/mcp-examples/mcp-external-call.json
new file mode 100644
index 00000000..e93fad72
--- /dev/null
+++ b/live/operator-session/mcp-examples/mcp-external-call.json
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "colibri-external-call": {
+      "command": "/usr/local/bin/colibri-mcp",
+      "args": [],
+      "env": {
+        "COLIBRI_MCP_EXTERNAL_CALL": "1"
+      }
+    }
+  }
+}
-- 
2.45.3