MCP Server - Gestión de Colaboradores y Talento Humano (PostgreSQL)

Este proyecto es un servidor de Model Context Protocol (MCP) desarrollado en Python utilizando librerías 100% de código abierto (principalmente el SDK oficial de MCP y FastMCP). Se conecta a una base de datos relacional en PostgreSQL y expone una serie de herramientas (Tools) y recursos (Resources) lógicos para que agentes de Inteligencia Artificial (IDEs como Cursor, VS Code, Antigravity) puedan realizar búsquedas complejas y análisis sobre el capital humano de una empresa.

El sistema resuelve el problema de la dispersión de datos unificando en un solo lugar la información sobre perfiles, roles, asignación de equipos (squads), habilidades técnicas (skills), avance de cursos de capacitación y tareas activas.

---

1. Arquitectura y Reglas de Negocio

El diseño del servidor MCP se basa en la Arquitectura de Agentes Eficientes para optimizar el consumo de tokens y prevenir alucinaciones de los modelos de lenguaje:

• Resource Estático (db://schema): En lugar de enviar sentencias CREATE TABLE pesadas, se entrega un catálogo semántico en formato JSON condensado con la estructura lógica, relaciones clave y reglas del sistema.
• Mitigación de Token Bloat (Control de Inundación): Las herramientas de búsqueda masiva (ej. search_collaborators_by_skill) están limitadas a un máximo de 10 registros. Si la consulta supera este límite, el servidor intercepta el flujo y devuelve un estado ambiguous_result con "facetas" o agregaciones de datos (distribución por seniority y squads), obligando a la IA a pedirle un filtro más cerrado al usuario.
• Vistas Consolidadas en Backend: Las operaciones de agregación y los JOINs se resuelven en consultas SQL parametrizadas optimizadas, entregando DTOs (Data Transfer Objects) limpios a la IA.
• Reglas de Negocio Implementadas:
  • Calificación de Skills: Rango discreto de 1 a 10.
  • Avance de Capacitaciones: Porcentaje del 1 al 100. Un avance < 100 o nulo se infiere como un upskilling activo o una brecha formativa a cubrir.
  • Detección de Burnout: El sistema analiza tareas con estado EN_CURSO. Se marca riesgo de burnout si la estimación semanal supera las 40 horas o si el colaborador trabaja en múltiples tareas EN_CURSO de forma paralela (multitasking).
  • Detección de Brechas Formativas (Gaps): Se comparan las tecnologías dominadas por otros miembros del squad (nivel >= 5) con las del colaborador en cuestión, identificando cuáles de ellas tiene en nivel bajo (< 3) o sin registrar.

---

2. Estructura de Carpetas

El proyecto está diseñado bajo buenas prácticas de modularidad, dividiendo responsabilidades en carpetas y archivos específicos:

mcp-workers/
├── src/
│   ├── tools/
│   │   ├── collaborators.py  # Consulta de perfiles e integrantes de Squads
│   │   ├── tasks.py          # Creación, actualización de tareas y cálculo de Burnout
│   │   ├── skills.py         # Matriz de conocimientos y desambiguación de inundación
│   │   └── courses.py        # Seguimiento académico y brechas formativas (Upskilling)
│   ├── resources/
│   │   └── schema.py         # Catálogo semántico estático (db://schema)
│   ├── config.py             # Carga y validación de variables de entorno (.env)
│   ├── database.py           # Gestor de conexiones y transacciones seguras (PostgreSQL)
│   ├── errors.py             # Errores globales normalizados (ERR_COLABORADOR_NO_ENCONTRADO, etc.)
│   ├── models.py             # Modelos de validación y DTOs basados en Pydantic
│   └── main.py               # Orquestador del servidor FastMCP y puntos de entrada
├── Dockerfile                # Configuración de imagen Docker para el servidor MCP
├── docker-compose.yml        # Orquestación de base de datos PostgreSQL + Servidor MCP
├── init.sql                  # Definición de tablas y datos semilla de prueba
├── requirements.txt          # Dependencias Open Source del proyecto
├── .env.example              # Plantilla de variables de entorno
├── .env                      # Variables de entorno locales
├── .gitignore                # Reglas de exclusión de Git
└── .dockerignore             # Reglas de exclusión para empaquetado Docker

---

3. Prácticas de Seguridad Implementadas

1. Prevención de SQL Injections: Todas las consultas a la base de datos se realizan con consultas parametrizadas a través del driver psycopg2. Jamás se concatena texto para armar queries dinámicas.
2. Validación de Rangos y Tipados Estrictos: Los inputs y outputs de las herramientas se validan utilizando Pydantic y restricciones lógicas a nivel base de datos (CHECK constraints y validadores python).
3. Gestión Segura de Secretos: Las contraseñas, hosts y puertos no están hardcodeados en el código fuente. Se extraen de variables de entorno gestionadas localmente por .env.
4. Aislamiento de Docker: La base de datos no expone puertos innecesarios internamente más que a la red de Docker, aunque se mapea el puerto 5432 externamente para facilidades de desarrollo local controlado. El servidor se ejecuta con un usuario no administrativo dentro del contenedor y no monta volúmenes innecesarios.

---

4. Despliegue Rápido (Con Docker Compose)

Para levantar la base de datos PostgreSQL (con toda la estructura de tablas y datos semilla) en conjunto con el servidor MCP en un solo comando:

1. Asegúrate de tener instalado Docker y Docker Compose.
2. Crea un archivo .env en la raíz del proyecto (puedes copiar el archivo .env.example):

   cp .env.example .env
   

3. Ejecuta el siguiente comando para compilar y levantar los contenedores:

   docker compose up --build -d
   

4. El contenedor de base de datos se iniciará, ejecutará el script init.sql para crear y poblar las tablas, y el contenedor mcp-server esperará a que el motor esté listo mediante su healthcheck interno antes de iniciar el servidor en el puerto 8000 exponiendo el endpoint /mcp.

---

5. Configuración en Clientes MCP (Antigravity y Cursor)

A. Integración en Cursor (Modo HTTP)

Cuando el servidor está corriendo dentro de Docker en modo HTTP JSON-RPC:

1. Abre Cursor y ve a Settings -> Beta -> Features -> MCP.
2. Haz clic en + Add New MCP Server.
3. Completa los campos:
   • Name: MCP Colaboradores
   • Type: http o SSE
   • URL: http://localhost:8000/mcp
4. Guarda la configuración.

B. Integración en Cursor (Modo Stdio / Sin Docker)

Si prefieres correr la base de datos en Docker pero ejecutar el servidor MCP de manera local directa a través del comando STDIO:

1. Asegúrate de que la base de datos de Docker esté activa (docker compose up db).
2. Instala el entorno virtual en la raíz del proyecto y sus dependencias:

   python -m venv .venv
   .venv\Scripts\activate     # En Windows
   pip install -r requirements.txt
   

3. En Cursor, agrega el servidor MCP con la siguiente configuración:
   • Name: MCP Colaboradores Local
   • Type: command
   • Command: C:\drafts\mcp-workers\.venv\Scripts\python.exe -m src.main
4. Asegúrate de tener un archivo .env local en la raíz con la configuración:

   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=mcp_colaboradores
   DB_USER=postgres
   DB_PASSWORD=postgres_secure_pass_2026
   

C. Integración en Antigravity

Para registrar este MCP en Antigravity, puedes usar el archivo mcp.json creado en la raíz del proyecto o agregar la siguiente entrada a tu configuración de servidores MCP HTTP:

{
  "mcpServers": {
    "mcp-colaboradores-http": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}

---

6. Listado de Herramientas Expuestas a la IA

Nombre	Parámetros	Descripción
obtener_ficha_colaborador	identificador: str	Devuelve el perfil completo de un colaborador (datos personales, seniority, equipo, rol, conocimientos, cursos y brechas formativas frente a su equipo) resolviendo por correo, legajo o nombre parcial. Si hay múltiples coincidencias, retorna ambiguous_result.
analizar_estructura_equipo	nombre_equipo: str	Lista los miembros de un equipo (squad) con su legajo, nombre completo, email y rol asignado.
consultar_estado_operativo	identificador: str	Analiza la carga operativa de un colaborador, listando sus tareas activas, la carga horaria acumulada, la fecha de liberación estimada y evaluando riesgos de burnout (multitasking o >40 horas).
buscar_colaboradores_por_habilidad	tecnologia: str, nivel_min?: int, seniority?: str, equipo?: str	Busca colaboradores calificados. Filtra por nivel (1-10), seniority y equipo. Si supera los 10 registros, activa control de inundación con facetas. Retorna 0 resultados de forma segura si la tecnología no está en el catálogo.
listar_catalogos_maestros	tipo_catalogo: str	Lista nombres del catálogo (tecnologias, proyectos, equipos, roles o seniorities) para evitar alucinaciones.
ejecutar_consulta	sql: str	Ejecuta una consulta SQL SELECT libre de lectura. Capped automáticamente a 100 registros por seguridad y bloquea keywords de modificación (INSERT, UPDATE, etc.).