# LightRAG Code Brain MCP

LightRAG Code Brain MCP turns a local LightRAG server into a persistent project
brain for coding agents such as Claude Code and Codex.

It provides:

- whole-codebase indexing with conservative default excludes and secret redaction
- multi-repo source names with `repo_id:relative/path`
- RAG query/context/data tools
- durable memory across sessions
- senior-developer project profile sections
- a task gate that encourages agents to load/update memory for non-trivial work

## What This Solves

Coding agents often reread the same files, forget prior fixes, and lose setup
history between sessions. This MCP gives them a durable memory layer:

- architecture and module boundaries
- conventions, workflows, and hazards
- debugging playbooks and failed attempts
- setup outcomes and provider quirks
- current project profile and handoff notes

It does not replace reading source files for exact edits. It reduces discovery
tokens and gives the agent a senior-engineer orientation before it opens files.

## Requirements

- Docker with Compose
- Python 3.10+
- A chat/LLM provider compatible with OpenAI chat completions
- An embeddings provider compatible with OpenAI `/v1/embeddings`
- Claude Code and/or Codex if you want agent integration

## Quick Start

```bash
git clone https://github.com/YOUR_ORG/lightrag-code-brain-mcp.git
cd lightrag-code-brain-mcp
cp .env.example .env
```

Edit `.env`:

```bash
LIGHTRAG_AUTH_ACCOUNTS="admin:your-password"
LIGHTRAG_USERNAME="admin"
LIGHTRAG_PASSWORD="your-password"
LIGHTRAG_TOKEN_SECRET="a-long-random-string"

LIGHTRAG_LLM_BINDING_HOST="https://api.openai.com/v1"
LIGHTRAG_LLM_API_KEY="..."
LIGHTRAG_LLM_MODEL="gpt-4o-mini"

LIGHTRAG_EMBEDDING_BINDING_HOST="https://api.openai.com/v1"
LIGHTRAG_EMBEDDING_API_KEY="..."
LIGHTRAG_EMBEDDING_MODEL="text-embedding-3-large"
LIGHTRAG_EMBEDDING_DIM="3072"
```

Start LightRAG:

```bash
docker compose up -d
curl http://127.0.0.1:9621/health
```

## NVIDIA NIM Embeddings

If you use NVIDIA NIM, this model worked with LightRAG's OpenAI-compatible
embedding call because it does not require `input_type`:

```bash
LIGHTRAG_EMBEDDING_BINDING_HOST="https://integrate.api.nvidia.com/v1"
LIGHTRAG_EMBEDDING_API_KEY="nvapi-..."
LIGHTRAG_EMBEDDING_MODEL="nvidia/nv-embed-v1"
LIGHTRAG_EMBEDDING_DIM="4096"
```

Some NVIDIA embedding models require `input_type`; those may fail through
LightRAG's default OpenAI embedding request.

## Install In Codex

```bash
export LIGHTRAG_URL="http://127.0.0.1:9621"
export LIGHTRAG_USERNAME="admin"
export LIGHTRAG_PASSWORD="your-password"
export LIGHTRAG_DEFAULT_REPO_ROOT="/path/to/your/project"
export LIGHTRAG_DEFAULT_REPO_ID="my-project"
./install-codex.sh
codex mcp list
```

This runs:

```bash
codex mcp add lightrag-code-brain \
  --env LIGHTRAG_URL=http://127.0.0.1:9621 \
  --env LIGHTRAG_USERNAME=admin \
  --env LIGHTRAG_PASSWORD=your-password \
  --env LIGHTRAG_DEFAULT_REPO_ROOT=/path/to/your/project \
  --env LIGHTRAG_DEFAULT_REPO_ID=my-project \
  -- python /absolute/path/lightrag_mcp_server.py
```

## Install In Claude Code

```bash
export LIGHTRAG_URL="http://127.0.0.1:9621"
export LIGHTRAG_USERNAME="admin"
export LIGHTRAG_PASSWORD="your-password"
export LIGHTRAG_DEFAULT_REPO_ROOT="/path/to/your/project"
export LIGHTRAG_DEFAULT_REPO_ID="my-project"
./install-claude.sh
```

Copy the generated `.mcp.json` into your Claude Code project root, or merge the
`mcpServers` entry into an existing `.mcp.json`.

Examples are also provided in `examples/`:

- `examples/claude-mcp.json`
- `examples/codex-install.sh`
- `examples/AGENTS-snippet.md`

## Recommended Agent Instructions

Add this to your project `CLAUDE.md`, `AGENTS.md`, or equivalent:

```md
Use the LightRAG MCP server as persistent project memory.

For non-trivial implementation/debugging/setup work:
- call `brain_begin` first
- use `senior_brief` for architecture/conventions/hazards
- use `brain_search` for prior fixes/failures when something is broken
- use `rag_index_repo` for whole-codebase indexing when needed
- after meaningful work, call `brain_remember`
- call `profile_upsert` when architecture/conventions/workflows/hazards change
- call `brain_finish` before final response
```

## Tool Overview

RAG tools:

- `rag_ask`
- `rag_get_context`
- `rag_query_data`
- `rag_status`
- `rag_clear`
- `rag_index_repo`
- `rag_list_documents`
- `rag_track_status`
- `rag_reprocess_failed`
- `rag_cancel_pipeline`
- `rag_webui`

Memory tools:

- `brain_remember`
- `brain_search`
- `brain_recent`
- `brain_reindex`
- `brain_begin`
- `brain_finish`
- `brain_gate_status`

Senior project profile tools:

- `profile_bootstrap`
- `profile_get`
- `profile_upsert`
- `profile_search`
- `senior_brief`

## Whole-Codebase Indexing

Use `rag_index_repo`:

```json
{
  "root": "/path/to/project",
  "repo_id": "my-project",
  "dry_run": true,
  "limit": 1000
}
```

Then run without `dry_run`.

Defaults intentionally skip:

- `.env`, MCP config, local memory files
- `.git`, `.venv`, caches, logs, lockfiles
- `node_modules`, build/dist output
- LightRAG storage and generated data
- backup/temp/database/log files
- files larger than 256 KiB

Secret-looking values are redacted before indexing.

## Multi-Repo Support

Pass a stable `repo_id` for each repository:

```json
{
  "root": "/work/project-a",
  "repo_id": "project-a"
}
```

Documents are indexed as:

```text
project-a:relative/path.py
```

This keeps references distinguishable across repositories.

## Publish Your Own Copy

```bash
git init
git add .
git commit -m "Initial LightRAG Code Brain MCP"
gh repo create lightrag-code-brain-mcp --public --source=. --remote=origin --push
```

Before publishing, confirm `.env` is not staged:

```bash
git status --short
```

## Troubleshooting

Check LightRAG:

```bash
docker compose ps
docker compose logs --tail=100 lightrag
curl http://127.0.0.1:9621/health
```

Common issues:

- `401`: wrong `LIGHTRAG_USERNAME` / `LIGHTRAG_PASSWORD`
- embedding `404`: provider does not expose `/v1/embeddings`
- NVIDIA `input_type required`: use `nvidia/nv-embed-v1` or another compatible model
- no context after indexing: wait for pipeline completion, then check `rag_status`

## Security Notes

- Do not commit `.env`.
- Keep LightRAG bound to `127.0.0.1` unless you know what you are doing.
- Rotate credentials if you accidentally indexed secrets before redaction.
- Review `rag_index_repo` dry-run output before first full indexing.