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

```text
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`):
    ```bash
    cp .env.example .env
    ```
3.  Ejecuta el siguiente comando para compilar y levantar los contenedores:
    ```bash
    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:
    ```bash
    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:
    ```env
    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:

```json
{
  "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.). |