ai-engineering-brain

An internal enterprise engineering knowledge platform for Claude Code and other MCP Agents: unify internal documentation, code repositories, and long-term memory into a single MCP Gateway, and manage documents, accounts, and MCP Keys through the Admin page.

The most mature and Docker end-to-end verified path is the kb-mcp knowledge base pipeline. code-mcp and mem-mcp are already connected to the unified MCP aggregation interface, but are still in the skeleton/continuous improvement stage.

See docs/kb-mcp-project-status.md for the full project implementation status, failure causes, and solutions.

Features

• Knowledge Base: Import Markdown, TXT, DOCX; preserve heading hierarchy, tables, code blocks, and quotes; parent-child chunking; Qdrant dense+sparse hybrid retrieval, RRF, optional reranker.

• Admin Management: EASTCOM admin page, document upload/retry/delete, missing file record cleanup, account login and RBAC.

• Account-bound MCP Keys: After logging in, users can create, view, copy, show/hide, and revoke their own MCP Keys; full keys are encrypted at rest and never written to logs.

• Unified MCP: Clients only connect to a single /mcp endpoint on the Gateway; the Gateway aggregates kb_*, code_*, and mem_* tools.

• LAN Deployment: Services run on a single Docker host; other Agents access the Gateway over the LAN.

Related MCP server: MCP Gateway

Architecture

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

External clients only need to know:

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

The internal 8100/8101/8102 ports do not need to be configured for other Agents.

Tool Naming

Tools in the unified MCP use a service prefix:

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

Some tools in code-mcp and mem-mcp are still skeleton implementations; they can be completed later without changing the client address.

Quick Start

Prerequisites

• Docker Desktop (Windows + WSL2) or Docker Engine + Docker Compose v2;

• Linux/macOS: Bash, curl, openssl, Python 3;

• Windows: PowerShell, Docker Desktop;

• If model download is needed, the host/container must be able to reach Hugging Face; if direct connection is not possible, prepare an HTTP proxy.

Linux / macOS

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

The install script will interactively ask:

• MCP_KEY_ENCRYPTION_KEY: press Enter to generate a random one; existing values are not overwritten; must remain unchanged during upgrades;

• Admin initial username: press Enter for default admin;

• Admin initial password: press Enter to generate a random one; only used on first startup with an empty database;

• Model download network prompt: if Hugging Face is not reachable, set KB_HTTP_PROXY / KB_HTTPS_PROXY in .env; the reranker is large, so you can set RERANKER_ENABLED=0 to use the RRF fallback.

Windows PowerShell

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

If the PowerShell execution policy blocks the script, run the following in the current window:

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

After Installation

The install script will output the Admin and MCP addresses. Log in to Admin:

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

Go to the MCP Keys page to create an account-bound key, then on the other Agent machines run:

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

Or use the client script:

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

Check Claude Code:

claude mcp list

Configuration

.env is not committed to Git. Some random values are written on first install; see the template:

cp .env.example .env

Key configuration:

Do not commit the following:

.env
ADMIN_KEY
API_KEYS
MCP_KEY_ENCRYPTION_KEY
ADMIN_BOOTSTRAP_PASSWORD
MCP Key 明文

Common Commands

View services:

docker compose ps

View install/model logs:

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

Health check:

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

Check database accounts and MCP Key tables:

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'

Validate configuration and syntax:

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

Data & Upgrades

Data is stored in Docker volumes:

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

It is recommended to back up Postgres and important documents before upgrading. Normal upgrade:

git pull
docker compose build
docker compose up -d

Do not run:

docker compose down -v

This command will delete data volumes.

LAN Access

If the Docker host's LAN IP is 192.168.1.10:

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

First test from another machine:

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

Under Windows + WSL2 mirrored networking, if WSL internal and Windows localhost are accessible but the Windows/LAN IP times out, check the WSL mirrored/Hyper-V network policy, Docker Desktop port publishing, and LAN inbound rules. The project service listening and Compose publishing should remain:

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

Do not expose the HTTP admin page directly to untrusted networks in production; use a VPN, internal firewall, or HTTPS reverse proxy, and regularly revoke/rotate MCP Keys.

Current Limitations

• code-mcp is currently a code repository capability skeleton; the full Git metadata database and AST index are still to be completed;

• mem-mcp is currently a memory layer skeleton; mem0 auto-extraction/hooks are still to be completed;

• The reranker model is large and may remain unavailable on unstable networks; core retrieval will fall back to RRF;

• Admin is currently suitable for intranet testing; production requires HTTPS/VPN/firewall;

• Document classification (project, document type, tags) is a direction for the next phase.

Table of Contents

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

License

This repository does not yet declare a formal open-source license. If you plan to distribute it publicly, please add a LICENSE file before release and clarify the usage rights for third-party models, dependencies, and documentation.