Upload MCP_instructions.md

MCP_instructions.md

@@ -0,0 +1,133 @@
+---
+title: Demo MIT - MCP Server
+emoji: 💻
+colorFrom: green
+colorTo: gray
+sdk: gradio
+sdk_version: 5.29.0
+app_file: app.py
+pinned: false
+---
+
+# Spotify MCP Server
+
+Servidor MCP (Model Context Protocol) para Spotify, implementado con **FastAPI + FastMCP**.
+Permite autenticar una cuenta de Spotify vía OAuth2 y exponer tools MCP para consultar perfil, buscar tracks, leer biblioteca/reproducción reciente y gestionar playlists.
+
+## Despliegue objetivo (Hugging Face)
+
+Este servidor corre en el Space:
+
+- `pharmaia/Demo_MCP_Server_Spotify`
+- https://huggingface.co/spaces/pharmaia/Demo_MCP_Server_Spotify
+
+URL pública base:
+
+- `https://pharmaia-demo-mcp-server-spotify.hf.space`
+
+Endpoint MCP SSE público:
+
+- `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`
+
+## Arquitectura general
+
+- `FastAPI` expone endpoints HTTP para healthcheck y flujo OAuth.
+- `FastMCP` registra tools MCP y las publica por SSE.
+- `httpx` ejecuta llamadas a Spotify Accounts API (tokens) y Spotify Web API (datos/acciones).
+- `spotify_tokens.json` (o ruta configurable) guarda tokens y metadatos de expiración.
+
+## Flujo de autenticación
+
+1. Cliente abre `/auth/login`.
+2. El servidor genera `state` anti-CSRF y redirige a Spotify `/authorize`.
+3. Spotify redirige a `/auth/callback` con `code` + `state`.
+4. El servidor valida `state`, intercambia `code` por tokens y guarda el resultado.
+5. Las tools MCP usan el token guardado; si expira, el servidor intenta refresh automático.
+
+## Endpoints HTTP (en producción)
+
+- `GET /`: metadata básica del servicio y rutas útiles.
+- `GET /health`: estado simple (`ok`).
+- `GET /auth/status`: estado del token local.
+- `GET /auth/reset`: borra token local (forzar nueva autenticación).
+- `GET /auth/login?force=true`: inicia OAuth (con diálogo de consentimiento).
+- `GET /auth/callback`: callback OAuth de Spotify.
+- `SSE /gradio_api/mcp/sse`: transporte MCP SSE (montado por FastMCP).
+
+## Tools MCP principales
+
+- `spotify_auth_status`: estado de autenticación.
+- `spotify_get_auth_url`: URL directa de autorización OAuth.
+- `spotify_get_my_profile`: perfil del usuario actual.
+- `spotify_search_tracks`: búsqueda de canciones.
+- `spotify_list_saved_tracks`: tracks guardados.
+- `spotify_list_recently_played`: reproducción reciente.
+- `spotify_get_top_tracks`: top tracks por rango temporal.
+- `spotify_check_saved_tracks`: valida si tracks están guardados.
+- `spotify_save_tracks` / `spotify_remove_saved_tracks` / `spotify_set_tracks_saved`.
+- `spotify_list_my_playlists`: listas del usuario.
+- `spotify_create_playlist`: crear playlist.
+- `spotify_add_items_to_playlist`: agregar ítems.
+- `spotify_update_playlist_details`: actualizar metadata.
+- `spotify_replace_playlist_items`: reemplazar contenido.
+- `spotify_delete_playlist`: eliminar (unfollow) playlist.
+
+## Variables de entorno (Hugging Face Spaces)
+
+Configurar en **Settings > Variables and secrets** del Space:
+
+- `SPOTIFY_CLIENT_ID`
+- `SPOTIFY_CLIENT_SECRET`
+- `SPOTIFY_REDIRECT_URI` = `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/callback`
+- `SPOTIFY_SCOPES` (opcional; el servidor completa scopes requeridos)
+- `SPOTIFY_TOKEN_FILE` (opcional; default `spotify_tokens.json`)
+- `MCP_PUBLIC_SSE_URL` = `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`
+- `PORT` (opcional; default `7860`)
+
+Importante: en Spotify Developer Dashboard, el Redirect URI debe coincidir exactamente con:
+
+- `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/callback`
+
+## Uso en producción (HF Space)
+
+1. Abrir login OAuth:
+
+- `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/login`
+
+2. Completar consentimiento de Spotify.
+3. Verificar estado:
+
+- `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/status`
+
+4. Conectar cliente MCP al SSE público:
+
+- `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`
+
+## Ejecución local (opcional)
+
+1. Instalar dependencias:
+
+```bash
+pip install -r requirements.txt
+```
+
+2. Ejecutar servidor:
+
+```bash
+python app.py
+```
+
+3. Abrir en navegador:
+
+- `http://localhost:7860/auth/login`
+
+4. Conectar cliente MCP al SSE local:
+
+- `http://localhost:7860/gradio_api/mcp/sse`
+
+## Notas de diseño
+
+- El servidor guarda estado OAuth en memoria con TTL para prevenir replay de callback.
+- Se validan scopes para operaciones sensibles de playlists.
+- IDs/URIs/URLs de Spotify se normalizan antes de invocar la API.
+- Respuestas de Spotify se transforman a payloads compactos para consumo en tools MCP.