Sonic MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with the Sonic API for managing events, venues, songs, and users.

Overview

This MCP server provides a comprehensive interface for AI agents to:

• Manage Events: Create, read, update, delete events with full CRUD operations

• Manage Venues: Handle venue information including addresses and capacity

• Handle Songs: Music data management with Spotify integration

• User Management: Profile operations and authentication

• Search Integration: Spotify music search and Google Maps places

• Real-time Interaction: Direct API communication with proper authentication

Related MCP server: Spotify MCP Server

Features

🎪 Event Management

• Create events with dates, venues, and attendee limits

• Search and filter events by name, owner, or description

• Include related data (venues, users, songs) in responses

• Support for public/private events

🏢 Venue Management

• Create venues with detailed address information

• Manage venue capacity and descriptions

• Link venues to events

• Search venues by location or name

🎵 Music Integration

• Add songs to your library

• Search Spotify for tracks

• Link songs to events

• Manage music metadata (artist, album, genre)

👥 User Operations

• View user profiles

• Update account information

• Admin functions for user management

• Authentication and authorization

🗺️ Location Services

• Search places using Google Maps

• Get detailed place information

• Address autocomplete functionality

Installation & Setup

Prerequisites

• Node.js 18+

• TypeScript

• Access to Sonic API with valid JWT token

Quick Start

1. Install dependencies:

   npm install

2. Build the project:

   npm run build

3. Set your authentication token:

   # Windows (PowerShell)
   $env:SONIC_API_TOKEN = "your-jwt-token-here"
   
   # macOS/Linux
   export SONIC_API_TOKEN="your-jwt-token-here"

4. Run the server:

   npm start

Configuration

Environment Variables

• SONIC_API_TOKEN: Your JWT authentication token (required)

• SONIC_API_BASE_URL: API base URL (default: https://localhost:5001/api)

Getting Your JWT Token

curl -X POST https://localhost:5001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com", 
    "password": "your-password"
  }'

AI Client Integration (Claude Desktop)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "sonic-api": {
      "command": "node",
      "args": ["C:\\path\\to\\sonic-mcp-server\\build\\index.js"],
      "env": {
        "SONIC_API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Available Tools

Event Tools

• get_events - List events with filtering and pagination

• get_event - Get specific event details

• create_event - Create new event

• update_event - Modify existing event

• delete_event - Remove event

Venue Tools

• get_venues - List venues with search

• get_venue - Get venue details

• create_venue - Add new venue

• update_venue - Modify venue info

• delete_venue - Remove venue

Song Tools

• get_songs - List music library

• get_song - Get song details

• create_song - Add song to library

• update_song - Update song info

• delete_song - Remove song

User Tools

• get_users - List users (admin)

• get_user - Get user profile

• get_current_user - Get your profile

• update_user - Update user info

Integration Tools

• search_spotify - Search Spotify catalog

• get_spotify_token - Check Spotify auth

• search_places - Find locations

• get_place_details - Get place info

Usage Examples

Natural Language Commands

Once configured with an AI assistant, you can use natural language:

• "Show me all events happening this week"

• "Create a new venue called 'The Blue Note Jazz Club' in New York"

• "Search Spotify for Beatles songs"

• "Find events at Madison Square Garden"

• "Update my user profile with a new email"

Direct Tool Calls

{
  "name": "create_event",
  "arguments": {
    "name": "Summer Music Festival",
    "description": "Outdoor music event",
    "startDate": "2024-07-15T18:00:00Z",
    "maxAttendees": 500,
    "isPublic": true
  }
}

Development

Scripts

• npm run build - Compile TypeScript

• npm run dev - Watch mode for development

• npm run clean - Remove build files

• npm start - Run the compiled server

Project Structure

src/
├── index.ts          # Main MCP server
├── sonic-client.ts   # API client wrapper  
└── types.ts          # TypeScript definitions

.vscode/
└── mcp.json          # VS Code MCP configuration

.github/
└── copilot-instructions.md  # AI coding assistance

Debugging in VS Code

The project includes VS Code debugging support. You can now debug this MCP server using VS Code with proper breakpoints and debugging tools.

Security & Authentication

• JWT Authentication: All API calls require valid JWT token

• Permission System: Cascading ownership with admin overrides

• Environment Variables: Secure token storage

• Error Handling: Comprehensive error messages without exposing sensitive data

API Compatibility

Compatible with Sonic API endpoints:

• /api/events - Event management

• /api/venues - Venue management

• /api/songs - Music management

• /api/users - User operations

• /api/spotify - Music search

• /api/maps - Location services

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes with proper TypeScript types

4. Add tests if applicable

5. Submit a pull request

License

MIT License - See LICENSE file for details

Support

For issues and questions:

• Check the troubleshooting section in the code

• Review the MCP protocol documentation

• Ensure your JWT token is valid and not expired