Audius MCP Dev

Audius MCP Server Development

This skill guides development of the audius-mcp-atris Code Mode MCP server — an Effect-TS server that gives LLMs access to the Audius music platform and Open Audio Protocol through two tools: search (API discovery) and execute (sandboxed code execution).

Architecture at a Glance

LLM ──POST /mcp──► McpServerTransport ──► McpSerialization ──► McpServer
                                              (JSON-RPC ↔ Effect)      │
                                                              ┌────────┴────────┐
                                                         SearchTool        ExecuteTool
                                                              │                │
                                                         SpecIndex         Sandbox
                                                              │           ┌────┴────┐
                                                         SpecLoader  AudiusClient  TypeGenerator
                                                                         │
                                                                     AppConfig

Every box is an Effect service (Context.Tag) composed via Layer. The entry point (src/index.ts) wires all layers together and starts the HTTP server.

Effect-TS Service Pattern

This is the core pattern used throughout the codebase. Understanding it is essential for adding any new component.

// 1. Define the service interface with Context.Tag
export class MyService extends Context.Tag("MyService")<
  MyService,
  {
    readonly doSomething: (input: string) => Effect.Effect<Result, Error>
  }
>() {}

// 2. Implement via Layer.effect (can depend on other services)
export const MyServiceLive: Layer.Layer<MyService, never, Dep1 | Dep2> = Layer.effect(
  MyService,
  Effect.gen(function* () {
    const dep1 = yield* Dep1
    const dep2 = yield* Dep2

    return {
      doSomething: (input) => Effect.gen(function* () {
        // use dep1, dep2...
        return result
      })
    }
  })
)

// 3. Wire in index.ts
const MyServiceLayer = MyServiceLive.pipe(
  Layer.provide(Layer.merge(Dep1Layer, Dep2Layer))
)

Key rules:

• Services are accessed via yield* ServiceTag inside Effect.gen
• Layer composition happens in index.ts — each layer explicitly provides its dependencies
• Tool handlers return Effect.Effect<T, E, R> where R lists required services
• Errors in tool handlers go in content with isError: true (tool-level), not protocol-level
• Layer.mergeAll(...) provides the final AppLayer to the main program

File Map

How to Add a New Tool

1. Create src/tools/MyTool.ts following the pattern in SearchTool.ts:

   • Export a Tool.make({...}) definition with name, description, inputSchema, annotations
   • Export a handler function returning Effect.Effect<typeof CallToolResult.Type, never, RequiredServices>
   • Return results via CallToolResult.make({ content: [TextContent.make({...})] })
   • Errors: set isError: true on CallToolResult, put error message in content text

2. Register in src/mcp/McpServer.ts:

   • Import the tool definition and handler
   • Add to the tools/list response array
   • Add a case in handleToolCall switch

3. Wire dependencies in src/index.ts if the new tool needs new services

How to Add a New Effect Service

1. Create the service file (e.g., src/api/NewService.ts):

   • Define Context.Tag with the interface
   • Implement Layer.effect with dependencies in the type signature

2. Wire in src/index.ts:

   • Create the layer with .pipe(Layer.provide(...)) for dependencies
   • Add to AppLayer via Layer.mergeAll

3. Use in handlers via yield* NewService

The Sandbox

The QuickJS WASM sandbox (src/sandbox/Sandbox.ts) is the execute tool's runtime:

• audius.request(method, path, options?) — host function bridged to AudiusClient
• console.log() — captured, returned in output
• Memory limit: 64MB
• Timeout: configurable, default 30s
• Isolation: fresh QuickJS context per execution, no state leakage
• User code is injected via __userCode__ global string (prevents template literal injection)
• Results are auto-parsed from JSON strings

The sandbox differs from the Cloudflare reference (which uses V8 Worker Loader isolates). QuickJS runs in WASM so it works in any Node.js environment without Cloudflare Workers infrastructure.

The Search Tool

The search tool (src/tools/SearchTool.ts) takes structured filters (query, tag, path, method) rather than executable code (unlike Cloudflare's approach where the LLM writes JavaScript to search the spec). This is simpler and sufficient for the Audius API size (~100 endpoints vs Cloudflare's ~2500).

The SpecIndex service builds keyword indexes at startup and supports filtering by tag, path pattern, HTTP method, and free-text search across descriptions.

Cloudflare Reference

The cloudflare-serverside-mcp-ref/ directory contains Cloudflare's production Code Mode MCP server as a reference implementation. Key architectural differences to be aware of:

Read cloudflare-serverside-mcp-ref/src/server.ts for the tool registration pattern, executor.ts for sandbox execution, and spec-processor.ts for OpenAPI processing.

Common Development Tasks

For detailed guidance on specific tasks, read the reference files:

• references/extending-tools.md — Adding tools, modifying tool descriptions, changing input schemas, adding tool annotations
• references/transport-and-protocol.md — MCP protocol compliance, session management, JSON-RPC handling, adding new protocol methods
• references/api-integration.md — Working with SpecLoader, SpecIndex, AudiusClient, adding new API providers, extending to Open Audio Protocol

Build & Test

pnpm build    # TypeScript → JavaScript
pnpm start    # Run compiled server (HTTP on PORT, default 3000)
pnpm dev      # Build + run
pnpm test     # Currently runs build as test

Environment: AUDIUS_API_KEY for API access, PORT for server port.

Important Constraints

• No @audius/sdk — direct REST API calls via AudiusClient.request(method, path, options)
• MCP protocol version: 2025-11-25
• Tool errors are tool-level (in content with isError: true), not protocol-level JSON-RPC errors
• The spec URL is hardcoded: https://api.audius.co/v1/swagger.yaml
• SSRF protection: paths must start with / and cannot contain @