POC PI Connectivity v2 — Codex local plugin

Conversión mínima del .mcpb: solo conectividad.

Codex local/Desktop
      ↓ MCP stdio
server/main.py
      ↓ HTTP POST
<SURREAL_URL>/sql
      ↓
SurrealDB

Qué incluye

• Una sola tool MCP: query_surrealdb(query).
• Python estándar únicamente; no requiere pip install.
• Timeout HTTP de 5 segundos por defecto.
• Timeout de tool de Codex de 8 segundos.
• Logging de diagnóstico local con timestamps y duraciones.
• Rotación simple del log al llegar a ~1 MB.

Qué NO incluye

• HTML.
• Prompts.
• Skills.
• Resources.
• Hooks.
• defaultPrompt.
• Health checks automáticos.
• Reintentos de red automáticos.

El proceso no toca la red durante el arranque, initialize ni tools/list. Sólo hay HTTP cuando Codex llama explícitamente a query_surrealdb.

Requisito

Python 3.10+ accesible como python en PATH.

Instalación conversacional en Codex Desktop

Adjuntá este ZIP a Codex Desktop y pedile, por ejemplo:

Descomprimí este ZIP, registrá el marketplace local y instalá el plugin poc-pi-connectivity en mi Codex local. Pedime aprobación antes de modificar mi instalación real.

El marketplace incluido se llama poc-pi-local.

También se puede registrar manualmente desde la carpeta descomprimida:

codex plugin marketplace add /RUTA/A/poc-pi-codex-marketplace-v2

Después instalá poc-pi-connectivity desde el Plugin Directory local.

Prueba explícita

En un chat nuevo:

Usá query_surrealdb exactamente una vez con: RETURN 1;

No hay ninguna prueba automática configurada en el plugin.

Diagnóstico

El puente escribe un log estructurado en:

Windows

%USERPROFILE%\.pocpi\pocpi.log

macOS / Linux

~/.pocpi/pocpi.log

Ejemplo:

{"ts":"2026-08-25T21:00:00.000Z","event":"server.start",...}
{"ts":"2026-08-25T21:00:00.020Z","event":"mcp.request","method":"initialize",...}
{"ts":"2026-08-25T21:00:00.030Z","event":"mcp.request","method":"tools/list",...}
{"ts":"2026-08-25T21:00:05.000Z","event":"tool.start","tool":"query_surrealdb",...}
{"ts":"2026-08-25T21:00:05.001Z","event":"http.start",...}
{"ts":"2026-08-25T21:00:05.180Z","event":"http.ok","elapsed_ms":179.0,...}
{"ts":"2026-08-25T21:00:05.181Z","event":"tool.end","elapsed_ms":181.0,...}

El SQL no se guarda en el log. Sólo se registra su tamaño y un fingerprint SHA-256 corto para poder correlacionar llamadas.

Configuración

Editar antes de instalar:

plugins/poc-pi-connectivity/.mcp.json

Variables actuales:

• SURREAL_URL=https://leif-uncountermandable-serenity.ngrok-free.dev
• SURREAL_NS=poc
• SURREAL_DB=PI
• SURREAL_USER=
• SURREAL_PASS=
• SURREAL_TIMEOUT_SECONDS=5

Opcionalmente, POCPI_LOG_PATH puede definirse en env para elegir otra ubicación del log.

Si Codex queda lento

1. Abrí el log y mirá el último evento.
2. Si no aparece tool.start, la demora es anterior a nuestro HTTP.
3. Si aparece http.start pero no http.ok/http.error durante ~5 s, la demora es la conexión al endpoint.
4. Si http.ok es rápido pero Codex sigue tardando, el cuello está después de la respuesta del plugin.
5. Deshabilitar/desinstalar el plugin y reiniciar Codex permite aislar el problema.