wp_criu

MCP Hub propio para Codex y ChatGPT

Este servicio consolida dos cosas en una sola capa:

• MCP remoto por Streamable HTTP para Codex y ChatGPT.
• Panel técnico y registry compatible para onboarding de conectores y sitios WordPress.

Qué incluye ahora

• Hub MCP con herramientas de Notion y WordPress.
• State store persistido en JSON para onboarding editable.
• Panel técnico en /admin.
• Admin API en /api/admin/*.
• Registry WordPress compatible:
• GET /sites
• GET /sites/:site_id
• POST /register-site
• PATCH /sites/:site_id
• DELETE /sites/:site_id

Arquitectura

• src/index.ts: entrypoint HTTP, /mcp, /health, /admin y rutas de registry.
• src/mcp-server.ts: herramientas MCP de Notion y WordPress.
• src/lib/state.ts: estado persistido del hub.
• src/notion.ts: adaptador Notion por alias.
• src/wordpress.ts: adaptador WordPress compatible con el bridge actual.
• src/admin/*: UI y API técnica de onboarding.

Variables de entorno

Obligatorias en producción:

• ADMIN_API_KEY
• ADMIN_SESSION_SECRET
• WORDPRESS_REGISTRY_TOKEN

Recomendadas:

• MCP_AUTH_MODE=bearer
• MCP_API_KEY
• MCP_ALLOWED_HOSTS=mcp.tudominio.com,localhost,127.0.0.1
• HUB_STATE_FILE=/app/data/hub-state.json

Bootstrap opcional:

• NOTION_CONNECTIONS_JSON
• WORDPRESS_BOOTSTRAP_SITES_FILE
• NOTION_OAUTH_CLIENT_ID
• NOTION_OAUTH_CLIENT_SECRET
• NOTION_OAUTH_REDIRECT_URI

Rutas principales

• GET /
• GET /health
• GET /admin
• POST /mcp
• GET /sites
• POST /register-site

Panel técnico

El panel permite:

• iniciar autorizaciones de Notion por OAuth;
• almacenar y editar conexiones Notion ya autorizadas;
• validarlas con whoami;
• registrar sitios WordPress a mano;
• ver estado de bridge;
• ocultar o desactivar sitios sin borrarlos lógicamente del modelo;
• eliminar sitios del registry;
• ver el catálogo técnico para futuros conectores.

Compatibilidad WordPress

La idea es no romper el stack actual:

• el plugin WordPress puede seguir enviando auto-registro a POST /register-site;
• el modelo por site_id, site_label y base_url se mantiene;
• las herramientas MCP WordPress conservan los mismos nombres usados antes.

Uso local

npm install
copy .env.example .env
npm run dev

Pruebas rápidas:

curl http://localhost:3000/health
npm run smoke:http

Abre:

http://localhost:3000/admin

Despliegue en EasyPanel

1. Crea el servicio desde este directorio.
2. Persiste ./data o define un volumen para HUB_STATE_FILE.
3. Configura MCP_AUTH_MODE=bearer y un MCP_API_KEY privado.
4. Configura MCP_ALLOWED_HOSTS con tu dominio publico y localhost.
5. Configura ADMIN_API_KEY, ADMIN_SESSION_SECRET y WORDPRESS_REGISTRY_TOKEN.
6. Si vas a conectar Notion desde el panel, configura NOTION_OAUTH_CLIENT_ID, NOTION_OAUTH_CLIENT_SECRET y NOTION_OAUTH_REDIRECT_URI=https://tu-dominio/api/admin/connectors/notion/oauth/callback.
7. Si vienes del wp_criu_registry actual, monta el mismo volumen y deja WORDPRESS_BOOTSTRAP_SITES_FILE=/app/data/sites.json.
8. Publica el servicio por HTTPS.
9. Usa /mcp para MCP y /admin para onboarding humano.

Onboarding de Notion

1. Crea una integración pública de Notion y define como redirect URI:

• https://tu-dominio/api/admin/connectors/notion/oauth/callback

1. Carga NOTION_OAUTH_CLIENT_ID, NOTION_OAUTH_CLIENT_SECRET y NOTION_OAUTH_REDIRECT_URI en EasyPanel.
2. Entra a /admin.
3. Escribe alias, label opcional y defaultParentPageId opcional.
4. Pulsa Conectar con Notion.
5. Autoriza la integración en Notion.
6. Vuelve al panel y valida con whoami.

Migración directa desde el registry actual

Si mcp.criu.com.co hoy responde como wp_criu_registry, la migración segura para reemplazarlo con este hub es:

1. Respaldar el volumen actual de /app/data.
2. Mantener el archivo legado sites.json en ese mismo volumen.
3. Desplegar este servicio con:

• HUB_STATE_FILE=/app/data/hub-state.json
• WORDPRESS_BOOTSTRAP_SITES_FILE=/app/data/sites.json

1. Arrancar el hub nuevo.
2. Confirmar en /admin que los sitios heredados aparecieron.

El hub también intenta detectar automáticamente un sites.json vecino al hub-state.json, de modo que un reemplazo directo no dependa de pasos manuales extra.

Codex

Ejemplo con bearer:

[mcp_servers.criu_hub]
url = "https://mcp.tudominio.com/mcp"
bearer_token_env_var = "CRIU_MCP_HUB_TOKEN"

El valor de CRIU_MCP_HUB_TOKEN debe ser el mismo MCP_API_KEY del hub.

ChatGPT

Diseño recomendado:

• camino principal: Secure MCP Tunnel
• fallback: endpoint HTTPS directo a /mcp

Guía operativa

Hay una guía más aterrizada de uso personal, despliegue y onboarding en docs/OPERACION_PERSONAL.md.

Si este repo ya está desplegado en producción, el estado operativo real y los endpoints live actuales quedaron documentados en docs/ESTADO_LIVE_MCP_CRIU.md.

Scripts útiles

Importar sitios desde el registry vivo actual a data/sites.json:

LEGACY_REGISTRY_TOKEN=tu_token npm run import:legacy-registry

O explícitamente:

node scripts/import-legacy-registry.mjs --url https://mcp.criu.com.co --token tu_token --output ./data/sites.json

Hacer smoke test HTTP/MCP del hub ya levantado:

MCP_HUB_URL=https://mcp.criu.com.co MCP_HUB_TOKEN=tu_token npm run smoke:http

Futuros conectores

Cada integración nueva debería entrar como:

1. manifest del conector
2. config schema
3. health check
4. admin form
5. entidades administrables
6. adaptador MCP