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。

能做什么

知识库：导入 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。

架构

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 管理页面

外部客户端只需要知道：

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

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

工具命名

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

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

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

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

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

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

安装完成后

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

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

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

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

或使用客户端脚本：

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

检查 Claude Code：

claude mcp list

配置说明

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

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

不要提交以下内容：

.env
ADMIN_KEY
API_KEYS
MCP_KEY_ENCRYPTION_KEY
ADMIN_BOOTSTRAP_PASSWORD
MCP Key 明文

常用命令

查看服务：

docker compose ps

查看安装/模型日志：

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

健康检查：

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

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

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'

验证配置和语法：

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：

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

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

git pull
docker compose build
docker compose up -d

不要执行：

docker compose down -v

该命令会删除数据卷。

局域网访问

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

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

先从其他机器测试：

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 发布本身应保持：

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/防火墙；
文档分类体系（项目、文档类型、标签）是下一阶段增强方向。

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

License

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