Sonic MCP Server

Sonic MCP服务器

模型上下文协议（MCP）服务器，使人工智能代理能够与Sonic API交互，以管理事件、场地、歌曲和用户。

概述

此MCP服务器为AI代理提供了一个全面的接口，用于：

• 管理活动：使用完整的CRUD操作创建、读取、更新、删除事件
• 管理场馆：处理场地信息，包括地址和容量
• 处理歌曲：与Spotify集成的音乐数据管理
• 用户管理：配置文件操作和身份验证
• 搜索集成：Spotify音乐搜索和谷歌地图
• 实时交互：具有正确身份验证的API直接通信

特性

🎪 事件管理

• 创建具有日期、地点和与会者限制的活动
• 按名称、所有者或描述搜索和筛选事件
• 在回复中包含相关数据（场地、用户、歌曲）
• 支持公共/私人活动

🏢 场馆管理

• 创建具有详细地址信息的场地
• 管理场馆容量和描述
• 将场馆与活动联系起来
• 按地点或名称搜索场地

🎵 音乐整合

• 将歌曲添加到曲库
• 在Spotify上搜索曲目
• 将歌曲链接到活动
• 管理音乐元数据（艺术家、专辑、流派）

👥 用户操作

• 查看用户资料
• 更新帐户信息
• 用户管理的管理功能
• 认证与授权

🗺️ 定位服务

• 使用谷歌地图搜索地点
• 获取详细的地点信息
• 地址自动补全功能

安装和设置

先决条件

• Node.js 18+
• TypeScript
• 使用有效的JWT令牌访问Sonic API

快速开始

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. 设置您的身份验证令牌：

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

   # macOS/Linux
   export SONIC_API_TOKEN="your-jwt-token-here"

1. 运行服务器：

   npm start

配置

环境变量

• SONIC_API_TOKEN：您的JWT身份验证令牌（必需）
• SONIC_API_BASE_URL：API基本URL（默认值：https://localhost:5001/api)

获取JWT代币

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

AI客户端集成（克劳德桌面）

添加到您的Claude Desktop配置中：

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

可用工具

事件工具

• get_events -列出具有过滤和分页功能的事件
• get_event -获取特定事件详细信息
• create_event -创建新事件
• update_event -修改现有事件
• delete_event -删除事件

场馆工具

• get_venues -列出带有搜索功能的场地
• get_venue -获取场地详细信息
• create_venue -添加新场地
• update_venue -修改会场信息
• delete_venue -移除会场

歌曲工具

• get_songs -列出音乐库
• get_song -获取歌曲详细信息
• create_song -将歌曲添加到曲库
• update_song -更新歌曲信息
• delete_song -删除歌曲

用户工具

• get_users -列出用户（管理员）
• get_user -获取用户资料
• get_current_user -获取您的个人资料
• update_user -更新用户信息

集成工具

• search_spotify -搜索Spotify目录
• get_spotify_token -检查Spotify身份验证
• search_places -查找位置
• get_place_details -获取地点信息

使用示例

自然语言命令

一旦配置了AI助手，您就可以使用自然语言：

• *“显示本周发生的所有事件”*
• *“在纽约创建一个名为‘蓝音符爵士俱乐部’的新场地”*
• *“在Spotify上搜索披头士歌曲”*
• *“查找麦迪逊广场花园的活动”*
• *“用新电子邮件更新我的用户资料”*

直接工具调用

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

发展

脚本

• npm run build -编译TypeScript
• npm run dev -开发观看模式
• npm run clean -删除构建文件
• npm start -运行已编译的服务器

项目结构

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

VS代码调试

该项目包括VS代码调试支持。现在，您可以使用带有适当断点和调试工具的VS Code调试此MCP服务器。

安全和身份验证

• JWT身份验证：所有API调用都需要有效的JWT令牌
• 权限系统：通过管理员覆盖级联所有权
• 环境变量：安全令牌存储
• 错误处理：全面的错误消息，不会暴露敏感数据

API兼容性

与Sonic API端点兼容：

• /api/events -活动管理
• /api/venues -场馆管理
• /api/songs -音乐管理
• /api/users -用户操作
• /api/spotify -音乐搜索
• /api/maps -定位服务

贡献

1. 分叉存储库
2. 创建要素分支
3. 使用正确的TypeScript类型进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

• 检查代码中的故障排除部分
• 查阅MCP协议文档
• 确保您的JWT令牌有效且未过期