# Software Estimation MCP

[![CI](https://github.com/SantosRojas/software-estimation-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SantosRojas/software-estimation-mcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Servidor MCP en Python para convertir requerimientos de desarrollo de software en una estimación trazable, riesgos, cronograma, cotización y documentos PDF listos para revisión comercial.

## Decisión de ecosistema

**Python + FastMCP 4 + Pydantic + ReportLab.** El dominio contiene cálculos deterministas y validaciones, y ReportLab genera PDF directamente sin necesitar Chromium, Node, fuentes descargadas o un servicio de conversión externo. El núcleo de negocio está separado de la capa MCP para que se pueda probar sin iniciar un agente.

Requiere Python 3.11 o superior. La línea `fastmcp>=4,<5` corresponde a la versión estable actual de FastMCP a octubre de 2026. Para conectores de escritorio, el transporte por defecto es `stdio`; para despliegues en red se ofrece HTTP Streamable.

## Funcionalidades y herramientas MCP

| Herramienta | Para qué sirve |
|---|---|
| `wbs_breakdown` | Genera una WBS inicial para una nueva funcionalidad, bugfix, parche legado, refactor o integración. |
| `calculate_pert` | Calcula tiempo esperado, desviación, varianza, nivel de riesgo e intervalos orientativos a partir de O/M/P. |
| `apply_buffers` | Aplica buffers de codebase, integraciones, PM, QA y contingencia explícita. Los porcentajes se suman de forma aditiva sobre PERT, como en la especificación. |
| `calculate_quotation` | Calcula coste directo, overhead, precio a partir de margen sobre venta, impuesto indicado y total. |
| `generate_roadmap` | Estima días laborables y distribuye esfuerzo entre análisis, desarrollo, QA y despliegue, con fechas cuando se proporciona inicio. |
| `analyze_scope_gaps` | Produce preguntas de descubrimiento para evitar comprometer plazo/precio con alcance ambiguo. |
| `build_risk_register` | Genera un registro de riesgos típico, puntuación, nivel, mitigación y propietario sugerido. |
| `compare_scenarios` | Compara hasta diez escenarios de coste/precio y calendario bajo los supuestos recibidos. |
| `generate_proposal_markdown` | Unifica WBS, PERT, precio, calendario, exclusiones, supuestos y riesgos en Markdown. |
| `generate_proposal_pdf` | Genera una propuesta técnica/comercial en PDF. |
| `generate_action_plan_markdown` | Genera un plan de acción con fases, responsables, dependencias y evidencia de cierre. |
| `generate_action_plan_pdf` | Genera un plan de acción independiente en PDF. |
| `generate_quote_pdf` | Genera una cotización PDF independiente, con desglose financiero, supuestos y exclusiones. |
| `render_markdown_pdf` | Convierte Markdown a PDF para otros documentos. Admite títulos, listas y tablas; no descarga ni ejecuta HTML externo. |

## Instalación en Windows (PowerShell)

Usa [uv](https://docs.astral.sh/uv/) para un entorno reproducible a partir de `uv.lock`:

```powershell
# Desde la carpeta del proyecto
uv sync --extra dev

# Prueba rápida del núcleo de negocio y del generador PDF
uv run pytest -q

# Iniciar el MCP en STDIO (normalmente lo inicia el cliente MCP)
uv run python -m estimation_mcp.server
```

### Instalación directa desde GitHub

```powershell
uv tool install "git+https://github.com/SantosRojas/software-estimation-mcp.git"
```

O, en modo desarrollo con las dependencias de prueba:

```powershell
uv pip install -e "git+https://github.com/SantosRojas/software-estimation-mcp.git#dev"
```

## Conectar con un cliente MCP

Hay dos plantillas en `examples/`; cambia las rutas por la ubicación real del proyecto:

- `examples/mcp-config.json` — formato `mcpServers` para Cursor, Claude Desktop u otro cliente compatible (Windows; la variante Linux está en `examples/mcp-config.linux.json`).
- `examples/opencode.json` — formato `mcp.servers` para OpenCode (Windows; Linux en `examples/opencode.linux.json`). Puede usarse como configuración de proyecto en cualquier repositorio consumidor, o copiarse a `~/.config/opencode/opencode.json` para disponer del servidor en todos los proyectos.

Formato estándar (`mcpServers`):

```json
{
  "mcpServers": {
    "software-estimation": {
      "command": "C:\\Projects\\software-estimation-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "estimation_mcp.server"],
      "env": {
        "ESTIMATOR_OUTPUT_DIR": "C:\\Projects\\software-estimation-mcp\\output",
        "ESTIMATOR_TRANSPORT": "stdio",
        "ESTIMATOR_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

Formato OpenCode (`opencode.json`):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "software-estimation": {
        "type": "local",
        "command": [
          "C:\\Projects\\software-estimation-mcp\\.venv\\Scripts\\python.exe",
          "-m",
          "estimation_mcp.server"
        ],
        "environment": {
          "ESTIMATOR_OUTPUT_DIR": "C:\\Projects\\software-estimation-mcp\\output",
          "ESTIMATOR_TRANSPORT": "stdio",
          "ESTIMATOR_LOG_LEVEL": "INFO"
        }
      }
    }
  }
}
```

El cliente ejecuta un proceso independiente. Reinicia el cliente MCP después de modificar su configuración. No escribas mensajes de depuración en `stdout` de un servidor `stdio`; ese canal transporta el protocolo.

## Transporte HTTP Streamable

Solo para despliegues en red. Primero instala el paquete en un entorno virtual del host; después configura:

```powershell
$env:ESTIMATOR_TRANSPORT = "http"
$env:ESTIMATOR_HTTP_HOST = "127.0.0.1"
$env:ESTIMATOR_HTTP_PORT = "8000"
$env:ESTIMATOR_OUTPUT_DIR = "C:\\ProgramData\\SoftwareEstimationMCP\\output"
python -m estimation_mcp.server
```

El endpoint queda en `http://127.0.0.1:8000/mcp`. El valor predeterminado es loopback intencionalmente. **No lo expongas directamente a Internet**: ponlo detrás de un gateway/proxy con autenticación, autorización, TLS, límites de solicitudes y registro operativo. Para una instalación remota real, habilita la autenticación de FastMCP o la del gateway y prueba los permisos del directorio de documentos antes de producción.

## Configuración de archivos de salida

Los PDF se guardan en `ESTIMATOR_OUTPUT_DIR`; por defecto, en `./output` relativo al directorio desde donde se inició el proceso. La herramienta devuelve ruta absoluta, URI local, nombre, tamaño y SHA-256. El cliente/usuario debe tener acceso a la ruta del servidor: la ruta local no se transfiere automáticamente al agente remoto.

Los nombres se convierten a slug seguro, se ignoran directorios indicados por el modelo y se usa un nombre alternativo si el archivo ya existe. No se sobrescriben documentos anteriores de forma silenciosa.

## Flujo de trabajo recomendado

1. Ejecutar `analyze_scope_gaps` con el requerimiento disponible. Resolver con el usuario las preguntas críticas; no marcar una categoría como cerrada por inferencia.
2. Ejecutar `wbs_breakdown` y ajustar las tareas al alcance confirmado. Solicitar O/M/P por tarea y ejecutar `calculate_pert`.
3. Ejecutar `apply_buffers` usando el tipo de código, integraciones y QA reales. La contingencia extra debe justificarse para no duplicar reservas.
4. Ejecutar `calculate_quotation` con tarifa de coste, overhead, margen, moneda y tasa tributaria confirmados. La tasa fiscal por defecto es 0; la herramienta no adivina el tratamiento tributario.
5. Ejecutar `generate_roadmap` con capacidad efectiva, disponibilidad real y fecha objetivo cuando se conozca.
6. Usar `build_risk_register`; revisar probabilidad/impacto y asignar responsables reales.
7. Generar `generate_proposal_markdown` y revisar supuestos, exclusiones, alcance, impuesto, cronograma y condiciones comerciales.
8. Generar `generate_proposal_pdf` para la propuesta completa, `generate_quote_pdf` para una cotización corta o `generate_action_plan_pdf` para el plan interno/de ejecución.
9. Revisar el PDF final manualmente antes de enviarlo al cliente.

## Metodología y límites importantes

- **PERT:** `E = (O + 4M + P) / 6`; `SD = (P - O) / 6`; se combina varianza asumiendo independencia. `E + SD` y `E + 2SD` son referencias aproximadas, no promesas de fecha ni intervalos calibrados para todos los proyectos.
- **Buffers:** los porcentajes se suman sobre la estimación base, de acuerdo con la especificación original; no se aplican en cascada. No dupliques una reserva ya incluida en cada tarea.
- **Margen:** el precio antes de impuestos es `coste total / (1 - margen objetivo)`, es decir, margen sobre venta y no recargo sobre coste.
- **Calendario:** se estiman días laborables lunes-viernes, sin festivos, vacaciones, ruta crítica o asignaciones parciales por persona. Es una primera aproximación de capacidad.
- **Cotización:** la moneda predeterminada es `PEN`, pero la tasa tributaria predeterminada es `0%` y debe indicarse explícitamente. Verifica la normativa aplicable, IGV/IVA, retenciones, licencias, alcance, plazos, vigencia y condiciones de pago.
- La WBS, preguntas y riesgos son ayudas para el profesional; no reemplazan el juicio técnico, la validación con el cliente ni un contrato aprobado.

## Observabilidad

Cada invocación de herramienta emite logs estructurados en JSON por `stderr` (nunca por `stdout`, que transporta el protocolo STDIO):

```json
{"event": "tool_started", "tool": "calculate_pert", "correlation_id": "9676921e1f1c423b"}
{"event": "tool_completed", "tool": "calculate_pert", "correlation_id": "9676921e1f1c423b", "duration_ms": 0.18}
{"event": "tool_failed", "tool": "calculate_pert", "correlation_id": "83c9fa46b78a4895", "duration_ms": 0.07, "error_type": "ValueError", "error": "..."}
```

- `correlation_id` sigue una llamada de extremo a extremo en los logs del host.
- `duration_ms` permite calcular latencia; los eventos `tool_completed`/`tool_failed` sirven como contadores de éxito/fallo.
- El nivel se controla con `ESTIMATOR_LOG_LEVEL` (`DEBUG`, `INFO` —predeterminado—, `WARNING`, `ERROR`). Un nivel inválido cae a `INFO`.

## Pruebas

```powershell
uv run pytest -q
uv run ruff check src tests
```

Las pruebas cubren fórmulas, validaciones de entradas, suma de buffers, cálculo de margen e impuesto, reparto de días de fases, preguntas de alcance, orden del registro de riesgos, comparación de escenarios, escritura de PDF y la protección contra path traversal. Los archivos `examples/demo-*.pdf` son ejemplos ficticios, no cotizaciones reales.

## Estructura

```text
src/estimation_mcp/
  domain/estimation.py       # cálculos de estimación y cronograma
  domain/scope.py            # preguntas de alcance y registro de riesgos
  services/documents.py      # Markdown y PDF
  observability.py           # logs estructurados por stderr
  server.py                  # herramientas y transporte MCP
  cli.py                     # entry point opcional
 tests/                       # pruebas automatizadas
 .github/workflows/ci.yml     # CI: ruff + pytest en 3.11 y 3.13
 examples/                    # configuración y PDFs ficticios
 docs/                        # guía y referencia de herramientas
```