Servidor de herramientas basado en el Model Context Protocol (MCP) para automatizar la generación de Estructuras de Desglose del Trabajo (EDT) en formato Mermaid.js, imagen PNG y documento Word corporativo (.docx) para el proyecto MINTRANET.

🗂️ Estructura del proyecto

.
├── main.py                          # Servidor MCP + registro de herramientas
├── models.py                        # Modelos Pydantic (EDTInput, DocumentoEDTInput, ActividadMinuta)
├── SKILL.md                         # Instrucciones para la IA sobre uso óptimo del MCP
├── config/
│   └── settings.py                  # Constantes: colores, URLs, rutas de salida
└── services/
    ├── mermaid_service.py           # Construcción Mermaid y renderizado PNG (Kroki + mermaid.ink)
    ├── docx_service.py              # Generación de documento Word (.docx) con plantilla corporativa
    └── validator_service.py         # Validación obligatoria de datos antes de generar documentos

🔧 Herramientas disponibles

Herramienta	Descripción
generar_edt	Genera el código Mermaid del EDT en texto
exportar_imagen_edt	Renderiza el EDT como PNG vía Kroki (fallback: mermaid.ink) y lo guarda en ~/Downloads/
validar_datos_proyecto	Verifica que todos los datos requeridos estén completos antes de generar el documento Word
generar_documento_proyecto_word	Genera un documento corporativo .docx con diagrama EDT, tabla base jerarquizada y minuta de validación

---

✅ Requisitos previos

Herramienta	Versión mínima	Enlace
Python	3.10+	python.org
Node.js	18+	nodejs.org
Git	cualquiera	git-scm.com
Claude Desktop	última	claude.ai/download

Windows: usa PowerShell o Git Bash.
macOS/Linux: usa la Terminal estándar.

---

📦 1. Clonar el repositorio

git clone https://github.com/JosaSeCisneros/MCP-GESTI-N-DE-PROYECTOS.git
cd MCP-GESTI-N-DE-PROYECTOS

---

🐍 2. Crear y activar el entorno virtual

macOS / Linux

python3 -m venv venv
source venv/bin/activate

Windows (PowerShell)

python -m venv venv
venv\Scripts\Activate.ps1

Windows (CMD)

python -m venv venv
venv\Scripts\activate.bat

Sabrás que está activo cuando veas (venv) al inicio de tu línea de comandos.

---

📥 3. Instalar dependencias

Con el entorno virtual activo, ejecuta:

pip install -r requirements.txt

---

🖥️ 4. Integrar con Claude Desktop

4.1 Localizar el archivo de configuración

Sistema operativo	Ruta
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

4.2 Encontrar la ruta del Python del venv

Necesitas la ruta absoluta al intérprete Python dentro del venv.

macOS / Linux

# Ejecuta esto estando en la carpeta del proyecto con el venv activo:
which python
# Ejemplo de salida: /Users/tuUsuario/Downloads/Tareas/MCP-GESTI-N-DE-PROYECTOS/venv/bin/python

Windows (PowerShell)

# Ejecuta esto con el venv activo:
where.exe python
# Ejemplo de salida: C:\Users\tuUsuario\...\MCP-GESTI-N-DE-PROYECTOS\venv\Scripts\python.exe

4.3 Editar el archivo de configuración

Abre claude_desktop_config.json y agrega la sección gestion-proyectos dentro de mcpServers:

macOS / Linux

{
  "mcpServers": {
    "gestion-proyectos": {
      "command": "/RUTA_ABSOLUTA/MCP-GESTI-N-DE-PROYECTOS/venv/bin/python",
      "args": [
        "/RUTA_ABSOLUTA/MCP-GESTI-N-DE-PROYECTOS/main.py"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "gestion-proyectos": {
      "command": "C:\\RUTA_ABSOLUTA\\MCP-GESTI-N-DE-PROYECTOS\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\RUTA_ABSOLUTA\\MCP-GESTI-N-DE-PROYECTOS\\main.py"
      ]
    }
  }
}

⚠️ Reemplaza RUTA_ABSOLUTA con la ruta real obtenida en el paso 4.2.
En Windows usa doble barra invertida \\ dentro del JSON.

4.4 Reiniciar Claude Desktop

Menú → Claude → Quit Claude

Luego vuelve a abrirlo. Haz clic en el ícono de martillo 🔨 en el chat para verificar que aparezcan las herramientas:

gestion-proyectos
  ├── generar_edt
  ├── exportar_imagen_edt
  ├── validar_datos_proyecto
  └── generar_documento_proyecto_word

---

🧪 5. Pruebas con el Inspector MCP (sin Claude Desktop)

El inspector abre una UI web para invocar las herramientas manualmente.

macOS / Linux

source venv/bin/activate
mcp dev main.py

Windows

venv\Scripts\Activate.ps1
mcp dev main.py

Luego abre http://localhost:5173 en tu navegador.

Si mcp no se reconoce: python -m mcp dev main.py

---

🧪 6. Prueba rápida desde la terminal

Verifica que todo funciona sin levantar el inspector ni Claude:

macOS / Linux

source venv/bin/activate
python -c "
from main import generar_edt
from models import EDTInput, Fase, Tarea

datos = EDTInput(
    nombre_proyecto='Proyecto de Prueba',
    fases=[
        Fase(nombre='Inicio', tareas=[
            Tarea(nombre='Acta de constitución', subtareas=[
                Tarea(nombre='Firma del patrocinador')
            ])
        ]),
        Fase(nombre='Planeación', tareas=[
            Tarea(nombre='Cronograma', subtareas=[
                Tarea(nombre='Definición de hitos')
            ])
        ]),
    ]
)
print(generar_edt(datos))
"

Windows (PowerShell)

venv\Scripts\Activate.ps1
python -c "from main import generar_edt; from models import EDTInput, Fase, Tarea; datos = EDTInput(nombre_proyecto='Proyecto Test', fases=[Fase(nombre='Inicio', tareas=[Tarea(nombre='Acta', subtareas=[Tarea(nombre='Firma')])])]); print(generar_edt(datos))"

---

🗂️ 7. JSON de prueba en el Inspector

Cuando uses mcp dev main.py, selecciona la herramienta y pega este JSON:

generar_edt — devuelve código Mermaid

{
  "datos": {
    "nombre_proyecto": "Proyecto MINTRANET",
    "fases": [
      {
        "nombre": "Inicio",
        "tareas": [
          {
            "nombre": "Acta de constitución",
            "subtareas": [{ "nombre": "Firma del patrocinador", "subtareas": [] }]
          }
        ]
      },
      {
        "nombre": "Planeación",
        "tareas": [
          {
            "nombre": "Cronograma",
            "subtareas": [{ "nombre": "Definición de hitos", "subtareas": [] }]
          }
        ]
      },
      {
        "nombre": "Ejecución",
        "tareas": [
          {
            "nombre": "Desarrollo del módulo",
            "subtareas": [{ "nombre": "Integración con base de datos", "subtareas": [] }]
          }
        ]
      },
      {
        "nombre": "Control",
        "tareas": [
          {
            "nombre": "Seguimiento de avances",
            "subtareas": [{ "nombre": "Informe semanal", "subtareas": [] }]
          }
        ]
      },
      {
        "nombre": "Cierre",
        "tareas": [
          {
            "nombre": "Entrega final",
            "subtareas": [{ "nombre": "Acta de cierre", "subtareas": [] }]
          }
        ]
      }
    ]
  }
}

exportar_imagen_edt — guarda PNG en ~/Downloads/

Usa el mismo JSON de arriba. La herramienta responderá con:

✅ Imagen generada y guardada exitosamente.
📁 Ruta: /Users/tuUsuario/Downloads/EDT_Proyecto_MINTRANET_20260613_200622.png
🖼️  Archivo: EDT_Proyecto_MINTRANET_20260613_200622.png

---

💬 8. Cómo pedírselo a Claude Desktop

El servidor tiene cuatro herramientas. Claude elige automáticamente la correcta según lo que le pidas.

📋 SKILL.md — Este proyecto incluye un archivo SKILL.md con instrucciones detalladas para que la IA use el MCP de forma óptima. Puedes pedirle a Claude: "Carga el archivo SKILL.md y sigue sus instrucciones para gestionar mi proyecto."

Flujo de trabajo recomendado

1. Recopilar datos — El usuario proporciona archivos .txt o información del proyecto.
2. Validar — Usar validar_datos_proyecto para verificar que todos los campos obligatorios están completos.
3. Completar faltantes — Si hay campos faltantes, solicitarlos al usuario. No inventar datos.
4. Generar — Solo cuando la validación sea exitosa, ejecutar generar_documento_proyecto_word.

Herramienta validar_datos_proyecto → verifica datos antes de generar

"Valida los datos del proyecto antes de generar el documento."

Esta herramienta revisa:

• Nombre e ID del proyecto
• Presupuesto de la fase y presupuesto total
• Actividades de la EDT
• Mínimo 3 actividades de minuta con nombre, tiempo, recursos y responsable
• Conclusión personalizada

Si faltan datos, devuelve una lista clara de lo que necesita el usuario. No genera ningún documento hasta que todos los campos estén completos.

Herramienta generar_edt → devuelve código Mermaid en texto

"Genera el EDT del proyecto MINTRANET con las fases Inicio, Planeación, Ejecución, Control y Cierre en cascada vertical."

Claude devolverá el código Mermaid como texto. Claude Desktop puede renderizarlo como diagrama interactivo, pero solo permite descargarlo como .html, no como imagen.

---

Herramienta exportar_imagen_edt → muestra la imagen en el chat y guarda el PNG

"Genera el EDT del proyecto MINTRANET y muéstrame la imagen."

"Exporta el diagrama como imagen PNG."

"Usa la herramienta exportar_imagen_edt para generar el EDT."

Con esta herramienta Claude Desktop:

1. Muestra la imagen inline directamente en el chat (sin .html)
2. Guarda automáticamente el archivo PNG en ~/Downloads/EDT_Proyecto_MINTRANET_YYYYMMDD_HHMMSS.png

---

Herramienta generar_documento_proyecto_word → genera documento corporativo .docx

"Genera el documento Word de la EDT del proyecto MINTRANET con la estructura metodológica completa."

"Usa la herramienta generar_documento_proyecto_word para crear el documento corporativo."

"Lee los archivos .txt del proyecto y genera el documento Word con el diagrama, la tabla base y la minuta de validación."

Con esta herramienta Claude Desktop:

1. Lee archivos de contexto .txt proporcionados por el usuario
2. Clasifica las tareas dentro de la Estructura Metodológica Fija de 5 etapas
3. Genera un .docx corporativo que incluye:
   • Encabezado corporativo tipo tablero (empresa, título, presupuestos, fecha)
   • Título centrado: PLANTILLA ESTRUCTURA DE DESGLOSE DEL TRABAJO (EDT)
   • Diagrama EDT visual (imagen embebida centrada)
   • Tabla Base de la EDT jerarquizada (Código EDT, Nombre, Descripción Operativa, Hito)
   • Minuta de Validación como anexo independiente (encabezado propio, objetivo, tabla de actividades, conclusión y firmas)
4. Guarda automáticamente el archivo en ~/Downloads/EDT_NombreProyecto_YYYYMMDD_HHMMSS.docx

Campos adicionales del modelo DocumentoEDTInput:

Campo	Tipo	Default	Descripción
nombre_empresa	Optional[str]	"MINTRANET"	Nombre de la empresa en el encabezado
presupuesto_fase	Optional[str]	"N/A"	Presupuesto asignado a la fase
presupuesto_proyecto	Optional[str]	"N/A"	Presupuesto total del proyecto
actividades_minuta	List[ActividadMinuta]	[]	Actividades de la minuta (usa defaults si vacía)
conclusion_minuta	Optional[str]	texto de validación	Conclusión de la minuta

Modelo ActividadMinuta:

Campo	Tipo
actividad	str
tiempo	str
recursos	str
responsable	str

JSON de prueba — generar_documento_proyecto_word

{
  "datos": {
    "nombre_proyecto": "Proyecto MINTRANET",
    "id_proyecto": "PROY-001",
    "nombre_empresa": "MINTRANET",
    "presupuesto_fase": "$500,000",
    "presupuesto_proyecto": "$3,000,000",
    "fases": [
      {
        "nombre": "Inicio",
        "tareas": [
          {
            "nombre": "Acta de constitución",
            "descripcion_operativa": "Documento formal de inicio",
            "hito": "Hito 1",
            "subtareas": [{ "nombre": "Firma del patrocinador", "descripcion_operativa": "Validación final", "hito": "N/A", "subtareas": [] }]
          }
        ]
      },
      {
        "nombre": "Planeación",
        "tareas": [
          {
            "nombre": "Cronograma",
            "descripcion_operativa": "Planificación de actividades",
            "hito": "Hito 2",
            "subtareas": []
          }
        ]
      }
    ],
    "actividades_minuta": [
      { "actividad": "Revisar EDT", "tiempo": "2 horas", "recursos": "Documento EDT", "responsable": "Director del proyecto" },
      { "actividad": "Firmar acta de validación", "tiempo": "30 min", "recursos": "Acta de constitución", "responsable": "Patrocinador del proyecto" }
    ],
    "conclusion_minuta": "La EDT ha sido validada satisfactoriamente por todas las partes. Se procede a la aprobación formal."
  }
}

⚠️ Recuerda reiniciar Claude Desktop después de cualquier cambio en main.py para que cargue la versión actualizada.

---

🛑 Detener el servidor (Inspector)

Presiona Ctrl + C en la terminal.

Para desactivar el entorno virtual:

deactivate

---

❓ Solución de problemas

Problema	Solución
No aparece el 🔨 en Claude Desktop	Verifica las rutas en claude_desktop_config.json y reinicia Claude
Claude solo descarga .html al pedir el diagrama	Pídele explícitamente usar exportar_imagen_edt: "Muéstrame la imagen"
string_too_short en el Inspector	El campo nombre_proyecto quedó vacío — escribe un nombre real antes de ejecutar
mcp: command not found	Usa python -m mcp dev main.py
python: command not found (macOS/Linux)	Usa python3 en lugar de python
Error de permisos en Windows (Activate.ps1)	Ejecuta Set-ExecutionPolicy RemoteSigned -Scope CurrentUser como administrador
Puerto 5173 ocupado	Cierra otras instancias del inspector o reinicia la terminal
ModuleNotFoundError: mcp	Verifica que el (venv) esté activo y ejecuta pip install -r requirements.txt
Error al exportar imagen	Verifica conexión a internet (usa la API de mermaid.ink)
Rutas con espacios en Windows	Encierra las rutas entre comillas dobles en el JSON

---

📝 Notas

• main.py es el punto de entrada del servidor. server.py se conserva como respaldo de la versión monolítica original.
• Los modelos Pydantic están unificados en models.py (TareaBase, FaseBase, EDTInput, DocumentoEDTInput, ActividadMinuta).
• Validación obligatoria: generar_documento_proyecto_word pasa primero por validator_service.py. Si hay datos incompletos, no se genera el documento y se informa qué falta.
• El documento Word usa una plantilla corporativa con encabezado tipo tablero (empresa, proyecto, presupuestos, etapa y fecha).
• La Minuta de Validación funciona como anexo independiente con página propia, encabezado de minuta, objetivo, tabla de actividades y firmas.
• La herramienta generar_edt soporta profundidad ilimitada de tareas y subtareas mediante recursividad.
• La herramienta exportar_imagen_edt requiere conexión a internet (Kroki como primario, mermaid.ink como fallback).
• Los diagramas incluyen estilos de color automáticos para cada fase (5 colores rotativos).
• El archivo SKILL.md contiene instrucciones detalladas para que la IA recopile datos, valide y genere documentos de forma correcta y sin alucinaciones.

Autores

• Jose Manuel Cisneros Valero
• García Vázquez Rogelio
• Gonzales Velázquez Josué
• Flores Jasso Miguel Angel
• Martínez Nicolas Francisco Leonardo
• Parra Mendoza Ernesto Zuriel