Update MCP_instructions.md

MCP_instructions.md

@@ -8,126 +8,137 @@ sdk_version: 5.29.0
 app_file: app.py
 pinned: false
 ---
+---
+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.
+Spotify MCP (Model Context Protocol) server, implemented with **FastAPI + FastMCP**.
+It authenticates a Spotify account via OAuth2 and exposes MCP tools to query profile data, search tracks, read library/recent playback, and manage playlists.
 
-## Despliegue objetivo (Hugging Face)
+## Target Deployment (Hugging Face)
 
-Este servidor corre en el Space:
+This server runs in the Space:
 
 - `pharmaia/Demo_MCP_Server_Spotify`
 - https://huggingface.co/spaces/pharmaia/Demo_MCP_Server_Spotify
 
-URL pública base:
+Public base URL:
 
 - `https://pharmaia-demo-mcp-server-spotify.hf.space`
 
-Endpoint MCP SSE público:
+Public MCP SSE endpoint:
 
 - `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.
+## General Architecture
+
+- `FastAPI` exposes HTTP endpoints for healthcheck and OAuth flow.
+- `FastMCP` registers MCP tools and publishes them over SSE.
+- `httpx` performs calls to Spotify Accounts API (tokens) and Spotify Web API (data/actions).
+- `spotify_tokens.json` (or a configurable path) stores tokens and expiration metadata.
+
+## Authentication Flow
+
+1. The client opens `/auth/login`.
+2. The server generates an anti-CSRF `state` and redirects to Spotify `/authorize`.
+3. Spotify redirects to `/auth/callback` with `code` + `state`.
+4. The server validates `state`, exchanges `code` for tokens, and saves them.
+5. MCP tools use the stored token; if expired, the server attempts automatic refresh.
+
+## HTTP Endpoints (Production)
+
+- `GET /`: basic service metadata and useful routes.
+- `GET /health`: simple status (`ok`).
+- `GET /auth/status`: local token status.
+- `GET /auth/reset`: removes local token (forces re-authentication).
+- `GET /auth/login?force=true`: starts OAuth (with consent dialog).
+- `GET /auth/callback`: Spotify OAuth callback.
+- `SSE /gradio_api/mcp/sse`: MCP SSE transport (mounted by FastMCP).
+
+## Main MCP Tools
+
+- `spotify_auth_status`: authentication status.
+- `spotify_get_auth_url`: direct OAuth authorization URL.
+- `spotify_get_my_profile`: current user profile.
+- `spotify_search_tracks`: track search.
+- `spotify_list_saved_tracks`: saved tracks.
+- `spotify_list_recently_played`: recently played tracks.
+- `spotify_get_top_tracks`: top tracks by time range.
+- `spotify_check_saved_tracks`: checks whether tracks are saved.
 - `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.
+- `spotify_list_my_playlists`: user playlists.
+- `spotify_create_playlist`: create playlist.
+- `spotify_add_items_to_playlist`: add items.
+- `spotify_update_playlist_details`: update metadata.
+- `spotify_replace_playlist_items`: replace content.
+- `spotify_delete_playlist`: delete (unfollow) playlist.
 
-## Variables de entorno (Hugging Face Spaces)
+## Environment Variables (Hugging Face Spaces)
 
-Configurar en **Settings > Variables and secrets** del Space:
+Configure in **Space Settings > Variables and secrets**:
 
 - `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`)
+- `SPOTIFY_SCOPES` (optional; the server appends required scopes)
+- `SPOTIFY_TOKEN_FILE` (optional; default `spotify_tokens.json`)
 - `MCP_PUBLIC_SSE_URL` = `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`
-- `PORT` (opcional; default `7860`)
+- `PORT` (optional; default `7860`)
 
-Importante: en Spotify Developer Dashboard, el Redirect URI debe coincidir exactamente con:
+Important: in Spotify Developer Dashboard, the Redirect URI must match exactly:
 
 - `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/callback`
 
-## Uso en producción (HF Space)
+## Production Usage (HF Space)
 
-1. Abrir login OAuth:
+1. Open OAuth login:
 
 - `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/login`
 
-2. Completar consentimiento de Spotify.
-3. Verificar estado:
+2. Complete Spotify consent.
+3. Check status:
 
 - `https://pharmaia-demo-mcp-server-spotify.hf.space/auth/status`
 
-4. Conectar cliente MCP al SSE público:
+4. Connect MCP client to the public SSE endpoint:
 
 - `https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse`
 
-## Ejecución local (opcional)
+## Local Run (Optional)
 
-1. Instalar dependencias:
+1. Install dependencies:
 
 ```bash
 pip install -r requirements.txt
 ```
 
-2. Ejecutar servidor:
+2. Start the server:
 
 ```bash
 python app.py
 ```
 
-3. Abrir en navegador:
+3. Open in browser:
 
 - `http://localhost:7860/auth/login`
 
-4. Conectar cliente MCP al SSE local:
+4. Connect MCP client to local SSE endpoint:
 
 - `http://localhost:7860/gradio_api/mcp/sse`
 
-## Notas de diseño
+## Design Notes
+
+- The server keeps OAuth state in memory with TTL to prevent callback replay.
+- Scopes are validated for sensitive playlist operations.
+- Spotify IDs/URIs/URLs are normalized before API calls.
+- Spotify responses are transformed into compact payloads for MCP tool consumption.
 
-- 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.