Saltar a contenido

Flujo diario STDIO para agentes de IA

Esta guía describe cómo conectar el servidor :docugraph-mcp a un workspace local o al despliegue remoto de Oracle y usarlo desde Claude Code, Codex, Antigravity CLI u OpenCode. STDIO es el transporte local; el perfil remoto usa Streamable HTTP /mcp y compatibilidad /sse, detrás de Caddy con X-MCP-API-KEY. La especificación de arranque y el alcance de Gate 0 están en MCP-G0, y el catálogo protocolario en MCP-SPEC.

Paradigma vigente (DEC-013, 2026-08-14): la fuente de verdad es Markdown + git. Los documentos los escriben los agentes vía MCP (STDIO local o HTTP remoto desde Oracle) y el driver los lee y navega con Obsidian (vault sobre el clon), Gitea (revisión web puntual) o el visor web. El flujo local STDIO de esta guía sigue siendo válido y el flujo remoto se describe en §3.

0. Escritura por agentes y lectura con Obsidian

  • Escribir: los agentes (Claude Code, Codex, Antigravity) crean/actualizan los .md mediante upsert_document y update_frontmatter; el servidor valida el DAG antes de escribir.
  • Leer/navegar: abre el clon local del repo en Obsidian como vault: soporta markdown nativo, vista de grafo y diagramas Mermaid, sin necesidad de la app Desktop.
  • Consultar desde navegador/móvil: el visor web en Oracle (Nivel 4.3) renderiza los .md y el grafo.

1. Preparar el launcher

Desde la raíz del monorepo, generar la distribución instalable:

.\gradlew.bat :docugraph-mcp:installDist

El launcher de Windows queda en:

<repo>\docugraph-mcp\build\install\docugraph-mcp\bin\docugraph-mcp.bat

El servidor necesita un workspace que contenga los documentos Markdown del proyecto. Puede recibirlo por variable de entorno:

$env:DOCUGRAPH_WORKSPACE = "C:\ruta\a\mi-workspace"
& "C:\ruta\a\docugraph\docugraph-mcp\build\install\docugraph-mcp\bin\docugraph-mcp.bat"

O como argumento explícito:

& "C:\ruta\a\docugraph\docugraph-mcp\build\install\docugraph-mcp\bin\docugraph-mcp.bat" --workspace "C:\ruta\a\mi-workspace"

En Unix, el equivalente es ./docugraph-mcp/build/install/docugraph-mcp/bin/docugraph-mcp --workspace /ruta/a/mi-workspace. Si no se proporciona ninguna de las dos opciones, el proceso termina con código 1.

2. Registrar el servidor en cada cliente

Sustituir las rutas de ejemplo por rutas absolutas. El cliente debe ejecutar el launcher como proceso hijo; no hay que iniciar un proceso STDIO separado en otra terminal.

Claude Code

Registrar el servidor con el comando oficial claude mcp add:

claude mcp add --transport stdio --env DOCUGRAPH_WORKSPACE=C:\ruta\a\mi-workspace docugraph -- "C:\ruta\a\docugraph\docugraph-mcp\build\install\docugraph-mcp\bin\docugraph-mcp.bat"

También puede fijarse el workspace en el comando del launcher:

claude mcp add --transport stdio docugraph -- "C:\ruta\a\docugraph\docugraph-mcp\build\install\docugraph-mcp\bin\docugraph-mcp.bat" --workspace "C:\ruta\a\mi-workspace"

Comprobar el registro con claude mcp list y abrir una nueva sesión en el workspace objetivo.

Codex

La forma recomendada es la CLI oficial:

codex mcp add docugraph --env DOCUGRAPH_WORKSPACE=C:\ruta\a\mi-workspace -- "C:\ruta\a\docugraph\docugraph-mcp\build\install\docugraph-mcp\bin\docugraph-mcp.bat"

Como alternativa, añadir la entrada a ~/.codex/config.toml (o al config.toml de .codex/ de un proyecto confiable):

[mcp_servers.docugraph]
command = "C:\\ruta\\a\\docugraph\\docugraph-mcp\\build\\install\\docugraph-mcp\\bin\\docugraph-mcp.bat"
args = []

[mcp_servers.docugraph.env]
DOCUGRAPH_WORKSPACE = "C:\\ruta\\a\\mi-workspace"

Validar la entrada con codex mcp list o consultar el estado MCP con /mcp dentro de Codex.

Antigravity CLI

Antigravity CLI admite configuración global en ~/.gemini/antigravity-cli/mcp_config.json y configuración por workspace en .agents/mcp_config.json. Para el flujo del driver, crear o editar la configuración global:

{
  "mcpServers": {
    "docugraph": {
      "command": "C:\\ruta\\a\\docugraph\\docugraph-mcp\\build\\install\\docugraph-mcp\\bin\\docugraph-mcp.bat",
      "args": [],
      "env": {
        "DOCUGRAPH_WORKSPACE": "C:\\ruta\\a\\mi-workspace"
      }
    }
  }
}

Para limitarlo a un repositorio, colocar el mismo objeto en <workspace>/.agents/mcp_config.json. Abrir el administrador oficial escribiendo /mcp en el panel de prompt, comprobar que docugraph está conectado y recargar la configuración si se modificó mientras el cliente estaba abierto.

3. Conectar al MCP remoto de Oracle

El Compose de deploy/oracle/ mantiene Gitea, el checkout /workspace, Caddy y el visor en servicios separados. El endpoint público es el host MCP_DOMAIN terminado en /mcp; no uses el puerto 8080 ni guardes MCP_API_KEY en Git.

OpenCode

El opencode.json del repositorio ya conserva el transporte remoto y obtiene la clave desde el entorno mediante {env:DOCUGRAPH_MCP_API_KEY}. Define la variable en la sesión local antes de iniciar OpenCode:

$env:DOCUGRAPH_MCP_API_KEY = "<clave-local-no-versionada>"
opencode mcp list

En una configuración global usa la misma entrada bajo mcp.docugraph. oauth está desactivado porque Caddy usa una clave estática de header, no un flujo OAuth.

Antigravity CLI

.agents/mcp_config.json conserva serverUrl y el header X-MCP-API-KEY con un placeholder de entorno. Si la versión instalada no expande ${DOCUGRAPH_MCP_API_KEY} automáticamente, copia la entrada en la configuración global/local ignorada de Antigravity y sustituye el placeholder allí, sin editar el archivo versionado. Comprueba la conexión con /mcp y recarga la configuración después de rotar la clave.

Ciclo remoto seguro

  1. En Oracle, ejecutar bash deploy/oracle/scripts/sync-workspace.sh con el árbol limpio.
  2. Pedir al agente la escritura mediante upsert_document o update_frontmatter.
  3. Ejecutar bash deploy/oracle/scripts/validate-traceability.sh y revisar el reporte.
  4. Revisar el diff y publicar con publish-workspace.sh --message "docs(scope): summary" --confirm.
  5. En Windows, ejecutar scripts/sync-docugraph.ps1 y abrir el checkout como vault Obsidian.

Una respuesta 401 sin llegar a Ktor indica credencial ausente o incorrecta; una modificación con ciclo, enlace roto, conflicto o workspace sucio debe detener el cierre y no debe sobrescribir documentos.

4. Uso diario de las ocho tools

  1. Obtener contexto: antes de implementar, pedir get_task_context("BE-XX") (o el ID atómico correspondiente). El agente recibe el bundle upstream necesario en lugar de cargar todo el repositorio.
  2. Crear o actualizar documentación: usar upsert_document para un Markdown nuevo o completo y update_frontmatter para cambios puntuales. Mantener los IDs y enlaces del frontmatter; ambas operaciones validan la integridad del DAG antes de escribir.
  3. Consultar dependencias: usar get_dependency_graph cuando sea necesario revisar el impacto upstream/downstream de una tarea o cambio.
  4. Listar tareas: usar list_tasks para consultar tareas por tipo o estado, junto con su ID y ruta documental.
  5. Verificar aceptación: usar get_acceptance_criteria para recuperar los criterios estructurados de la tarea y comprobar su cumplimiento.
  6. Analizar impacto: usar analyze_impact para revisar dependientes downstream y caminos críticos antes de un cambio.
  7. Cerrar con auditoría: ejecutar validate_traceability sobre el workspace y corregir cualquier error antes de dar la tarea por terminada.

La descripción normativa de parámetros, resultados y comportamiento pertenece a MCP-G0 y MCP-SPEC; esta guía solo describe el flujo operativo.

5. Ejemplo completo de ciclo diario

Supóngase un workspace en C:\proyectos\inventario y una tarea de backend BE-21:

  1. Registrar el servidor una vez, pasando DOCUGRAPH_WORKSPACE=C:\proyectos\inventario al cliente.
  2. Crear la historia docs/user_stories/US-21_importar_stock.md con upsert_document, incluyendo un ID único y sus enlaces depends_on.
  3. Pedir get_task_context("BE-21") para que el agente recupere US-21 y las demás dependencias trazables.
  4. Implementar BE-21 respetando el bundle y las reglas de AGENTS.md, sin copiar contratos que ya tienen una fuente única.
  5. Si cambia la metadata de un documento, aplicar update_frontmatter en vez de reescribir campos no relacionados.
  6. Ejecutar validate_traceability sobre C:\proyectos\inventario. Si el reporte no tiene errores, cerrar la tarea; si los tiene, corregir el documento o enlace indicado y repetir la validación.

Así, el ciclo queda: crear US → obtener contexto → implementar → validar → cerrar.

6. Resolución de problemas

  • El proceso termina con código 1: comprobar que DOCUGRAPH_WORKSPACE o --workspace apunta a un directorio existente.
  • No aparecen tools: comprobar la ruta absoluta del launcher, que installDist se ejecutó y reiniciar o recargar el cliente.
  • La auditoría falla: leer errors del resultado de validate_traceability; no cerrar la tarea hasta que los errores introducidos por el cambio estén resueltos.

Trazabilidad

  • ROADMAP-00 — Nivel 1.2, flujo diario del driver.
  • MCP-G0 — transporte STDIO y arranque del servidor.
  • MCP-SPEC — especificación general del servidor MCP.
  • AGENTS — protocolo de trabajo de agentes y matriz de tools.