# knowledge-mcp

Serves the estate's markdown knowledge (git working tree) over MCP so boxes query instead of cloning.
See `DESIGN.md` for the architecture and the migration plan. Tools: `list_docs`, `search`, `get_doc`.

## Run locally (stdio POC)
```bash
python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt   # needs python3-venv
KNOWLEDGE_DIR=./docs python server.py            # stdio
```

## Run on the MCP VM (remote, mesh-bound HTTP)
```bash
KNOWLEDGE_DIR=/srv/mallen-knowledge \
MCP_TRANSPORT=streamable-http \
MCP_HOST=<wt0 mesh IP> MCP_PORT=8970 \
python server.py
# behind host Caddy: reverse_proxy 127.0.0.1:8970, mesh-gated; or bind wt0 directly.
# keep KNOWLEDGE_DIR a git checkout: a cron/webhook `git pull` refreshes the served docs.
```

## Wire a box (Claude Code → remote)
```bash
claude mcp add --transport http knowledge https://knowledge.mallen.au/mcp \
  --header "Authorization: Bearer <per-box-token>" --scope user
claude mcp list      # confirm; in a session: /mcp
```

## Status
- `server.py` verified in a python:3.12 container with the real `mcp` SDK: 3 tools register, search/get
  work over the real ESTATE.md/SERVERS.md, path-traversal blocked.
- `docs/` here holds sample copies for the POC — real content lives in the `mallen-knowledge` git repo.
- Not yet deployed to the MCP VM (needs its access + the git repo) and no auth layer wired yet.