Booboo MCP Server

🐾 Booboo — the unified operational brain

Turn any AI system's data into one living, rooted 3D brain — structure + knowledge + memory + agents + automations fused into a single graph. Query it by REST or MCP, view it in your browser or as a desktop wallpaper, and boot your agents from it in one call.

Named after a dachshund who never forgets where the treats are buried. Fitting, because Booboo is about exactly that: memory and recall — seeing the whole system at once, fetching what's buried, never losing the thread.

Unretouched: booboo view --demo --nodes 50000 — 50k nodes, 4 layers, live in a browser tab, zero console errors. Try it yourself in one command.

Most tools show you one slice: a knowledge graph, an agent flow chart, a memory store, a trace viewer. Booboo fuses all of them into one graph rooted at a single point, so you can see — and query — how the whole system actually hangs together.

Status: alpha — seven packages published: @booboo-brain/spec (the contract), @booboo-brain/build (config-driven postgres/json adapters), @booboo-brain/serve (REST + MCP query layer), @booboo-brain/viewer (million-node 3D render), @booboo-brain/panel (the organigram), @booboo-brain/cli (the unified booboo command), and create-booboo (project scaffolder). Per-package semver — see each package.json. MIT.

---

The one idea

Booboo is a tiny JSON spec at the center, with adapters that feed it and consumers that render/serve/query it:

  your data ──▶  ADAPTERS  ──▶  GRAPH JSON ──▶  CONSUMERS
  (postgres,     (config-       (the spec,       (3D viewer ·
   json, neo4j,   driven,        ~1 KB            REST API ·
   mcp, …)        ~50 lines)     contract)        MCP server · wallpaper)

Emit the JSON → get the viewer, the API, and the MCP server for free. Weird data → a ~50-line adapter, not a fork. See SPEC.md.

Quickstart

npx create-booboo my-brain       # scaffold a project (json starter + postgres upgrade path)
cd my-brain
npm install
npm run build                    # booboo.config.yaml → brain.json (the snapshot)
npm run serve                    # REST API on http://localhost:8787
npm run mcp                      # MCP over stdio — point Claude / Cursor / Claude Code at it

Edit booboo.config.yaml to point at your own Postgres/Supabase (a commented example ships in the scaffold). Full reference: docs/CONFIG.md · stuck? docs/TROUBLESHOOTING.md.

The headline flex: Booboo renders a million-node brain at 60fps in your browser. Try it with booboo view --demo --nodes 1000000 (or the viewer playground: pnpm -F @booboo-brain/viewer dev, then open with ?n=1000000). See SCALE.md for how (instanced GPU field + tier-LOD).

Roadmap: a single all-in-one command bundling build + REST + MCP + the 3D viewer together, an interactive scaffold wizard, and a --demo mega-graph generator — tracked in LAUNCH_CHECKLIST.md.

What works today

booboo build --config booboo.config.yaml    # any postgres/json → one graph snapshot (privacy walls + parent spines)
booboo serve --snapshot my.booboo.json --port 8787   # REST: /graph /stats /search /nodes/:id /neighbors/:id /path/:a/:b
booboo mcp   --snapshot my.booboo.json --org org.booboo.json  # MCP over stdio (+ booboo_boot: agents boot FROM the org)
booboo view  --snapshot my.booboo.json               # 3D viewer in your browser — no monorepo, no build step
booboo panel --org org.booboo.json --snapshot my.booboo.json  # THE ORGANIGRAM — see below
booboo vault --snapshot my.booboo.json --org org.booboo.json --out vault  # the brain as a markdown vault — see below

booboo view serves the @booboo-brain/viewer 3D renderer as a standalone app — any snapshot (or ?n=1000000 synthetic) in your browser, no monorepo. The build engine was proven on a real 4,469-node production brain assembled straight from Supabase by config alone — privacy-walled, validated, served. See each package's README for the details.

Connect it to Claude / Cursor (MCP)

booboo mcp speaks MCP over stdio. Point any MCP client at it — no server to host, it runs on demand:

// Claude Desktop: claude_desktop_config.json · Cursor: .cursor/mcp.json · Claude Code: .mcp.json
{
  "mcpServers": {
    "booboo": {
      "command": "npx",
      "args": ["-y", "@booboo-brain/cli", "mcp",
               "--snapshot", "my.booboo.json", "--org", "org.booboo.json"]
    }
  }
}

Your agent can now query the whole system — search, neighbors, path, stats — and booboo_boot('<agent-id>') returns an agent's rules, memory reach, and reports so it boots from the org. Point --snapshot/--org at absolute paths if the client's working directory differs.

The Organigram — run your agents like a company

booboo panel opens your agent fleet as a real org chart — and the chart is not a diagram, it's the authority. Every agent is a card: its rules, skills, memory-bucket access, and latest reports. Drag an agent under a new parent, hit apply, and the org file changes — versioned in git, validated before every write (a cycle can never land). Agents that boot with booboo_boot obey the new shape on their next session. Reorganize your company at breakfast; the whole fleet knows by the first coffee.

Five tabs over one org file + one snapshot: organigram (drag-drop hierarchy) · buckets (who remembers what) · reports (what the fleet closed, newest first) · rules (who declares, who inherits) · graph (the 3D brain, embedded). Rules inherit top-down — declare once at a branch, everyone beneath is bound; every dossier shows the inherited stack in boot order.

The vault — your brain as plain markdown (Obsidian-ready)

booboo vault emits the same snapshot as a wiki-linked markdown vault: one page per node with frontmatter and its links, index pages per layer and cluster, an agent dossier per org member (chain of command, inherited rules, buckets, machines, contract). Open the folder as an Obsidian vault and you have the "LLM second brain" pattern — except generated from your real system instead of hand-fed notes. Plain files are the ultimate portability: any human can read them, any agent from any provider can too. Emit it nightly and the vault doubles as your insurance copy.

Author links yourself: put [[node-id]] (or [[exact label]]) refs inside a note's text and set wikilinks: true in the config — the builder turns them into first-class authored edges that outrank harvested relations, in the graph, the API, the 3D view and the vault. Every build also prints an ingestion-quality line (authored · orphans · dump-suspects) so curation is a number, not a vibe.

Your agent knows what to do — the contract ships with the scaffold

npx create-booboo scaffolds AGENTS.md (imported by CLAUDE.md) into the project: the operating doctrine any AI agent working that folder reads automatically — boot from the org, one atomic fact per note, author your [[links]], corrections replace, respect the walls, watch the quality gate, close honestly. A fresh install leaves your agent already fluent in the brain's conventions; edit the file as your own rules evolve — it is your system's constitution, versioned next to the org.

Why it's different

The closest things on GitHub each do one layer — good tools, all of them, for their slice:

None fuse wiring + knowledge + episodic memory + agents + crons into one rooted, live, bootable brain that's simultaneously a view, a wallpaper, an API, and an MCP source. That operational fusion is the novel part.

Key in hand (optional — everything above stays free)

Every feature is MIT and always will be. If you'd rather not do the setup yourself:

• The Booboo Drop — £29 · key in hand: a folder + operator prompt you paste into Claude Code or Cursor — your agent deploys your brain end-to-end while you answer five questions.
• Done-for-you · we map your stack — custom adapters, hosted snapshot, refresh pipeline.

Both are built on this repo, same config schema — never a fork, never a gate.

License

MIT — built to be forked, adapted, and shipped. By Fractional HQ.