McScribble/sonic-mcp-server

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

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