From d44427e71f25750c8dbe74d171eab4686b70c47d Mon Sep 17 00:00:00 2001 From: Mathias Bergqvist Date: Sat, 2 May 2026 23:03:45 +0200 Subject: [PATCH] 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) --- .aider.conventions.md | 18 +++++++++++++----- .context/PROJECT.md | 18 +++++++++++++----- .context/system-prompt.txt | 18 +++++++++++++----- .cursorrules | 18 +++++++++++++----- AGENTS.md | 18 +++++++++++++----- CLAUDE.md | 18 +++++++++++++----- README.md | 25 ++++++++++++++++++------- 7 files changed, 96 insertions(+), 37 deletions(-) diff --git a/.aider.conventions.md b/.aider.conventions.md index b15e5f3..7b43b74 100644 --- 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 diff --git a/.context/PROJECT.md b/.context/PROJECT.md index 3c89c4e..5ebfa1f 100644 --- 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 diff --git a/.context/system-prompt.txt b/.context/system-prompt.txt index 044bf47..1f8bd4c 100644 --- 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 diff --git a/.cursorrules b/.cursorrules index cf6b207..8717e56 100644 --- 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 diff --git a/AGENTS.md b/AGENTS.md index b15e5f3..7b43b74 100644 --- 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 diff --git a/CLAUDE.md b/CLAUDE.md index 3c89c4e..5ebfa1f 100644 --- 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 diff --git a/README.md b/README.md index 01a7204..0d17a7e 100644 --- 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