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.

Related MCP server: Postgres MCP Pro

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