# brain-mcp

MCP server exposing the Brain wiki to other agents: read/search + append-only writes.

## Run locally (stdio)

Register at **user scope** so it's available in every Claude Code session:

```json
{
  "mcpServers": {
    "brain": {
      "command": "brain-mcp",
      "env": {
        "BRAIN_ROOT": "/Users/shanzer/Documents/Brain",
        "BRAIN_MANIFEST": "/Users/shanzer/source/brain/brain-mcp.config.json"
      }
    }
  }
}
```

> `BRAIN_MANIFEST` must be an absolute path to `brain-mcp.config.json` in this repo — the
> manifest lives in the project directory, not inside the vault.

### Stdio smoke test

```bash
cd ~/source/brain
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| BRAIN_ROOT="/Users/shanzer/Documents/Brain" \
  BRAIN_MANIFEST="/Users/shanzer/source/brain/brain-mcp.config.json" \
  brain-mcp
```

Expected: two JSON-RPC responses; the second lists 8 tools.

## Run as a network service (HTTP)

```bash
BRAIN_TRANSPORT=http BRAIN_PORT=3005 \
BRAIN_TOKEN=… BRAIN_ALLOWED_HOSTS=localhost,yoyodyne.local \
BRAIN_ROOT=/path/to/synced/Brain \
BRAIN_MANIFEST=/path/to/brain-mcp/brain-mcp.config.json \
brain-mcp
```

Smoke test:
```bash
curl -s localhost:3005/health
```

Remote client stanza:
```json
{ "mcpServers": { "brain": { "url": "http://storm.local:3005/mcp",
  "headers": { "Authorization": "Bearer <token>" } } } }
```

## Tools

- `brain_search`, `brain_read`, `brain_map`, `brain_pending` (read)
- `brain_submit_source`, `brain_append_journal`, `brain_add_note`, `brain_deposit` (append/create-only)

### brain_append_journal — entry placement

`brain_append_journal` inserts a timestamped bullet **directly under the chosen `## Section`
heading** — after any existing bullets in that section, immediately before the next `## `
heading (or EOF for the last section). The entry shape is:

```
- YYYY-MM-DD HH:MM — your content here
```

Downstream journal-processing agents should expect entries nested under their section
headings (`## Work`, `## Personal`, `## Notes & Ideas`), not as labeled blocks at end of
file.

## Graph view (HTTP transport only)

- `GET /graph` — full wikilink graph as JSON (`{nodes, edges, stats}`), gated by the
  same allowlist + bearer token as `/mcp`. Nodes are every `.md` page; unresolved
  `[[targets]]` appear as `ghost: true` nodes; attachment embeds are skipped.
- `GET /graph/view` — self-contained Obsidian-style interactive viewer
  (`static/graph.html`). Allowlist-gated only; the page prompts for the bearer token
  (stored in that browser's localStorage) and fetches `/graph` same-origin.

```bash
curl -s -H "Authorization: Bearer <token>" localhost:3005/graph | jq .stats
open http://localhost:3005/graph/view
```

## Deposit registry

Edit `brain-mcp.config.json` and restart to add targets. See the design spec.

## launchd (macOS background service)

A plist template lives at `docs/launchd/com.brain-mcp.plist`. To install:

```bash
cp docs/launchd/com.brain-mcp.plist ~/Library/LaunchAgents/
# Edit the copy: replace REPLACE_WITH_NODE_PATH with the output of `which node`
# (e.g. an nvm path or /opt/homebrew/bin/node) and REPLACE_WITH_TOKEN with your bearer token.
chmod 600 ~/Library/LaunchAgents/com.brain-mcp.plist   # file holds the token
launchctl load ~/Library/LaunchAgents/com.brain-mcp.plist
```

> **Security:** the plist holds `BRAIN_TOKEN` in plaintext — `chmod 600` is required.
> Never commit a filled-in token. The template ships with `REPLACE_WITH_TOKEN`.