Atris MCP for Audius

Servidor MCP Audius (Modo Código)

Um servidor MCP em Modo Código que dá aos LLMs acesso completo à plataforma de música Audius e ao Open Audio Protocol. Em vez de mais de 100 ferramentas individuais, ele usa duas meta-ferramentas — search e execute — para compactar toda a API Audius em cerca de 1.000 tokens de contexto.

Construído com Effect-TS. Executa um sandbox QuickJS WASM para execução segura de código.

Como Funciona

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

O LLM escreve JavaScript que roda em um sandbox isolado com um cliente audius.request() autenticado. Sem chaves de API no prompt, sem explosão de ferramentas, sem sobrecarga de ida e volta.

Ferramentas

Ferramenta	O que faz
search	Descobre endpoints da API por tag, caminho, método ou palavra-chave
execute	Executa JavaScript contra a API Audius em um sandbox QuickJS
play	Abre uma faixa no aplicativo de desktop Audius ou no navegador
subgraph	Consulta dados on-chain do protocolo (staking, governança, nós) via The Graph

Início 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

Obtendo Chaves de API

Chave de API Audius (obrigatória)

1. Acesse audius.co/settings e faça login (ou crie uma conta)
2. Role até Developer Apps e crie um novo aplicativo
3. Copie a API Key — ela vai no seu .env como AUDIUS_API_KEY
4. Opcionalmente, copie o API Secret se você planeja fazer operações de escrita (uploads, favoritos)

Alternativamente, obtenha credenciais em api.audius.co/plans.

Chave de API The Graph (opcional, para a ferramenta subgraph)

A ferramenta subgraph consulta dados on-chain do protocolo (staking, governança, nós). Ela requer uma chave de API Graph:

1. Acesse thegraph.com/studio e faça login
2. Crie uma chave de API (tutorial em vídeo)
3. Adicione-a ao seu .env como GRAPH_API_KEY

Sem essa chave, a ferramenta subgraph retornará um erro de autenticação. Todas as outras ferramentas funcionam normalmente sem ela.

Conectar ao Claude

Claude Code

Adicione ao .mcp.json do seu projeto:

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

Claude Desktop

Adicione ao claude_mcp_config.json:

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

Exemplos de Conversas

"O que está em alta no Audius agora?"

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

"Encontre deadmau5 e mostre as principais faixas dele"

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 }))

"Quanto $AUDIO está em staking no protocolo?"

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

Arquitetura

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 é um serviço Effect (Context.Tag) composto via Layer. O sandbox usa QuickJSDeferredPromise para suportar chamadas await encadeadas ilimitadas.

Variáveis de Ambiente

Variável	Obrigatória	Descrição
AUDIUS_API_KEY	Sim	Chave de API de audius.co/settings
PORT	Não	Porta do servidor HTTP (padrão: 3000)
GRAPH_API_KEY	Não	Chave de API The Graph para consultas subgraph

Desenvolvimento

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

Segurança

• Isolamento do sandbox: Código gerado por LLM roda em QuickJS WASM — sem sistema de arquivos, sem rede, sem variáveis de ambiente
• Sem fetch bruto: Apenas audius.request() está disponível, fixado em api.audius.co
• Proteção SSRF: Caminhos da API devem começar com / e não podem conter @
• Limite de memória: 64MB por execução
• Timeout: 30s padrão, configurável por chamada
• Contexto fresco: Sem vazamento de estado entre execuções

Protocolo

• Versão MCP: 2025-11-25
• Transporte: HTTP Streamable em POST /mcp
• Sessões: Cabeçalho MCP-Session-Id, em memória (pronto para stateless)

Open Audio Protocol

Este servidor é construído sobre o Open Audio Protocol — o banco de dados musical global descentralizado. Audius é uma camada de aplicação sobre o OAP. A ferramenta subgraph fornece acesso direto aos dados on-chain do protocolo.

Licença

MIT