Metadata-Version: 2.4
Name: brein-mcp
Version: 0.5.10
Summary: A policy-aware MCP server for an org-wide knowledge brain that lives in a git repo.
Project-URL: Homepage, https://brein.sh
Project-URL: Repository, https://github.com/brein-sh/brein
Author: brein
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: fastembed>=0.7.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: tomli-w>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://brein.sh"><img src="assets/brain.gif" alt="brein" width="320"></a>
</p>

<h1 align="center">brein</h1>

<p align="center"><em>a brain that lives in your company.</em></p>

brein is a local MCP server for a company memory that lives in git: markdown docs in your repo, readable and writable by AI agents. Works with Claude Code, Cursor, Codex, Hermes, and any stdio MCP client.

Website: https://brein.sh

## Quickstart

```bash
npx brein init
```

Walks you through the brain repo, paths, eval, and MCP client config. Then restart your client and verify with `brein doctor`.

Requirements: Node, Python 3.11+, `git`, an MCP-capable client.

<details><summary>From source</summary>

```bash
git clone https://github.com/brein-sh/brein && cd brein
uv sync
brein setup
brein mcp claude
```

</details>

## CLI

```bash
brein setup [section]   # all sections, or one of: repo paths vector eval mcp
brein doctor            # ok/warn/fail health checks
brein mcp <client>      # claude | cursor | codex | generic
brein config            # show resolved config
brain-eval --limit 20   # local retrieval evals against $BRAIN_REPO
```

## Tools exposed over MCP

| Tool | Purpose |
| --- | --- |
| `brain_search(query, mode="hybrid")` | Keyword / vector / hybrid retrieval with optional rerank. |
| `brain_evidence(question)` | Ranked docs + snippets + excerpts + citations in one round-trip. The client agent writes the final answer. |
| `brain_update(file_path, content, commit_message, mode)` | Write to an allowed path, validate, commit, push. |
| `brain_audit()` | Repo cleanliness, doc/frontmatter counts, log + index health. |
| `brain_retrieval_log(...)` | Telemetry; search auto-logs. |

For plain reads / listings, agents use their normal file tools (`Read`, `Glob`, `Grep`) against the brain repo directly — the MCP only mediates what plain tools can't do: semantic search and policy-gated writes.

Write policy: paths under `docs/`, `skills/`, `templates/`, plus `AGENTS.md` / `README.md` / `CONTRIBUTING.md` at the root. Secrets are pattern-blocked.

## Configuration

`brein setup` writes `~/.brein/config.json`. Environment variables override the file and are documented in [`src/brain_mcp/config.py`](src/brain_mcp/config.py). The big ones:

- `BRAIN_REPO` — path to your brain git repo (required)
- `BRAIN_RETRIEVAL_LOG` — JSONL telemetry path
- `BRAIN_VECTOR_INDEX` — vector index cache path
- `BRAIN_EMBEDDING_MODEL` — fastembed model (default `BAAI/bge-small-en-v1.5`)

## Project layout

```text
src/brain_mcp/          MCP server + `brein` CLI
src/brain_mcp/_scripts/ bundled helpers (eval, index, validate)
```

## Contributing

Issues and PRs welcome. See `CONTRIBUTING.md`.

## License

MIT. See `LICENSE`.
