docs: document brain MCP endpoint at koala:30330

- README architecture diagram now shows two MCP servers (supervisor + brain) with the brain hosted by ingestion directly. - Connect-a-project example includes both servers. - .context/PROJECT.md replaces the boilerplate "Knowledge base access" block with the actual hyperguild MCP endpoints. - Adapters regenerated via task context:sync. Captures the transitional state where two MCPs coexist; the supervisor MCP will shrink as skill workers move to SKILL.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 23:03:45 +02:00
parent 2635cdcaa7
commit d44427e71f
7 changed files with 96 additions and 37 deletions
--- a/.aider.conventions.md
+++ b/.aider.conventions.md
@@ -216,13 +216,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding

-## Knowledge base access
+## MCP endpoints

-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:

- **MCP endpoint**: `mcp://localhost:3100/knowledge`
- **HTTP fallback**: `http://localhost:3100/api/v1/search`
- **Scoping**: queries are filtered to collection `personal` + `public`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.

 ## Agent instructions

--- a/.context/PROJECT.md
+++ b/.context/PROJECT.md
@@ -45,13 +45,21 @@
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding

-## Knowledge base access
+## MCP endpoints

-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:

- **MCP endpoint**: `mcp://localhost:3100/knowledge`
- **HTTP fallback**: `http://localhost:3100/api/v1/search`
- **Scoping**: queries are filtered to collection `personal` + `public`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.

 ## Agent instructions

--- a/.context/system-prompt.txt
+++ b/.context/system-prompt.txt
@@ -221,13 +221,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding

-## Knowledge base access
+## MCP endpoints

-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:

- **MCP endpoint**: `mcp://localhost:3100/knowledge`
- **HTTP fallback**: `http://localhost:3100/api/v1/search`
- **Scoping**: queries are filtered to collection `personal` + `public`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.

 ## Agent instructions

--- a/.cursorrules
+++ b/.cursorrules
@@ -219,13 +219,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding

-## Knowledge base access
+## MCP endpoints

-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:

- **MCP endpoint**: `mcp://localhost:3100/knowledge`
- **HTTP fallback**: `http://localhost:3100/api/v1/search`
- **Scoping**: queries are filtered to collection `personal` + `public`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.

 ## Agent instructions

--- a/AGENTS.md
+++ b/AGENTS.md
@@ -216,13 +216,21 @@ Key skills:
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding

-## Knowledge base access
+## MCP endpoints

-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:

- **MCP endpoint**: `mcp://localhost:3100/knowledge`
- **HTTP fallback**: `http://localhost:3100/api/v1/search`
- **Scoping**: queries are filtered to collection `personal` + `public`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.

 ## Agent instructions

--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,13 +45,21 @@
 - Client data never leaves local network unless explicitly cleared
 - Dependencies: audit with `govulncheck` before adding

-## Knowledge base access
+## MCP endpoints

-This project can query the shared knowledge base via MCP or HTTP:
+Two MCP servers expose this project's tooling, both reachable over Tailscale:

- **MCP endpoint**: `mcp://localhost:3100/knowledge`
- **HTTP fallback**: `http://localhost:3100/api/v1/search`
- **Scoping**: queries are filtered to collection `personal` + `public`
+- **`brain`** at `http://koala:30330/mcp` — preferred path for `brain_query`,
+  `brain_write`, `brain_ingest`, `brain_ingest_raw`, and `session_log`. Hosted
+  by the ingestion service directly.
+- **`supervisor`** at `http://koala:30320/mcp` — skill workers (`tdd_red`,
+  `tdd_green`, `tdd_refactor`, `review`, `debug`, `spec`, `retrospective`,
+  `trainer`, `tier`). Will shrink as skill workers move to SKILL.md in a later
+  migration.
+
+The brain HTTP REST API (`/query`, `/write`, `/ingest`, `/ingest-raw`,
+`/ingest-path`, `/backfill-refs`) remains available on the same port (3300) for
+shell scripts and non-MCP clients.

 ## Agent instructions

--- a/README.md
+++ b/README.md
@@ -11,9 +11,10 @@ into a searchable brain.
 Your Claude Code session (in any project)
    │
    │  MCP over HTTP (Tailscale)
-    ▼
-supervisor  :3200 (NodePort 30320 on koala) — skill workers: tdd, retrospective
-ingestion   :3300                            — brain HTTP API: query wiki, write notes
+    ├──▶ supervisor  :3200 (NodePort 30320 on koala) — skill workers: tdd, debug, spec, …
+    └──▶ brain       :3300 (NodePort 30330 on koala) — brain_query, brain_write, brain_ingest, session_log
+                       │
+                       └─ also serves the legacy REST endpoints (/query, /write, /ingest, …)
    │
    ▼
 brain/
@@ -57,16 +58,26 @@ Create `.mcp.json` in your project root:
    "supervisor": {
      "type": "http",
      "url": "http://koala:30320/mcp"
+    },
+    "brain": {
+      "type": "http",
+      "url": "http://koala:30330/mcp"
    }
  }
 }
 ```

-The supervisor MCP server is reachable over Tailscale at `koala:30320` (NodePort
-to the in-cluster service on port 3200). No local binary or stdio shim is
-required — Claude Code talks to it directly via HTTP.
+Two MCP servers are exposed today, both reachable over Tailscale:

-Open Claude Code in your project — run `/mcp` to confirm `supervisor` is listed.
+- **`supervisor`** at `koala:30320` — skill workers (`tdd_red/green/refactor`,
+  `review`, `debug`, `spec`, `retrospective`, `trainer`, `tier`).
+- **`brain`** at `koala:30330` — knowledge access (`brain_query`, `brain_write`,
+  `brain_ingest`, `brain_ingest_raw`) and `session_log`. Hosted by the ingestion
+  service directly, no separate pod.
+
+No local binary or stdio shim is required — Claude Code talks to both via HTTP.
+
+Open Claude Code in your project — run `/mcp` to confirm both servers are listed.

 ## A typical TDD session