# Servidor MCP Inklusport (Python)

Servidor **MCP (Model Context Protocol)** con la misma base que el ejemplo de clase
(`mcp>=2.0.0`, `MCPServer`, `@server.tool`, transporte HTTP).

Las tools de dominio **no tocan bases de datos**: hacen GET HTTP a
`ink-ms-users` (puerto 3002) e `ink-ms-sports` (puerto 3003). Un **agente por rol**
(usuario, entrenador, organizador, admin) ve solo las tools que le corresponden.

---

## Herramientas (lectura y gestión → microservicios)

| Herramienta | Microservicio | Endpoint | Casos de prueba |
| :--- | :--- | :--- | :--- |
| `listar_discapacidades` | sports | `GET /api/disabilities` | CP1-HU16.2 |
| `consultar_discapacidad` | sports | `GET /api/disabilities/{id}` | CP2-HU16.2 |
| `registrar_discapacidad` | sports | `POST /api/disabilities` | CP1-HU16.1, CP2-HU16.1 |
| `editar_discapacidad` | sports | `PUT /api/disabilities/{id}` | CP1-HU16.3, CP2-HU16.3 |
| `desactivar_discapacidad` | sports | `PATCH /api/disabilities/{id}/deactivate` | CP1-HU16.4, CP2-HU16.4 |
| `reactivar_discapacidad` | sports | `PATCH /api/disabilities/{id}/activate` | CP1-HU16.4 |
| `listar_adaptaciones_deporte` | sports | `GET /api/sport-disabilities/sport/{sportId}` | CP1-HU17, CP2-HU17 |
| `listar_eventos` | sports | `GET /api/events` | CP1-HU18 |
| `crear_evento` | sports | `POST /api/events` | CP2-HU18, CP1-HU18.1, CP2-HU18.1 |
| `listar_eventos_disponibles` | sports | `GET /api/events/available` | CP1-HU18.2 |
| `consultar_evento` | sports | `GET /api/events/{id}` | CP2-HU18.2 |
| `editar_evento` | sports | `PUT /api/events/{id}` | CP1-HU18.3, CP2-HU18.3 |
| `cancelar_evento` | sports | `POST /api/events/{id}/cancel` | CP1-HU18.4, CP2-HU18.4 |
| `inscribirse_evento` | sports | `POST /api/registrations` | CP1-HU18.5, CP2-HU18.5 |
| `consultar_calendario_eventos` | sports | `GET /api/events/calendar` | CP1-HU19, CP2-HU19 |
| `consultar_usuario` | users | `GET /api/internal/users/{id}` (o email → `id-by-email`) | — |
| `consultar_inscripciones` | sports | `GET /api/registrations/user/{userId}` | — |
| `consultar_roles_por_email` | users | `GET /api/internal/users/roles-by-email` | — |
| `listar_usuarios` / `buscar_usuarios` | users | `GET /api/admin/users` / `search` | — |
| `bloquear_usuario` | users | `POST /api/admin/users/{email}/block` | — |
| `desactivar_usuario` | users | `POST /api/admin/users/{email}/deactivate` | — |
| `activar_usuario` | users | `POST /api/admin/users/{email}/activate` | — |
| `eliminar_usuario` | users | `DELETE /api/admin/users/{email}` | — |
| `asignar_rol` / `reemplazar_roles` | users | `POST` / `PUT /api/admin/users/{email}/roles` | — |
| `listar_roles` | users | `GET /api/admin/users/roles` | — |
| `consultar_auditoria` | users | `GET /api/admin/users/audit` | — |
| `contar_usuarios` | users | `GET /api/admin/users/count` | — |
| `consultar_dashboard` | reports | `GET /api/dashboard` | — |
| `exportar_pdf_dashboard` | reports | `GET /api/dashboard` + enlace `export/pdf` | — |
| `editar_deporte` / `eliminar_deporte` | sports | `PUT` / `DELETE /api/sports/{id}` | — |
| `registrar_adaptacion` | sports | `POST /api/sport-disabilities` | — |
| `listar_rutinas_publicadas` | sports | `GET /api/routines` | — |
| `listar_rutinas_entrenador` | sports | `GET /api/routines/trainer/{trainerId}` | — |
| `listar_deportes` | sports | `GET /api/sports/active` | — |

---

## Agentes por rol

`AGENT_ROLE` en `.env` (o al arrancar) filtra las tools:

| Rol | Tools |
| :--- | :--- |
| `usuario` | eventos, disponibles, calendario, inscribirse, deportes, perfil, inscripciones, adaptaciones |
| `entrenador` | eventos, calendario, perfil, rutinas, adaptaciones, discapacidades (CRUD/activar) |
| `organizador` | eventos (CRUD/cancelar), calendario, discapacidades, inscripciones, adaptaciones |
| `admin` | todas las de gestión: usuarios (bloquear/activar/eliminar/roles), PDF, eventos, discapacidades, deportes, rutinas y adaptaciones |
| `all` | todas las anteriores |

Instrucciones para Antigravity: `agents/usuario.md`, `entrenador.md`, `organizador.md`, `admin.md`.

---

## Estructura

```
ink-mcp-inklusport/
├── requirements.txt
├── .env / .env.example
├── README.md
├── agents/                 # prompts y config MCP para Antigravity
└── src/
    ├── server.py           # servidor MCP y registro de tools
    ├── ms_client.py        # GET HTTP a Users/Sports
    └── client_test.py      # cliente de prueba (como en clase)
```

---

## Configuración (`.env`)

```env
TRANSPORT=streamable-http
HOST=127.0.0.1
PORT=8000
AGENT_ROLE=all
USERS_SERVICE_URL=http://localhost:3002
SPORTS_SERVICE_URL=http://localhost:3003
REPORTS_SERVICE_URL=http://localhost:3006
```

`TRANSPORT`: `sse`, `streamable-http` o `stdio`.

---

## Inicio rápido (Windows)

### 1. Entorno e instalación

```powershell
cd ink-mcp-inklusport
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

### 2. Servidor MCP

Users y Sports no son obligatorios para arrancar. Sin ellos, las tools
devuelven `success=false` (microservicio no alcanzable).

```powershell
python src/server.py
```

Deberías ver `http://127.0.0.1:8000`. Health: [http://127.0.0.1:8000/](http://127.0.0.1:8000/).

### 3. Cliente de prueba (otra terminal)

```powershell
.\.venv\Scripts\Activate.ps1
python src/client_test.py
```

### 4. Un proceso por rol (opcional)

```powershell
# terminal 1
$env:AGENT_ROLE="usuario"; $env:PORT="8000"; python src/server.py
# terminal 2
$env:AGENT_ROLE="entrenador"; $env:PORT="8001"; python src/server.py
# terminal 3
$env:AGENT_ROLE="organizador"; $env:PORT="8002"; python src/server.py
# terminal 4
$env:AGENT_ROLE="admin"; $env:PORT="8003"; python src/server.py
```

Config Antigravity con los cuatro: `agents/antigravity.roles.mcp.json`.
Con un solo servidor (`AGENT_ROLE=all`): `agents/antigravity.mcp.json`.

---

## Antigravity

1. Instala **Antigravity IDE** (no el agente 2.0 “puro”).
2. Arranca el servidor con `TRANSPORT=streamable-http`.
3. Añade el MCP: `http://127.0.0.1:8000/mcp`.
4. Pega el prompt de `agents/<rol>.md` como instrucciones del agente.
5. Prueba: “¿Qué eventos hay en Inklusport?”. Si la respuesta incluye el campo
   `"via": "mcp"`, el agente está usando el servidor y no inventando datos.

---

## Microservicios

Desde la raíz del monorepo:

```powershell
docker compose up -d users-service sports-service reports-service
```

Puertos: Users `3002`, Sports `3003`, Reports `3006`. Las consultas de lectura
son `permitAll`. Las tools de escritura (crear/editar/cancelar/inscribir,
bloquear usuarios, roles, deportes) llaman los mismos endpoints y pueden
exigir JWT de admin/entrenador/organizador según el perfil de seguridad.