# ai-engineering-brain

面向 Claude Code 和其他 MCP Agent 的企业内部工程知识平台：把内部文档、代码仓库和长期记忆统一接入一个 MCP Gateway，并通过 Admin 页面管理文档、账户和 MCP Key。

> 当前最成熟、已完成 Docker 端到端验证的是 `kb-mcp` 知识库链路。`code-mcp` 和 `mem-mcp` 已接入统一 MCP 聚合接口，但仍处于骨架/持续完善阶段。

项目完整实施状态、故障原因与解决方法见：[docs/kb-mcp-project-status.md](docs/kb-mcp-project-status.md)。

## 能做什么

- **知识库**：导入 Markdown、TXT、DOCX；保留标题层级、表格、代码块和引用；父子分块；Qdrant dense+sparse 混合召回、RRF、可选 reranker。
- **Admin 管理**：EASTCOM 管理页面、文档上传/重试/删除、缺失文件记录清理、账户登录与 RBAC。
- **账户归属 MCP Key**：账户登录后创建、查看、复制、显示/隐藏和撤销自己的 MCP Key；完整 Key 加密保存，不写入日志。
- **统一 MCP**：客户端只连接 Gateway 的一个 `/mcp` 地址；Gateway 将 `kb_*`、`code_*`、`mem_*` 工具聚合到一起。
- **局域网部署**：服务运行在一台 Docker 主机，其他 Agent 通过局域网访问 Gateway。

## 架构

```text
Claude Code / Other Agents
          │  HTTP MCP + Bearer MCP Key
          ▼
Gateway :8000/mcp  ← 唯一对外 MCP 接口
          │
    ┌─────┼─────────────┐
    ▼     ▼             ▼
 kb-mcp  code-mcp      mem-mcp
 :8100   :8101         :8102
    │       │             │
    └───────┴──────┬──────┘
                   ▼
          Postgres + Qdrant

Admin :9001  ← 文档、账户、MCP Key 管理页面
```

外部客户端只需要知道：

```text
MCP:   http://<服务器局域网IP>:8000/mcp
Admin: http://<服务器局域网IP>:9001/
```

内部 `8100/8101/8102` 不需要给其他 Agent 配置。

## 工具命名

统一 MCP 中的工具使用服务前缀：

```text
kb_search
kb_list_documents

code_search_code
code_grep_code
code_query_git_history
code_get_commit_diff
code_get_file_at_version

mem_save_memory
mem_search_memory
```

当前 `code-mcp`、`mem-mcp` 的部分工具仍是骨架实现，后续可以在不改变客户端地址的情况下继续补齐。

## 快速安装

### 前置条件

- Docker Desktop（Windows + WSL2）或 Docker Engine + Docker Compose v2；
- Linux/macOS：Bash、`curl`、`openssl`、Python 3；
- Windows：PowerShell、Docker Desktop；
- 如果需要模型下载，宿主机/容器需要访问 Hugging Face；无法直连时准备 HTTP 代理。

### Linux / macOS

```bash
git clone https://github.com/arui-git/ai-engineering-brain.git
cd ai-engineering-brain
chmod +x install.sh
./install.sh
```

安装脚本会交互询问：

- `MCP_KEY_ENCRYPTION_KEY`：直接回车则随机生成；已有值不会覆盖；升级时必须保持不变；
- Admin 初始用户名：直接回车默认 `admin`；
- Admin 初始密码：直接回车则随机生成；仅空数据库首次启动使用；
- 模型下载网络提示：如果 Hugging Face 不可访问，在 `.env` 填写 `KB_HTTP_PROXY` / `KB_HTTPS_PROXY`；reranker 较大，可设置 `RERANKER_ENABLED=0` 使用 RRF fallback。

### Windows PowerShell

```powershell
git clone https://github.com/arui-git/ai-engineering-brain.git
Set-Location ai-engineering-brain
.\install.ps1
```

如果 PowerShell 执行策略阻止脚本，可以在当前窗口执行：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1
```

### 安装完成后

安装脚本会输出 Admin 和 MCP 地址。登录 Admin：

```text
http://<服务器IP>:9001/
```

进入 **MCP 密钥** 页面创建账户归属的 Key，然后在其他 Agent 机器执行：

```bash
claude mcp add --transport http aeb \
  http://<服务器IP>:8000/mcp \
  --header "Authorization: Bearer <MCP_KEY>"
```

或使用客户端脚本：

```bash
./claude/setup-claude.sh http://<服务器IP>:8000 <MCP_KEY>
```

检查 Claude Code：

```bash
claude mcp list
```

## 配置说明

`.env` 不提交到 Git。首次安装会写入部分随机值；参考模板：

```bash
cp .env.example .env
```

关键配置：

| 配置 | 作用 |
|---|---|
| `POSTGRES_PASSWORD` | Postgres 密码，安装脚本生成 |
| `MCP_KEY_ENCRYPTION_KEY` | 加密 MCP Key 的 Fernet 密钥，必须长期保留 |
| `ADMIN_BOOTSTRAP_USER/PASSWORD` | 空数据库首次初始化账户 |
| `MCP_KEY_ENV_COMPAT` | 旧 `API_KEYS` 兼容开关，迁移后建议设为 `0` |
| `API_KEYS` | 旧 Gateway Key 兼容机制，不建议作为长期方案 |
| `KB_HTTP_PROXY` / `KB_HTTPS_PROXY` | Hugging Face 模型下载代理 |
| `RERANKER_ENABLED` | 是否启用 bge reranker；关闭后使用 RRF fallback |

不要提交以下内容：

```text
.env
ADMIN_KEY
API_KEYS
MCP_KEY_ENCRYPTION_KEY
ADMIN_BOOTSTRAP_PASSWORD
MCP Key 明文
```

## 常用命令

查看服务：

```bash
docker compose ps
```

查看安装/模型日志：

```bash
docker compose logs -f kb-mcp
docker compose logs -f gateway
docker compose logs -f admin
```

健康检查：

```bash
curl http://127.0.0.1:8000/healthz
curl -I http://127.0.0.1:9001/
```

检查数据库账户和 MCP Key 表：

```bash
docker compose exec -T postgres psql -U aeb -d aeb -c '\dt admin_*'
docker compose exec -T postgres psql -U aeb -d aeb -c '\d mcp_api_keys'
```

验证配置和语法：

```bash
docker compose config --quiet
python3 -m py_compile services/admin/app/*.py services/kb-mcp/app/*.py services/gateway/app/*.py
node --check services/admin/app/static/admin.js
bash -n install.sh claude/setup-claude.sh
```

## 数据与升级

数据存放在 Docker volumes：

```text
pg_data       账户、MCP Key 元数据、文档状态
qdrant_data   向量索引
kb_docs       原始文档
model_cache   embedding/reranker 模型
repos         代码仓库数据
```

升级前建议备份 Postgres 和重要文档。普通升级：

```bash
git pull
docker compose build
docker compose up -d
```

不要执行：

```bash
docker compose down -v
```

该命令会删除数据卷。

## 局域网访问

如果 Docker 主机局域网 IP 是 `192.168.1.10`：

```text
Admin: http://192.168.1.10:9001/
MCP:   http://192.168.1.10:8000/mcp
```

先从其他机器测试：

```bash
curl http://192.168.1.10:8000/healthz
curl -I http://192.168.1.10:9001/
```

Windows + WSL2 mirrored networking 下，如果 WSL 内部和 Windows `localhost` 可访问，但 Windows/局域网 IP 超时，需要检查 WSL mirrored/Hyper-V 网络策略、Docker Desktop 端口发布和局域网入站规则。项目服务监听和 Compose 发布本身应保持：

```text
0.0.0.0:8000 -> Gateway
0.0.0.0:9001 -> Admin
```

生产环境不要直接把 HTTP 管理页暴露到不可信网络；建议使用 VPN、内网防火墙或 HTTPS 反向代理，并定期撤销/轮换 MCP Key。

## 当前限制

- `code-mcp` 当前是代码仓库能力骨架，完整 Git 元数据库和 AST 索引仍待补齐；
- `mem-mcp` 当前是记忆层骨架，mem0 自动抽取/hook 仍待补齐；
- reranker 模型体积较大，网络不稳定时可能保持 unavailable，核心检索会回退到 RRF；
- Admin 当前适合内网测试，生产需要 HTTPS/VPN/防火墙；
- 文档分类体系（项目、文档类型、标签）是下一阶段增强方向。

## 目录

```text
services/kb-mcp/       知识库解析、摄入、检索
services/gateway/      唯一对外 MCP、Bearer 鉴权、工具聚合
services/admin/        Admin 页面、账户和 MCP Key
services/code-mcp/     代码能力骨架
services/mem-mcp/      记忆能力骨架
docs/                  设计、部署、稳定性和项目状态文档
claude/                Claude Code 接入脚本与检索行为规则
```

## License

当前仓库尚未声明正式开源许可证。如需公开分发，请在发布前补充 LICENSE 文件并明确第三方模型、依赖和文档的使用权限。