Atris MCP for Audius

Audius MCP Server (Code Mode)

Un servidor MCP en modo Code Mode que da a los LLMs acceso completo a la plataforma musical de Audius y al Protocolo de Audio Abierto. En lugar de más de 100 herramientas individuales, utiliza dos meta-herramientas — search y execute — para comprimir toda la API de Audius en ~1,000 tokens de contexto.

Construido con Effect-TS. Ejecuta un sandbox QuickJS WASM para la ejecución segura de código.

Cómo Funciona

LLM ──► search("trending tracks")     → discovers GET /tracks/trending
    ──► execute("audius.request(...)") → runs code in sandbox, returns results

El LLM escribe JavaScript que se ejecuta en un sandbox aislado con un cliente audius.request() autenticado. Sin claves API en el prompt, sin explosión de herramientas, sin sobrecarga de ida y vuelta.

Herramientas

Herramienta	Qué hace
search	Descubre endpoints de API por etiqueta, ruta, método o palabra clave
execute	Ejecuta JavaScript contra la API de Audius en un sandbox QuickJS
play	Abre una pista en la aplicación de escritorio o navegador de Audius
subgraph	Consulta datos del protocolo on-chain (staking, gobernanza, nodos) a través de The Graph

Inicio Rápido

# Install
git clone https://github.com/glassBead-tc/audius-mcp-atris.git
cd audius-mcp-atris
pnpm install

# Configure
echo 'AUDIUS_API_KEY=your_key_here' > .env

# Build & run
pnpm dev

Obtención de Claves API

Clave API de Audius (requerida)

1. Ve a audius.co/settings e inicia sesión (o crea una cuenta)
2. Desplázate hasta Developer Apps y crea una nueva aplicación
3. Copia la API Key — esto va en tu .env como AUDIUS_API_KEY
4. Opcionalmente copia el API Secret si planeas hacer operaciones de escritura (subidas, favoritos)

Alternativamente, obtén credenciales en api.audius.co/plans.

Clave API de The Graph (opcional, para la herramienta subgraph)

La herramienta subgraph consulta datos del protocolo on-chain (staking, gobernanza, nodos). Requiere una clave API de Graph:

1. Ve a thegraph.com/studio e inicia sesión
2. Crea una clave API (tutorial en video)
3. Añádela a tu .env como GRAPH_API_KEY

Sin esta clave, la herramienta subgraph devolverá un error de autenticación. Todas las demás herramientas funcionan bien sin ella.

Conectar con Claude

Claude Code

Añade a .mcp.json de tu proyecto:

{
  "mcpServers": {
    "audius-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Desktop

Añade a claude_mcp_config.json:

{
  "mcpServers": {
    "audius": {
      "command": "node",
      "args": ["/path/to/audius-mcp-atris/dist/index.js"],
      "env": {
        "AUDIUS_API_KEY": "your_key_here"
      }
    }
  }
}

Ejemplos de Conversaciones

"¿Qué está de moda en Audius ahora mismo?"

// LLM calls search({ tag: "tracks" }), then:
return await audius.request('GET', '/tracks/trending', { query: { limit: 5 } })

"Encuentra a deadmau5 y muéstrame sus mejores pistas"

const users = await audius.request('GET', '/users/search', { query: { query: 'deadmau5' } })
const userId = users.data[0].id
const tracks = await audius.request('GET', '/users/' + userId + '/tracks', { query: { sort: 'plays' } })
return tracks.data.map(t => ({ title: t.title, plays: t.play_count }))

"¿Cuánto $AUDIO está en staking en el protocolo?"

{ audiusNetworks(first: 1) { totalTokensStaked totalTokensDelegated totalSupply } }

Arquitectura

src/
├── index.ts                    # Entry point — Effect layers, HTTP server
├── AppConfig.ts                # Env var config (AUDIUS_API_KEY, PORT)
├── mcp/
│   ├── McpSchema.ts            # MCP 2025-11-25 protocol (Effect Schema)
│   ├── McpSerialization.ts     # JSON-RPC ↔ Effect RPC bridge
│   ├── McpServer.ts            # Request dispatch (initialize, tools/*)
│   └── McpServerTransport.ts   # Streamable HTTP on /mcp
├── api/
│   ├── SpecLoader.ts           # Fetch + resolve Audius swagger.yaml
│   ├── SpecIndex.ts            # Searchable index over parsed spec
│   └── AudiusClient.ts         # Authenticated HTTP client
├── tools/
│   ├── SearchTool.ts           # search tool
│   ├── ExecuteTool.ts          # execute tool
│   ├── PlayTool.ts             # play tool
│   └── SubgraphTool.ts         # subgraph tool
└── sandbox/
    ├── Sandbox.ts              # QuickJS WASM sandbox
    └── TypeGenerator.ts        # TS declarations from spec

Cada componente es un servicio de Effect (Context.Tag) compuesto mediante Layer. El sandbox utiliza QuickJSDeferredPromise para soportar llamadas encadenadas ilimitadas de await.

Variables de Entorno

Variable	Requerida	Descripción
AUDIUS_API_KEY	Sí	Clave API de audius.co/settings
PORT	No	Puerto del servidor HTTP (predeterminado: 3000)
GRAPH_API_KEY	No	Clave API de The Graph para consultas de subgraph

Desarrollo

pnpm build    # Compile TypeScript
pnpm start    # Run compiled server
pnpm dev      # Build + run
pnpm test     # Run tests

Seguridad

• Aislamiento del sandbox: El código generado por LLM se ejecuta en QuickJS WASM — sin sistema de archivos, sin red, sin variables de entorno
• Sin fetch crudo: Solo audius.request() está disponible, codificado a api.audius.co
• Protección SSRF: Las rutas de API deben comenzar con / y no pueden contener @
• Límite de memoria: 64MB por ejecución
• Tiempo de espera: 30s por defecto, configurable por llamada
• Contexto fresco: Sin fugas de estado entre ejecuciones

Protocolo

• Versión de MCP: 2025-11-25
• Transporte: HTTP transmisible en POST /mcp
• Sesiones: cabecera MCP-Session-Id, en memoria (listo para sin estado)

Open Audio Protocol

Este servidor está construido sobre el Open Audio Protocol — la base de datos musical global descentralizada. Audius es una capa de aplicación sobre OAP. La herramienta subgraph proporciona acceso directo a los datos del protocolo on-chain.

Licencia

MIT