🎵 Servidor MCP de Discogs

Un potente servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con tu colección personal de música de Discogs. Construido sobre Cloudflare Workers utilizando el Cloudflare Agents SDK oficial y @modelcontextprotocol/sdk.

✨ Características

• 🔐 Autenticación OAuth segura: Conecta tu cuenta de Discogs de forma segura

• 🧠 Mapeo inteligente de estados de ánimo: Traduce emociones en música ("tranquilo", "enérgico", "vibraciones de domingo por la noche")

• 🔍 Inteligencia de búsqueda avanzada: Estrategia de búsqueda múltiple con lógica OR y puntuación de relevancia

• 📊 Analíticas de colección: Estadísticas completas e información sobre tu música

• 🎯 Recomendaciones conscientes del contexto: Sugerencias inteligentes basadas en estado de ánimo, género y similitud

• ⚡ Computación en el borde: Respuestas globales de baja latencia mediante Cloudflare Workers

• 🗂️ Caché inteligente: Caché basada en KV para un rendimiento óptimo

• 🔄 Sincronización de colección en segundo plano: Un trabajo cada 6 horas mantiene una instantánea de tu colección en KV, para que las búsquedas respondan desde la instantánea en lugar de paginar a través de Discogs en cada llamada

Related MCP server: navigravity

⚠️ Esto no es un servicio compartido

discogs-mcp.com es la instancia privada del mantenedor. Está bloqueada para una sola cuenta de Discogs y devolverá un 403 para cualquier otra persona.

¿Por qué? El límite de tasa de la API de Discogs (60 solicitudes por minuto, contadas por IP de origen) es demasiado ajustado para compartirlo entre usuarios. Una sola consulta activa de colección de un usuario puede saturarlo. En lugar de ejecutar un servicio multiinquilino defectuoso, cada usuario despliega su propio Worker con sus propias credenciales de API de Discogs.

La buena noticia: desplegar tu propia copia es sencillo, se ejecuta en el nivel gratuito de Cloudflare Workers y toma unos 10 minutos. Consulta Autoalojamiento más abajo.

🚀 Autoalojamiento

La ruta más rápida es el botón Desplegar en Cloudflare de arriba. Clona este repositorio en tu cuenta de GitHub, aprovisiona los espacios de nombres KV y el Objeto Duradero en tu cuenta de Cloudflare, te pide los tres secretos y configura Workers Builds para que futuros envíos a tu bifurcación se redesplieguen automáticamente.

1. Registra una aplicación de desarrollador de Discogs

Ve a discogs.com/settings/developers → Crear una aplicación. Ponle cualquier nombre; la URL de devolución de llamada puede ser un marcador de posición por ahora (volverás y la configurarás después de desplegar el Worker). Guarda la Clave de Consumidor y el Secreto de Consumidor — los pegarás a continuación.

2. Haz clic en el botón

Cuando se te solicite, pega:

Después de que el despliegue se complete, Cloudflare muestra la URL de tu Worker — algo como https://discogs-mcp.<tu-subdominio>.workers.dev. El endpoint MCP es /mcp.

3. Actualiza la URL de devolución de llamada de tu aplicación de Discogs

Vuelve a tu aplicación de Discogs y establece la URL de devolución de llamada a:

https://discogs-mcp.<your-subdomain>.workers.dev/discogs-callback

4. (Opcional pero recomendado) Bloquea tu instancia a tu propio usuario de Discogs

Por defecto, cualquiera que descubra la URL de tu Worker puede autenticarse y consumir tu presupuesto de límite de tasa de Discogs. Para restringirlo, edita wrangler.toml en tu bifurcación y establece ALLOWED_DISCOGS_USER_ID bajo [vars]:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

# Or a comma-separated list for multiple users
ALLOWED_DISCOGS_USER_ID = "123456,789012,345678"

Encuentra tu ID numérico visitando https://api.discogs.com/users/<tu-nombre-de-usuario> y mirando el campo id. Sube el cambio — Workers Builds se redespliega automáticamente.

5. Conecta tu cliente MCP

Reemplaza https://tu-worker.workers.dev abajo con tu propia URL.

Claude Desktop — Configuración → Integraciones → Añadir Integración → https://tu-worker.workers.dev/mcp

Claude Code:

claude mcp add --transport http discogs https://your-worker.workers.dev/mcp

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "discogs": {
      "serverUrl": "https://your-worker.workers.dev/mcp"
    }
  }
}

Continue.dev / Zed / Genérico:

{
  "mcpServers": {
    "discogs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev/mcp"]
    }
  }
}

Inspector MCP (pruebas):

npx @modelcontextprotocol/inspector https://your-worker.workers.dev/mcp

Despliegue manual (alternativa)

Si prefieres saltarte el botón — por ejemplo, quieres un clon completamente local o estás en una cuenta de Cloudflare donde el botón no funciona:

git clone https://github.com/rianvdm/discogs-mcp.git
cd discogs-mcp
npm install

# Create the two KV namespaces and copy the returned IDs into wrangler.toml
# (replace the empty `id = ""` values under the top-level [[kv_namespaces]] blocks)
wrangler kv namespace create MCP_SESSIONS
wrangler kv namespace create OAUTH_KV

# Set the three secrets
wrangler secret put DISCOGS_CONSUMER_KEY
wrangler secret put DISCOGS_CONSUMER_SECRET
wrangler secret put JWT_SECRET

# Deploy
npm run deploy

Luego sigue los pasos 3–5 de arriba (URL de devolución de llamada, lista blanca opcional, conecta tu cliente MCP).

Opcional: enrutar llamadas a Discogs a través de tu propia IP

Discogs limita por IP de origen, y las solicitudes salientes de un Worker salen de las IPs de salida compartidas de Cloudflare, por lo que otros Workers que hablen con Discogs desde la misma ubicación consumen tus 60 solicitudes por minuto. Puedes ver esto cuando una primera solicitud después de horas de inactividad ya reporta un X-Discogs-Ratelimit-Remaining bajo. Si te afecta, apunta el Worker a un relé que tú ejecutes: un Cloudflare Tunnel a cualquier máquina siempre encendida (un Mac en casa, un VPS pequeño) con un proxy inverso local que reenvíe a https://api.discogs.com y establezca tanto Host como X-Forwarded-Host a api.discogs.com (cloudflared solo no puede, sobrescribe X-Forwarded-Host). Pon una aplicación de Cloudflare Access con una política de token de servicio delante del nombre de host del túnel, luego:

# wrangler.toml: DISCOGS_RELAY_ORIGIN = "https://relay.example.com"
wrangler secret put RELAY_ACCESS_CLIENT_ID
wrangler secret put RELAY_ACCESS_CLIENT_SECRET

Deja DISCOGS_RELAY_ORIGIN vacío para llamar a Discogs directamente (el valor predeterminado). Si el relé es inalcanzable, el Worker recurre a llamadas directas para esa solicitud y lo registra, por lo que una máquina apagada degrada al comportamiento de IP compartida en lugar de una interrupción. Implementación y justificación: src/rate-limiter/relay.ts.

🔐 Autenticación

Este servidor utiliza MCP OAuth 2.1 con Discogs como proveedor de identidad. Cuando te conectas por primera vez:

1. Tu cliente MCP abre automáticamente una ventana del navegador

2. Autoriza la aplicación en Discogs

3. Eres redirigido de vuelta y autenticado — sin necesidad de copiar y pegar

4. Tu sesión persiste durante 7 días

🛠️ Herramientas disponibles

🔓 Herramientas públicas (sin autenticación requerida)

🔐 Herramientas autenticadas (requieren inicio de sesión)

Búsqueda y descubrimiento

Gestión de colección

Lista de deseos

Carpetas

Campos personalizados

Diagnóstico

📚 Recursos MCP

Accede a datos de Discogs a través de URIs de recursos MCP estandarizados:

discogs://collection             # Complete collection (JSON)
discogs://release/{id}           # Specific release details
discogs://search?q={query}       # Search results

💬 Prompts MCP

🏗️ Desarrollo local

# Dev secrets live in .dev.vars (gitignored); the same Discogs app is fine for dev
cp .dev.vars.example .dev.vars   # then fill in DISCOGS_CONSUMER_KEY, DISCOGS_CONSUMER_SECRET, JWT_SECRET

# Run the Worker locally
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8787/mcp

El bloque [vars] predeterminado en wrangler.toml deja ALLOWED_DISCOGS_USER_ID vacío, por lo que el desarrollo local está abierto a cualquier cuenta de Discogs — conveniente para pruebas.

🧪 Pruebas

npm test              # vitest in watch mode (runs in workerd via @cloudflare/vitest-pool-workers)
npx vitest run        # one pass, then exit
npm run lint          # ESLint; CI runs lint, test, and a dry-run build

Diagnóstico

ping y server_info informan cómo sale el tráfico de Discogs (directo, o a través del relé descrito anteriormente) y si el relé ha recurrido a llamadas directas. Para el estado en vivo del limitador de tasa — presupuesto restante, profundidad de cola, estado del interruptor automático, fallos del relé — establece un secreto DEBUG_TOKEN y llama a GET /debug/budget?token=<DEBUG_TOKEN>; sin el secreto el endpoint devuelve 404.

🤝 Contribuciones

1. Haz un fork del repositorio

2. Crea tu rama de características (git checkout -b feature/caracteristica-increible)

3. Haz commit de tus cambios (git commit -m 'Añadir característica increíble')

4. Sube a la rama (git push origin feature/caracteristica-increible)

5. Abre una Solicitud de Extracción

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

• Discogs para la API de la base de datos musical

• Model Context Protocol para el estándar

• Cloudflare Workers para la plataforma