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_* 도구를 함께 집계합니다.

• LAN 배포: 서비스가 한 대의 Docker 호스트에서 실행되며, 다른 Agent는 LAN을 통해 Gateway에 접근합니다.

Related MCP server: MCP 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: Enter를 누르면 랜덤 생성됩니다. 기존 값은 덮어쓰지 않습니다. 업그레이드 시 반드시 동일하게 유지해야 합니다.

• Admin 초기 사용자 이름: Enter를 누르면 기본값 admin;

• Admin 초기 비밀번호: Enter를 누르면 랜덤 생성됩니다. 빈 데이터베이스의 최초 시작에만 사용됩니다.

• 모델 다운로드 네트워크 안내: 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

주요 구성:

다음 항목은 커밋하지 마세요:

.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

이 명령은 데이터 볼륨을 삭제합니다.

LAN 접근

Docker 호스트의 LAN 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/LAN IP가 타임아웃되면, WSL mirrored/Hyper-V 네트워크 정책, Docker Desktop 포트 게시, LAN 인바운드 규칙을 확인해야 합니다. 프로젝트 서비스 리슨 및 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 파일을 추가하고 타사 모델, 의존성, 문서의 사용 권한을 명확히 하세요.