# Audius MCP Server (Code Mode)

A Code Mode MCP server that gives LLMs full access to the Audius music platform and Open Audio Protocol. Instead of 100+ individual tools, it uses two meta-tools — **search** and **execute** — to compress the entire Audius API into ~1,000 tokens of context.

Built with Effect-TS. Runs a QuickJS WASM sandbox for secure code execution.

## How It Works

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

The LLM writes JavaScript that runs in an isolated sandbox with an authenticated `audius.request()` client. No API keys in the prompt, no tool explosion, no round-trip overhead.

## Tools

| Tool | What it does |
|------|-------------|
| **search** | Discover API endpoints by tag, path, method, or keyword |
| **execute** | Run JavaScript against the Audius API in a QuickJS sandbox |
| **play** | Open a track in the Audius desktop app or browser |
| **subgraph** | Query on-chain protocol data (staking, governance, nodes) via The Graph |

## Quick Start

```bash
# 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
```

## Getting API Keys

### Audius API Key (required)

1. Go to [audius.co/settings](https://audius.co/settings) and sign in (or create an account)
2. Scroll to **Developer Apps** and create a new app
3. Copy the **API Key** — this goes in your `.env` as `AUDIUS_API_KEY`
4. Optionally copy the **API Secret** if you plan to do write operations (uploads, favorites)

Alternatively, get credentials at [api.audius.co/plans](https://api.audius.co/plans).

### The Graph API Key (optional, for subgraph tool)

The subgraph tool queries on-chain protocol data (staking, governance, nodes). It requires a Graph API key:

1. Go to [thegraph.com/studio](https://thegraph.com/studio) and sign in
2. Create an API key ([video tutorial](https://www.youtube.com/watch?v=UrfIpm-Vlgs))
3. Add it to your `.env` as `GRAPH_API_KEY`

Without this key, the subgraph tool will return an auth error. All other tools work fine without it.

## Connect to Claude

### Claude Code

Add to your project's `.mcp.json`:

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

### Claude Desktop

Add to `claude_mcp_config.json`:

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

## Example Conversations

**"What's trending on Audius right now?"**
```js
// LLM calls search({ tag: "tracks" }), then:
return await audius.request('GET', '/tracks/trending', { query: { limit: 5 } })
```

**"Find deadmau5 and show me his top tracks"**
```js
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 }))
```

**"How much $AUDIO is staked in the protocol?"**
```graphql
{ audiusNetworks(first: 1) { totalTokensStaked totalTokensDelegated totalSupply } }
```

## Architecture

```
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
```

Every component is an Effect service (`Context.Tag`) composed via `Layer`. The sandbox uses `QuickJSDeferredPromise` to support unlimited chained `await` calls.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `AUDIUS_API_KEY` | Yes | API key from audius.co/settings |
| `PORT` | No | HTTP server port (default: 3000) |
| `GRAPH_API_KEY` | No | The Graph API key for subgraph queries |

## Development

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

## Security

- **Sandbox isolation**: LLM-generated code runs in QuickJS WASM — no filesystem, no network, no env vars
- **No raw fetch**: Only `audius.request()` is available, hardcoded to `api.audius.co`
- **SSRF protection**: API paths must start with `/` and cannot contain `@`
- **Memory cap**: 64MB per execution
- **Timeout**: 30s default, configurable per call
- **Fresh context**: No state leaks between executions

## Protocol

- **MCP version**: 2025-11-25
- **Transport**: Streamable HTTP at `POST /mcp`
- **Sessions**: `MCP-Session-Id` header, in-memory (stateless-ready)

## Open Audio Protocol

This server is built on the [Open Audio Protocol](https://openaudio.org) — the decentralized global music database. Audius is one application layer on top of OAP. The subgraph tool provides direct access to on-chain protocol data.

## License

MIT