ai-engineering-brain

Plataforma de conocimiento de ingeniería empresarial para Claude Code y otros agentes MCP: conecta documentación interna, repositorios de código y memoria a largo plazo en una pasarela MCP unificada, y gestiona documentos, cuentas y claves MCP a través de la página de administración.

La cadena de conocimiento kb-mcp es la más madura y la que ha superado la validación integral de extremo a extremo con Docker. code-mcp y mem-mcp ya están conectados a la interfaz de agregación MCP unificada, pero siguen en fase de esqueleto/mejora continua.

El estado completo de implementación del proyecto, las causas de los fallos y las soluciones se encuentran en: docs/kb-mcp-project-status.md.

Qué puede hacer

• Base de conocimiento: importa Markdown, TXT y DOCX; conserva la jerarquía de títulos, tablas, bloques de código y citas; fragmentación padre-hijo; recuperación híbrida densa+dispersa de Qdrant, RRF y reranker opcional.

• Administración: página de administración EASTCOM, carga/reintento/eliminación de documentos, limpieza de registros de archivos faltantes, inicio de sesión de cuentas y RBAC.

• Claves MCP vinculadas a cuentas: los usuarios crean, ven, copian, muestran/ocultan y revocan sus propias claves MCP tras iniciar sesión; las claves completas se guardan cifradas y no se registran en los registros.

• MCP unificado: los clientes solo se conectan a la dirección /mcp de la pasarela; la pasarela agrega las herramientas kb_*, code_* y mem_*.

• Despliegue en red local: el servicio se ejecuta en un host Docker y otros agentes acceden a la pasarela a través de la red de área local.

Related MCP server: MCP Gateway

Arquitectura

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

Los clientes externos solo necesitan conocer:

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

Los puertos internos 8100/8101/8102 no necesitan configurarse para otros agentes.

Nomenclatura de herramientas

Las herramientas del MCP unificado utilizan el prefijo del servicio:

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

Actualmente, algunas herramientas de code-mcp y mem-mcp siguen siendo implementaciones esqueleto; se pueden completar más adelante sin cambiar la dirección del cliente.

Instalación rápida

Requisitos previos

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

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

• Windows: PowerShell, Docker Desktop;

• Si se necesita descargar modelos, el host/contenedor debe poder acceder a Hugging Face; si no hay conexión directa, prepara un proxy HTTP.

Linux / macOS

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

El script de instalación preguntará de forma interactiva:

• MCP_KEY_ENCRYPTION_KEY: si se pulsa Enter, se genera aleatoriamente; los valores existentes no se sobrescriben; debe permanecer igual al actualizar;

• Nombre de usuario inicial de administrador: si se pulsa Enter, el valor predeterminado es admin;

• Contraseña inicial de administrador: si se pulsa Enter, se genera aleatoriamente; solo se usa en el primer arranque con base de datos vacía;

• Aviso de red para la descarga de modelos: si Hugging Face no es accesible, rellena KB_HTTP_PROXY / KB_HTTPS_PROXY en .env; el reranker es grande, puedes establecer RERANKER_ENABLED=0 para usar el respaldo RRF.

Windows PowerShell

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

Si la directiva de ejecución de PowerShell bloquea el script, puedes ejecutar en la ventana actual:

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

Después de la instalación

El script de instalación mostrará las direcciones de administración y MCP. Inicia sesión en el panel de administración:

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

Entra en la página Claves MCP para crear una clave vinculada a la cuenta y, a continuación, ejecuta en la otra máquina del agente:

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

O usa el script de cliente:

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

Comprueba Claude Code:

claude mcp list

Configuración

.env no se confirma en Git. La primera instalación escribe algunos valores aleatorios; consulta la plantilla:

cp .env.example .env

Configuración clave:

No confirmes lo siguiente:

.env
ADMIN_KEY
API_KEYS
MCP_KEY_ENCRYPTION_KEY
ADMIN_BOOTSTRAP_PASSWORD
MCP Key 明文

Comandos habituales

Ver servicios:

docker compose ps

Ver registros de instalación/modelo:

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

Comprobación de estado:

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

Comprobar la cuenta de la base de datos y la tabla de claves MCP:

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'

Verificar configuración y sintaxis:

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

Datos y actualizaciones

Los datos se almacenan en volúmenes Docker:

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

Antes de actualizar, se recomienda hacer una copia de seguridad de Postgres y de los documentos importantes. Actualización normal:

git pull
docker compose build
docker compose up -d

No ejecutes:

docker compose down -v

Ese comando eliminará los volúmenes de datos.

Acceso a la red de área local

Si la IP de red local del host Docker es 192.168.1.10:

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

Primero prueba desde otra máquina:

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

En Windows + WSL2 con redes en modo espejo, si se puede acceder desde localhost de WSL y Windows, pero se agota el tiempo de espera con la IP de Windows/LAN, debes comprobar la política de red en modo espejo/Hyper-V de WSL, la publicación de puertos de Docker Desktop y las reglas de entrada de la red de área local. La escucha del servicio del proyecto y la publicación de Compose deben mantenerse:

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

En producción, no expongas directamente la página de administración HTTP a redes no confiables; se recomienda usar VPN, cortafuegos de red interna o proxy inverso HTTPS, y rotar/revocar las claves MCP periódicamente.

Limitaciones actuales

• code-mcp es actualmente un esqueleto de capacidades de repositorio de código; la base de datos completa de metadatos Git y el índice AST están pendientes;

• mem-mcp es actualmente un esqueleto de capa de memoria; la extracción automática/hooks de mem0 están pendientes;

• El modelo reranker es grande; si la red es inestable, puede permanecer no disponible; la recuperación principal volverá a RRF;

• El panel de administración es adecuado para pruebas en red interna; en producción se necesita HTTPS/VPN/cortafuegos;

• El sistema de clasificación de documentos (proyecto, tipo de documento, etiquetas) es una dirección de mejora para la próxima fase.

Directorio

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

Licencia

El repositorio actual no declara una licencia de código abierto formal. Si se va a distribuir públicamente, añade el archivo LICENSE y aclara los permisos de uso de los modelos, dependencias y documentación de terceros antes de la publicación.