🦆 Servidor MCP de Gestión de Proyectos

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

Related MCP server: Document Organizer MCP Server

✅ Requisitos previos

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

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:

Modelo ActividadMinuta:

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

📝 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