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`)

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

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).

python src/server.py

Deberías ver http://127.0.0.1:8000. Health: http://127.0.0.1:8000/.

3. Cliente de prueba (otra terminal)

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

4. Un proceso por rol (opcional)

# 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

Instala Antigravity IDE (no el agente 2.0 “puro”).
Arranca el servidor con TRANSPORT=streamable-http.
Añade el MCP: http://127.0.0.1:8000/mcp.
Pega el prompt de agents/<rol>.md como instrucciones del agente.
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:

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.