Software Estimation MCP

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.

Related MCP server: Overseer MCP Server

Funcionalidades y herramientas MCP

Instalación en Windows (PowerShell)

Usa uv para un entorno reproducible a partir de uv.lock:

# 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

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

O, en modo desarrollo con las dependencias de prueba:

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):

{
  "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):

{
  "$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:

$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):

{"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

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

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