Saltar a contenido

MCP-G0: Servidor MCP — subconjunto Gate 0

Este documento es la especificación implementable del servidor para Gate 0. El catálogo amplio permanece en MCP-SPEC (phase: GATE_0 anotado, pero incluye SSE, resources, entitlements y backend que no son criterios §5.1).

Regla: en conflicto entre MCP-SPEC (catálogo) y MCP-G0 (Gate 0), prevalece MCP-G0 hasta aprobar el gate; luego se puede ampliar hacia el catálogo por decisión explícita.

1. Objetivo runtime

Ítem Gate 0
Módulo :docugraph-mcp
SDK io.modelcontextprotocol:kotlin-sdk:0.1.0 (DEC-003)
Main io.docugraph.mcp.MainKt (ya declarado en Gradle)
Transporte STDIO only
Dependencia lógica :docugraph-core (META-01)
Auth / API keys / PostgreSQL No
Entitlement maxDepth freemium No (usar maxDepth del request tal cual)

2. Arranque y workspace

# Conceptual
docugraph-mcp --workspace <path>
# o variable de entorno DOCUGRAPH_WORKSPACE
  • Si falta workspace → error de arranque no cero / log fatal.
  • Carga inicial: Document Loader + parse de todos los .md elegibles (META-01).
  • Re-carga en caliente: no requerida en Gate 0 (reinicio del proceso basta).

3. Tools obligatorios

3.1 get_task_context
Nombre get_task_context
Descripción Recorrido upstream por depends_on desde taskId; devuelve context bundle en Markdown con justificación de inclusiones.
Parámetros taskId (string, required); maxDepth (integer, optional, default 5)
Retorno Texto Markdown (MCP text content)

Comportamiento

  1. Si taskId no existe → error de tool estructurado (TASK_NOT_FOUND).
  2. Resolver bundle según META-01 §7 (determinista).
  3. Si el grafo tiene ciclos que impiden orden topológico global, el tool puede fallar con GRAPH_CYCLE o devolver bundle parcial solo del reachable acíclico; Gate 0 preferido: fallar y pedir validate_traceability (fail-closed).
  4. Markdown de salida debe incluir sección de justificación por nodo (criterio MASTER-00 §5.1.4).

Plantilla de salida (normativa mínima)

# Context bundle: {taskId}
maxDepth: {n}
truncated: {true|false}

## Inclusion report
- `{id}` depth={d}: {reason}

## Documents

### {id} — {title}
path: {path}

{full markdown file content}

...

3.2 validate_traceability
Nombre validate_traceability
Descripción Auditoría de frontmatter, enlaces y ciclos (Tarjan).
Parámetros workspacePath (string, optional) — si se omite, usa workspace del proceso
Retorno JSON (text content)

Schema JSON mínimo

{
  "workspacePath": "...",
  "nodeCount": 0,
  "edgeCount": 0,
  "errors": [
    { "code": "LINK_CYCLE", "message": "...", "nodeId": "...", "path": "..." }
  ],
  "warnings": [],
  "valid": true
}

valid === true iff errors vacío.

Códigos: META-01 §6.

4. Tools / capacidades no Gate 0

No implementar como requisito de aprobación:

  • get_dependency_graph
  • list_tasks (registrado en el servidor, pero no es criterio obligatorio del gate)
  • get_acceptance_criteria (registrado en el servidor, pero no es criterio obligatorio del gate)
  • analyze_impact (registrada en el servidor, pero no es criterio obligatorio del gate)
  • Resources docugraph://…
  • Prompts prompt_implement_task / prompt_audit_traceability (útiles después; opcionales)
  • SSE / HTTP
  • Capado freemium maxDepth=2
  • Delegación a :docugraph-backend

5. Cliente MCP real

Criterio §5.1.1: al menos un cliente real (Junie, Claude Code, Cursor, u otro compatible MCP STDIO) configurado para spawnear el proceso Gradle/JAR y listar/invocar tools.

Estado (2026-08-11): verificado con JetBrains Junie (cliente MCP externo real) vía STDIO spawneando docugraph-mcp.bat (launcher installDist, DOCUGRAPH_WORKSPACE=research/evidence/demo-repo) -> 4/4 PASS (initialize, tools/list, bundle BE-02, validate_traceability, fail-closed). Evidencia y detalle en EXP-01 (research/experiments/EXP-01_recuperacion_contexto.md) y DEC-005 (research/99_DECISION_LOG.md).

Evidencia esperada en EXP-01: log de sesión o captura de invocación exitosa.

6. Tarea demo BE-02

  • Parámetro de evaluación: get_task_context(taskId="BE-02") sobre repo demo, no sobre docs/backend/BE-02_project-create.md.
  • Conjunto esperado = gold standard (GATE-0 §5.2), no el grafo del monorepo de producto.

7. Reproducibilidad

  1. Mismo commit de fixtures demo + mismo binario → mismo bundle (byte-estable tras normalizar EOL si se documenta).
  2. Documentar en README de evidence el comando exacto de ejecución.
  3. No depender de relojes ni de orden de filesystem no normalizado (ordenar paths/IDs).

8. Definición de done (servidor)

  • [ ] STDIO acepta handshake MCP del SDK.
  • [ ] Tools registrados y descubribles.
  • [ ] get_task_context cumple plantilla y determinismo.
  • [ ] validate_traceability detecta link roto y ciclo en fixtures negativos.
  • [ ] Sin dependencia de red ni DB.

9. Relación con MCP-SPEC

Tema MCP-SPEC (catálogo) MCP-G0
Tools 6 + prompts 2 mandatory tools (6 registered in the Gate 0 server)
Transport STDIO + SSE STDIO
Backend BE-03/04/05 in-process core
Auth API key + Pro none

10. Trazabilidad

  • GATE-0 (research/GATE_0_SPEC.md), META-01, EXP-01 (research/experiments/EXP-01_recuperacion_contexto.md), AGENTS.md tool matrix (subset).