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_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 de eventos, discapacidades, usuarios, 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

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

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:

docker compose up -d users-service sports-service

Puertos: Users 3002, Sports 3003. Las consultas de lectura son permitAll. Las tools de escritura (crear/editar/cancelar/inscribir) llaman los mismos endpoints del API de Sports y pueden exigir JWT según el perfil de seguridad.