devMCP — planner proMCP multi-fuente con federación concurrente

Extensión de dominio de proMCP v0.3.0 para el ciclo de vida de desarrollo: un servidor proMCP que planifica rutas de ejecución sobre codepreproc+SuperKG, JIRA, Confluence y GitHub mediante can_do compuesto, y las ejecuta en serie y en paralelo de forma determinista, auditable y compensable, bajo contratos estrictos entre MCPs.

Esta entrega es diseño con contratos ejecutables, y el planner ya corre. Los modelos validan, el manifest valida contra ellos, tools/verify_design.py falla si el diseño es incoherente, y devmcp/planner/ produce un ExecutionPlan real desde el manifest real (python3 tools/plan_demo.py) que devmcp/executor/ recorre contra fuentes simuladas (python3 tools/exec_demo.py), todo detrás de siete tools proMCP (python3 tools/server_demo.py). Falta conectar las fuentes reales.

Estado: v0.2.0. Empieza por ADR-003 si te interesa la capa de federación, o por ADR-002 si vienes de cero.

Cómo está organizado

Todo devMCP es un solo paquete, y todo lo que necesita en ejecución está dentro de él. No es orden por gusto: mientras el catálogo vivía en examples/, la política en la raíz y el panel en frontend/dist/, instalarlo producía un servidor que arrancaba y decía tener cero capacidades — el fallo no se veía al importar, se veía tres capas más abajo.

devmcp/
  contracts/     los modelos Pydantic. Fuente de verdad de todo lo demás.
  planner/       el hiperDijkstra: de una intención a un ExecutionPlan.
  executor/      recorre el plan: pool, semáforos, ledger, gates, compensación.
  server/        los siete tools que ve el modelo.
  adapters/      jira, confluence, github, kg, cli, rest, quality.
  analysis/      las capacidades internas, y la sonda de formalización.
  bootstrap/     la tríada que establece devMCP en otra carpeta.
  datos/         lo que no es código y hace falta para funcionar:
                   manifests/  los catálogos
                   schemas/    los JSON Schema generados desde contracts/
                   skills/     los 14 procedimientos
                   panel/      el panel construido (lo emite panel/, no se versiona)
                   devmcp.policy.yml
  panel/         las fuentes del panel (vite + react). No van en la rueda.
  recursos.py    el único módulo que sabe dónde está cada cosa.

docs/            el diseño, los ADR y las specs.
tools/           la suite de controles y los generadores. No van en la rueda.

La regla que ordena esto es qué necesita cada consumidor: devmcp/ es lo que se instala, tools/ y docs/ son del que desarrolla devMCP. La sonda de formalización se movió a devmcp/analysis/ justo por eso — es una capacidad del servidor, no una herramienta del repo, y mientras vivió en tools/ había que copiarla al paquete para que read_formalization_probe la encontrase.

Qué hay aquí

Las seis ideas que sostienen el diseño

1. El modelo declara intención; el planner calcula la ruta. can_do recibe una intención estructurada y devuelve un ExecutionPlan: un DAG de llamadas con argumentos resueltos, claves de idempotencia pre-asignadas y gates. Elegir ruta es un Dijkstra sobre un grafo de artefactos tipados, no una inferencia sobre descripciones.

2. El paralelismo lógico y el físico son cosas distintas. El DAG dice qué podría ir junto; el ConcurrencyProfile de cada fuente dice qué va junto. Confundirlos no da un problema de rendimiento: da respuestas correctas del proyecto equivocado, porque codepreproc guarda estado por conexión. La diferencia entre ambos se escribe en el plan (critical_path_ms vs admission_limited_ms) antes de ejecutar.

3. El paralelismo también compra evidencia, no solo tiempo. artifact:ticket.key tiene cuatro rutas independientes. En vez de elegir una, un stage quorum(2) las corre a la vez y compone confianza por acuerdo: rama (0.93) + título (0.72) dan 0.98 por 300 ms extra. Y si discrepan, eso es un hallazgo con gate, no ruido que se descarta.

4. Las políticas explícitas de Kanban son precondiciones verificables. Una transición de columna es un do_* cuya evidencia mínima es la Definition of Ready o of Done de esa columna, leída de Confluence y evaluada contra Jira y GitHub. Mover a una columna llena deja de ser posible (dev_wip_limit_exceeded), y lo que la política no permite comprobar se declara como hueco en vez de darse por cumplido. Ver SDLC-KANBAN.md.

5. El FSM lo deciden predicados, no personas. Un gate existía por cuatro motivos y solo uno es irreducible: la irreversibilidad con radio real. Los otros tres —falta de evidencia, confianza baja, y esperar— se convierten en mecanismos deterministas. AWAITING_EVIDENCE separa "falta un dato que llegará solo" de "hace falta una decisión", y el auto-merge se gana formalizando la DoD, no se concede. Ver AUTONOMY-LADDER.md.

6. Contratos estrictos o no hay contrato. Pydantic como fuente de verdad, extra="forbid" en ambas direcciones, ningún campo de control como texto libre, todo artifact:* con esquema, y un handshake que rechaza una fuente cuya versión no coincide en vez de suponerla.

Empezar en una carpeta nueva

Se instala una vez y se establece en cada repo donde se vaya a trabajar. Son dos gestos distintos a propósito: instalar pone devMCP en el venv, establecer escribe en el proyecto lo que hace falta para que arranque ahí.

pip install phylos-mcp                  # o: pipx install phylos-mcp
devmcp-bootstrap survey    E:/proyectos/nuevo      # qué hay y qué se escribiría
devmcp-bootstrap establish E:/proyectos/nuevo --dry-run
devmcp-bootstrap establish E:/proyectos/nuevo --kg-project nuevo

El paquete se llama phylos-mcp en PyPI y devmcp al importarlo, y no es un descuido: PyPI rechaza devmcp por parecido con dev-mcp, que ya existe. Lo que se instala cambia de nombre; import devmcp, python -m devmcp y toda entrada .mcp.json ya escrita, no.

El arranque se llama desde fuera porque en esa carpeta todavía no hay entrada devmcp en su .mcp.json, así que no hay servidor al que llamar. Desde un clon del repo el equivalente es python -m devmcp.bootstrap, y hace exactamente lo mismo.

Escribe siete cosas, y todas se quedan en el proyecto:

Sirve igual con la carpeta vacía que con un proyecto en marcha, y nada se pisa: el .mcp.json y el CLAUDE.md que ya hubiera se fusionan por marcador, una política ya editada se conserva salvo --overwrite, y un .mcp.json que no se deja parsear no se toca — la entrada se deja al lado para pegarla a mano. Volver a establecer la misma carpeta es un noop explícito: llave de idempotencia determinista, cero efectos declarados.

El catálogo se copia, y en la 0.1 no. La versión que lo apuntaba con DEVMCP_MANIFEST al devMCP de origen daba un catálogo con un dueño, que es mejor argumento — hasta que el origen deja de ser una carpeta del disco. Instalado desde PyPI el origen es site-packages: lo reescribe entero el próximo pip install -U y lo comparten todos los proyectos del venv. Copiado, el catálogo entra en el repo, se versiona con él y se revisa en un diff como la política. Traer una versión nueva es reestablecer con --overwrite, que es explícito y deja recibo. Detalle completo en docs/BOOTSTRAP.md.

Verificación

pip install -e ".[dev]"
python3 tools/gen_schemas.py --check     # deriva devmcp/contracts/ ↔ devmcp/datos/schemas/
python3 tools/verify_design.py           # el diseño completo
python3 tools/bootstrap_demo.py          # la tríada de arranque (27 controles, 16 negativos)

Última ejecución:

1. devmcp/contracts/ ↔ devmcp/datos/schemas/   sincronizado (17 esquemas)
2. manifest (revisión)     22 capacidades · 5 fuentes · 22 artefactos
3. esquemas de artefacto   todo artifact:* tipado
4. aristas del grafo       ticket.key: 4 rutas · design.page_ref: 2 rutas
5. alcanzabilidad          objetivo y evidencia mínima alcanzables
6. concurrencia            github ×4 · jira ×4 · confluence ×3 · kg ×2 (sin cancelación)
7. ExecutionPlan           13 steps / 7 stages · crítico 9200 ms · admisión 11400 ms
7b. invariantes rechazan   9 casos incorrectos, todos rechazados
8. can_do                  input del caso de uso valida
9. manifest SDLC Kanban    71 capacidades (50 read, 1 fanout, 20 do) · 5 fuentes · 78 artefactos
                           toda transición exige política + estado del tablero
                           las 4 operaciones irreversibles declaradas no compensables
                           las 8 etapas del ciclo cubiertas
                           las 8 composiciones cuelgan de la fuente `analysis`, no de quien aportó los datos
                           la erosión de la verificación es observable
9b. autonomía del FSM      5 transiciones automáticas · 13 condiciones de guard resueltas
                           contra los $defs · ningún guard se apoya en juicio
                           radio public y publicar norma nunca se automatizan
9c. síntesis de predicados techo de 5 iteraciones · aceptación por holdout · 4 trampas
                           declaradas · ratificar norma nunca se automatiza
9d. grafo de exploración   expansión judgmental / colapso pure · dedup auditable ·
                           la propuesta entra por la DoR y no crea tarjetas
9e. completions            7 judgmental, todas con modelo y esquema tipado declarados ·
                           ninguna con purpose=score · lentes obligatorias en proponentes ·
                           el optimizador de complejidad solo degrada
10. skills                 14 skills · referencias a capacidades, todas existen

Diseño coherente: todas las comprobaciones pasan.

El bloque 7b es el que importa: comprobar que el contrato acepta lo correcto es la mitad fácil.

Lo que bloquea la implementación

Las primitivas de código ya están. codepreproc expone desde 2026-08-15 los dos tools que faltaban del lado del código (34 tools en total). Ver docs/CODEPREPROC-TOOLS-IMPL.md.

Las dos pendientes componen sobre las dos implementadas más search_context, que ya existía. El razonamiento del reparto está en §7 de docs/CODEPREPROC-TOOLS-IMPL.md: codepreproc contesta preguntas sobre el código; quien pregunta desde fuera del código traduce.

El riesgo de fondo, y cómo está mitigado. Si las páginas normativas no son formalizables, todo cae a textual_fallback + degraded. Pero el riesgo real no es ese: es que el sistema bloquee, alguien afloje min_quality para poder seguir, y nadie note que las garantías se evaporaron. docs/VERIFICATION-GUARDRAILS.md tiene los cinco guard rails — escalera de formalización en vez de acantilado, juicio humano como evidencia de primera clase, relajaciones registradas, trinquete, y métricas del propio sistema de verificación. Y docs/PREDICATE-SYNTHESIS.md lo hace además resoluble: un bucle de 5 iteraciones con backtest sobre los veredictos humanos ya recogidos asciende una regla de prosa a predicado, con una firma humana por regla en vez de una aprobación por PR. Sigue mereciendo la prueba con una página real, pero ahora el resultado posible es un peldaño, no un sí o un no.

Decidido el 2026-08-17: Atlassian Cloud (REST v3/v2 con API token) y ledger en Postgres, el mismo de codepreproc, append-only por contrato y no por motor.

Corrección respecto a la 0.1

SuperKG no es un servidor MCP. Vive in-process dentro de codepreproc (codepreproc.superkg.engine); SuperKGClient llama a KnowledgeGraphService directo, sin capa de red. Es una fuente, no dos, y su endpoint es python -m codepreproc. La 0.1 planificaba sobre un servidor que no existe.

devMCP v0.2.0 — Working Draft · promcp_base: "0.2.0" · contract_version: "0.2.0"