内容
# SimBrain
[简体中文](README_zh-CN.md) | English
SimBrain 逐步将本地文档摄入 Elasticsearch，并为摄入、项目检查、进度监控和检索提供 MCP 工具和命令行接口（CLI）。
## 快速开始
SimBrain 默认使用本地 Ollama，地址为 `http://localhost:11434`，模型为 `bge-m3`。首先启动 Ollama 并安装模型：
```bash
ollama pull bge-m3
```
所有使用模式都需要 Elasticsearch。至少配置其端点和身份验证：
```dotenv
ES_URL=https://your-es-host:9200
ES_API_KEY=your_es_api_key
```
参见 [.env.example](.env.example) 获取所有字段和默认值。从源码运行 SimBrain 时，将其复制到 `.env`：
```bash
cp .env.example .env
```
`MINERU_API_TOKEN` 为可选配置。当配置后，MinerU 将优先用于 PDF 解析；否则 SimBrain 将回落到 pypdf。
支持的文档格式：PDF、DOCX、TXT、TEXT、Markdown、CSV 和 XLSX。
## 与 MCP 一起使用
SimBrain 通过标准输入/输出（stdio）暴露一个 MCP 服务器。在 PyPI 发布后，可以使用以下命令启动：
```bash
uvx --from simbrain simbrain-mcp
```
服务器暴露以下工具：
| 工具 | 参数 | 用途 |
| --- | --- | --- |
| `simbrain-ingest` | `input_dir`、`output_dir`、`project` | 增量摄入 |
| `simbrain-status` | `output_dir` | 列出所有项目 |
| `simbrain-status-realtime` | `output_dir`、`project` | 监控摄入进度 |
| `simbrain-search` | `question`、`project`、`top_k` | 混合向量和关键词检索 |
### Codex 配置
将以下内容添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.simbrain]
command = "uvx"
args = ["--from", "simbrain", "simbrain-mcp"]
[mcp_servers.simbrain.env]
ES_URL = "https://your-es-host:9200"
ES_API_KEY = "your_es_api_key"
MINERU_API_TOKEN = "your_mineru_token"
```
或从命令行注册：
```bash
codex mcp add simbrain \
--env ES_URL=https://your-es-host:9200 \
--env ES_API_KEY=your_es_api_key \
--env MINERU_API_TOKEN=your_mineru_token \
-- uvx --from simbrain simbrain-mcp
```
### Claude Desktop 配置
在 `claude_desktop_config.json` 的 `mcpServers` 下添加以下条目：
```json
{
"simbrain": {
"command": "uvx",
"args": ["--from", "simbrain", "simbrain-mcp"],
"env": {
"ES_URL": "https://your-es-host:9200",
"ES_API_KEY": "your_es_api_key",
"MINERU_API_TOKEN": "your_mineru_token"
}
}
}
```
如果不需要 MinerU，请移除 `MINERU_API_TOKEN`。所有剩余设置均使用 [.env.example](.env.example) 中的默认值。要使用兼容 OpenAI 的嵌入服务，请同时设置 `EMBEDDING_PROVIDER`、`EMBEDDING_URL`、`EMBEDDING_API_KEY` 和 `EMBEDDING_MODEL`。
## 与命令行接口（CLI）一起使用
以下示例使用 PyPI 包。在开发此存储库时，请将 `uvx --from simbrain` 替换为 `uv run`。
### 增量摄入
```bash
uvx --from simbrain simbrain-ingest \
--input-dir ./docs \
--output-dir ./output \
--project 我的知识库
```
具有相同名称的文件将被更新，不变的文件将被跳过，历史文件将从当前输入中省略。
### 列出所有项目
```bash
uvx --from simbrain simbrain-status --output-dir ./output
```
### 监控摄入进度
```bash
uvx --from simbrain simbrain-status \
--output-dir ./output \
--project 我的知识库
```
### 搜索项目
```bash
uvx --from simbrain simbrain-search \
--question "如何配置访问权限？" \
--project 我的知识库 \
--top-k 10
```
`top-k` 必须介于 1 和 100 之间。结果包含源代码块和元数据；SimBrain 不生成 LLM 答案。
## 输出和测试
成功的 CLI 调用返回 JSON。进度命令在状态更改时发出 JSON Lines。
运行测试：
```bash
uv run pytest -q
```
包含 Elasticsearch 集成测试：
```bash
SIMBRAIN_TEST_ES_URL=http://localhost:9200 uv run pytest -q -m integration
```
