Metadata-Version: 2.5
Name: phylos-mcp
Version: 0.2.1
Summary: Un servidor MCP que planifica sobre un catálogo de capacidades en vez de exponer una herramienta por sistema
Project-URL: Homepage, https://github.com/alexlqi/devmcp
Project-URL: Documentation, https://github.com/alexlqi/devmcp/tree/main/docs
Project-URL: Issues, https://github.com/alexlqi/devmcp/issues
Project-URL: Source, https://github.com/alexlqi/devmcp
Author: alexlqi
License-Expression: MIT
License-File: LICENSE
Keywords: confluence,github,jira,mcp,planner,sdlc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: jsonschema>=4.0; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Description-Content-Type: text/markdown

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

Extensión de dominio de [proMCP v0.3.0](https://github.com/alexlqi/proMCP) 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`](https://github.com/alexlqi/devmcp/blob/main/docs/ADR-003-concurrencia-y-contratos-estrictos.md)
si te interesa la capa de federación, o por [`ADR-002`](https://github.com/alexlqi/devmcp/blob/main/docs/ADR-002-planner-devmcp-multifuente.md)
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í

| Archivo | Qué es |
|---|---|
| **`docs/TODO.md`** | **Empieza aquí si vas a seguir construyendo.** Todo lo que falta, con el qué y lo que cada qué debe lograr: las 20 capacidades internas que no existen, los 4 adaptadores reales, el transporte MCP, el ledger Postgres, el FSM, la política, y la deuda contada. Más las reglas de la casa, que no son estilo: cada una salió de un fallo concreto. |
| `docs/BOOTSTRAP.md` + `devmcp/bootstrap/` | **Nuevo — la tríada de arranque.** `can_do`, `read_establishment_survey` y `do_establish_devmcp`: establecer devMCP en una carpeta cualquiera —vacía o con un proyecto dentro— sin pisar nada de lo que ya hubiera. Servidor proMCP propio (`devmcp-bootstrap`, o `python -m devmcp.bootstrap` desde un clon) porque los siete tools del servidor grande hablan de planes sobre un manifest ya cargado, y aquí todavía no hay ninguno. 27 controles, 16 negativos; uno de ellos encendió el servidor establecido y destapó que `tools/list` moría en Windows por el códec de la consola. |
| `docs/ADR-002-planner-devmcp-multifuente.md` | Por qué un planner y no cuatro MCPs sueltos. La decisión de partida. |
| `docs/ADR-003-concurrencia-y-contratos-estrictos.md` | Cómo hablan planner y fuentes, y qué puede pasar a la vez. Hechos verificados sobre el código real de codepreproc. |
| `docs/SDLC-KANBAN.md` | **Nuevo.** El ciclo de vida completo sobre Kanban: la tesis (las políticas explícitas de Kanban *son* la evidence policy), las 7 etapas, los 5 fallos que ataca, y dónde está la frontera entre lo que decide el agente y lo que decide una persona. |
| `docs/DEVMCP-0.2-SPEC.md` | **La spec vigente.** Topología, 7 tools, contratos estrictos, sobre inter-MCP, concurrencia en dos niveles, `can_do` en 7 fases, ExecutionPlan, FSM, idempotencia, y el binding real a codepreproc. |
| `docs/DEVMCP-0.1-SPEC.md` | *Superada por la 0.2.* Se conserva por trazabilidad; §1 de la 0.2 resume qué cambió y por qué. |
| `devmcp/contracts/` | **Fuente de verdad.** Modelos Pydantic v2: sobre, contratos proMCP base, intención, plan, manifest, taxonomía de errores. |
| `devmcp/datos/schemas/` | JSON Schema **generados** desde `devmcp/contracts/`. No editar a mano. |
| `devmcp/datos/schemas/artifacts.schema.json` | Esquemas de payload de cada artefacto. Es lo que hace que el grafo esté tipado de verdad. |
| `devmcp/datos/manifests/devmcp.manifest.yml` | Manifest del caso de uso de revisión: 5 fuentes, 22 capacidades, 22 artefactos. |
| `devmcp/datos/manifests/sdlc-kanban.manifest.yml` | El ciclo completo: 71 capacidades (50 read, 1 fanout, 20 do), 78 artefactos, 4 calibraciones y 5 transiciones automáticas. |
| `devmcp/datos/skills/` | 14 playbooks SKILL.md. Los tools dicen qué se puede saber; las skills, qué hacer con ello. |
| `docs/walkthrough-pr-jira-confluence.md` | El caso de uso trazado de punta a punta, con variantes de fallo. |
| `docs/COMPLETIONS-AND-COMPLEXITY.md` | **Nuevo.** La completion como contrato (modelo, esquema tipado, traza), las lentes de calidad y rendimiento como campos obligatorios, y el optimizador de complejidad que solo degrada. |
| `docs/EXPLORATION-GRAPH.md` | **Nuevo.** Recorrer el espacio de diseño de un feature como hipergrafo AND-OR: expansión acotada con RAG y dedup semántico, colapso con el mismo hiperDijkstra que `can_do`. |
| `docs/PREDICATE-SYNTHESIS.md` | **Nuevo.** Cómo una sugerencia del modelo se gana ser una validación: corpus etiquetado desde los veredictos humanos, bucle de 5 iteraciones con backtest y holdout, ratificación humana única. |
| `docs/AUTONOMY-LADDER.md` | **Nuevo.** Sacar al humano del bucle: `AWAITING_EVIDENCE`, la escalera de `Gate`, determinismo verificado, `blast_radius` y guards tipados. Las 5 transiciones automáticas y las 2 que no se automatizan por diseño. |
| `docs/VERIFICATION-GUARDRAILS.md` | **Nuevo.** Los 5 guard rails contra el riesgo real: no que las normas sean informales, sino que el sistema bloquee, alguien afloje la política, y nadie note que dejó de verificar. |
| `docs/DEVMCP-ANALYSIS-IMPL.md` | **Nuevo.** Cómo `read_pattern_conformance` y `read_acceptance_coverage` se componen en devMCP sobre las primitivas de codepreproc. La fuente `analysis` y sus reglas de degradación. |
| `docs/CODEPREPROC-TOOLS-IMPL.md` | Guía de implementación de `read_symbols_for_files` y `read_change_envelope` en codepreproc, escrita contra el código real. **Implementados.** |
| `docs/FORMALIZATION-PROBE.md` | **Nuevo.** B1 cerrado: la prueba de formalización, medida sobre las páginas reales de codepreproc. El `layer_map` cubre el 18% del repo; las reglas verificables son de protocolo, no de arquitectura. Cambia el orden de implementación de `read_pattern_conformance`. |
| `docs/PROMCP-CONFORMANCE.md` | **Nuevo.** devMCP contra la spec base, comprobado contra `E:\e_repos\promcp` en vez de citado de memoria. Seis desviaciones; la peor habría hecho que un PR no se fusionara — sin error — porque la llave de idempotencia se repetía entre planes y el servidor, cumpliendo §9.2, no reaplicaba el efecto. |
| `devmcp/server/` + `tools/server_demo.py` | **Nuevo — la superficie que ve el modelo.** Seis tools proMCP sobre un catálogo de 71 capacidades: `can_do`, `do_execute_plan`, `read_plan_status`, `do_approve_step`, `read_capabilities`, `read_contract`. El número no es una limitación que se sufre: es la consecuencia de que el modelo declare intención en vez de elegir capacidad. |
| `docs/EXECUTOR.md` + `devmcp/executor/` | **Nuevo.** Recorre el plan: pool con afinidad por sesión, semáforos por recurso, ledger append-only que deduplica de verdad, gates que detienen antes de llamar y compensación que declara lo irreversible en vez de fingir que lo deshace. 29 controles, 23 negativos. |
| `docs/PLANNER.md` + `devmcp/planner/` | **Nuevo — la primera pieza que corre.** Dijkstra generalizado de Knuth sobre el hipergrafo AND-OR: de una intención a un `ExecutionPlan` de 17 steps en 8 stages con barreras tipadas y contención calculada antes de ejecutar. Su control negativo destapó que `CapabilityReport` no sabía decir "no hay ruta". |
| `docs/EVIDENCE-INTEGRITY.md` | **Nuevo.** El instrumento mirándose a sí mismo: `Calibration` (un número a ojo caduca por contrato), `Control` (la entrada que DEBE fallar), y seis capacidades que detectan deriva de contrato, umbrales sin procedencia y verificadores que solo saben decir que sí. Guard en las 5 transiciones automáticas. |
| `docs/CODEPREPROC-FIXES-C1-C5.md` | **Nuevo.** Cinco correcciones sobre código en producción, tres de ellas bugs vivos que no dan error: un fichero ausente que está, veinte llamadores de cuarenta y siete, y decisiones de otro componente presentadas como las de este. Todas encontradas escribiendo el contrato de la respuesta, no ejecutando el código. |
| `pyproject.toml` + `devmcp/recursos.py` | **Nuevo — devMCP como paquete.** `pip install phylos-mcp` deja dos ejecutables (`devmcp`, `devmcp-bootstrap`). Todo lo que devMCP necesita en ejecución vive en `devmcp/datos/` y viaja con el paquete: catálogos, esquemas, skills, política y el panel construido. `recursos.py` es el único módulo que resuelve dónde está cada cosa; antes lo hacían ocho sitios con `Path(__file__).parent.parent`, dando por hecho un checkout. |
| `tools/gen_schemas.py` | Genera `devmcp/datos/schemas/` desde `devmcp/contracts/`. `--check` falla si divergen. |
| `tools/verify_design.py` | Verificación ejecutable del diseño completo. |
| `devmcp/analysis/formalization_probe.py` | **Nuevo.** Mete una página normativa y un repo, saca su peldaño L0–L4, el `layer_map` medido y qué reglas caen en prosa. Sin red ni dependencias. `--selftest` corre los dos controles de `tools/fixtures/`. |

## 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](https://github.com/alexlqi/devmcp/blob/main/docs/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](https://github.com/alexlqi/devmcp/blob/main/docs/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í.

```bash
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:

| Fichero | Qué es |
|---|---|
| `devmcp.manifest.yml` | El catálogo de capacidades, copiado. Se versiona con el repo. |
| `devmcp.policy.yml` | Qué permite **este** proyecto: suelo de evidencia, radio, vetos. |
| `.mcp.json` | La entrada `devmcp`, **fusionada** con los servidores que ya hubiera. |
| `.env.example` | Qué variable pide cada fuente, sacado del catálogo y no de la memoria de nadie. |
| `.claude/skills/` | Los 14 procedimientos, para que el modelo sepa qué hacer con los siete tools. |
| `CLAUDE.md` | Un bloque marcado que dice que devMCP está aquí y cuál es el orden de los verbos. |
| `.devmcp/` | El estado, el ledger y el recibo del arranque. No se versiona. |

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`](https://github.com/alexlqi/devmcp/blob/main/docs/BOOTSTRAP.md).

## Verificación

```bash
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`](https://github.com/alexlqi/devmcp/blob/main/docs/CODEPREPROC-TOOLS-IMPL.md).

| Tool | Estado |
|---|---|
| `read_symbols_for_files(files[])` | ✅ implementado — consulta dirigida sobre `idx_file`, devuelve `chunk_id` y procedencia |
| `read_change_envelope(chunk_ids[])` | ✅ implementado — expone `get_change_envelope` con `kg_backed` explícito |
| `read_pattern_conformance(...)` | pendiente **en devMCP** (fuente `analysis`) — diseño en [`docs/DEVMCP-ANALYSIS-IMPL.md`](https://github.com/alexlqi/devmcp/blob/main/docs/DEVMCP-ANALYSIS-IMPL.md) |
| `read_acceptance_coverage(...)` | pendiente **en devMCP** (fuente `analysis`) — ídem |

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`](https://github.com/alexlqi/devmcp/blob/main/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`](https://github.com/alexlqi/devmcp/blob/main/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"`*
