# 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:**
   ```bash
   npm install
   ```

2. **Build the project:**
   ```bash
   npm run build
   ```

3. **Set your authentication token:**
   ```bash
   # Windows (PowerShell)
   $env:SONIC_API_TOKEN = "your-jwt-token-here"
   
   # macOS/Linux
   export SONIC_API_TOKEN="your-jwt-token-here"
   ```

4. **Run the server:**
   ```bash
   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
```bash
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:

```json
{
  "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
```json
{
  "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