mcp-ai-music 1.0.4 → 1.0.7

package/README.md

@@ -1,260 +1,260 @@
-# AI作曲 MCP 服务
-
-**版本 (Version):** 1.0.0
-
-## 描述 (Description)
-
-`mcp-ai-music` 是一个基于 Suno4.5 API 的 AI 作曲 MCP 服务，提供音乐生成、翻唱、扩展和进度查询功能。该服务支持多种音乐风格，可以生成原创音乐、对现有音乐进行翻唱转换，以及扩展音乐长度。
-
-## 功能特点
-
-- **原创音乐生成**：根据提示词和风格生成全新的音乐作品
-- **音乐翻唱**：将现有音乐转换为不同风格，保留核心旋律
-- **音乐扩展**：在保持原始风格的基础上延长音乐时长
-- **实时进度查询**：支持轮询查询任务进度，实时了解生成状态
-- **多模型支持**：支持 V3_5、V4、V4_5 多个AI模型版本
-- **纯音乐模式**：支持生成无歌词的纯音乐版本
-
-## 环境配置
-
-> **重要**：请配置以下必填环境变量：
-> - `SUNO_API_KEY`：Suno API 密钥
-> - `SUNO_SERVICE_BASE`：服务网关地址，默认 `https://www.mcpcn.cc`
-
-### 费用说明
-- 生成音乐：¥0.438/次
-- 翻唱音乐：¥0.438/次  
-- 扩展音乐：¥0.438/次
-- 查询进度：免费
-
-## 使用方法
-
-```json
-{
-  "mcpServers": {
-    "mcp-ai-music": {
-      "command": "node",
-      "args": [
-        "dist/index.js"
-      ],
-      "env": {
-        "SUNO_API_KEY": "您的Suno API密钥",
-        "SUNO_SERVICE_BASE": "https://www.mcpcn.cc/api"
-      },
-      "autoApprove": [
-        "generate_music",
-        "cover_music", 
-        "extend_music",
-        "query_progress"
-      ]
-    }
-  }
-}
-```
-
-## 可用工具 (Available Tools)
-
-该服务提供以下4个工具：
-
-### 1. `generate_music` - 生成音乐
-
-生成原创音乐作品。
-
-**输入参数：**
-- `prompt` (必需): 音乐描述提示词，详细描述想要的音乐风格、情感、乐器等
-  - V3_5/V4 模型：最多 3000 字符
-  - V4_5 模型：最多 5000 字符
-- `style` (可选): 音乐风格，如"古典"、"流行"、"摇滚"等
-  - V3_5/V4 模型：最多 200 字符
-  - V4_5 模型：最多 1000 字符  
-- `title` (可选): 音乐标题，最多 80 字符
-- `instrumental` (可选): 是否生成纯音乐（无歌词），默认 false
-- `model` (可选): AI模型版本，可选 "V3_5"、"V4"、"V4_5"，默认 "V4_5"
-- `negativeTags` (可选): 负面标签，描述不想要的音乐元素
-
-**调用示例：**
-```json
-{
-  "name": "generate_music",
-  "arguments": {
-    "prompt": "一段平静舒缓的钢琴曲，带有柔和的旋律，适合冥想和放松",
-    "style": "古典",
-    "title": "宁静钢琴冥想",
-    "instrumental": true,
-    "model": "V4_5",
-    "negativeTags": "重金属, 强节奏鼓点"
-  }
-}
-```
-
-### 2. `cover_music` - 翻唱音乐
-
-将现有音乐转换为新的风格，保留核心旋律。
-
-**输入参数：**
-- `uploadUrl` (必需): 要翻唱的音频文件URL，音频长度不超过2分钟
-- `prompt` (必需): 翻唱风格描述
-- `style` (可选): 目标音乐风格
-- `title` (可选): 翻唱版本标题
-- `instrumental` (可选): 是否生成纯音乐版本，默认 false
-- `model` (可选): AI模型版本，默认 "V4_5"
-- `negativeTags` (可选): 负面标签
-
-**调用示例：**
-```json
-{
-  "name": "cover_music",
-  "arguments": {
-    "uploadUrl": "https://example.com/audio.mp3",
-    "prompt": "将这首歌转换为爵士风格",
-    "style": "爵士",
-    "title": "爵士翻唱版",
-    "instrumental": false
-  }
-}
-```
-
-### 3. `extend_music` - 扩展音乐
-
-在保留原始音频风格的同时扩展音轨长度。
-
-**输入参数：**
-- `uploadUrl` (必需): 要扩展的音频文件URL，音频长度不超过2分钟
-- `prompt` (必需): 扩展描述，如"用更多舒缓的音符延长音乐"
-- `continueAt` (必需): 从音频的第几秒开始扩展，必须大于0且小于音频总时长
-- `style` (可选): 保持的音乐风格
-- `title` (可选): 扩展版本标题
-- `instrumental` (可选): 是否生成纯音乐版本，默认 false
-- `model` (可选): AI模型版本，必须与源音乐保持一致，默认 "V4_5"
-- `negativeTags` (可选): 负面标签
-
-**调用示例：**
-```json
-{
-  "name": "extend_music",
-  "arguments": {
-    "uploadUrl": "https://example.com/audio.mp3",
-    "prompt": "用更多舒缓的音符延长音乐，保持原有的宁静氛围",
-    "continueAt": 60,
-    "style": "古典",
-    "title": "宁静钢琴延长版",
-    "instrumental": true
-  }
-}
-```
-
-### 4. `query_progress` - 查询进度
-
-查询音乐生成任务的进度状态。
-
-> **重要提示**：由于AI生成音乐需要时间，大模型需要轮询此接口来获取任务状态和结果。建议每10-30秒查询一次，直到状态为'complete'或'failed'。
-
-**输入参数：**
-- `taskId` (必需): 音乐生成任务的ID（从其他工具的返回结果中获取）
-
-**调用示例：**
-```json
-{
-  "name": "query_progress",
-  "arguments": {
-    "taskId": "task_12345"
-  }
-}
-```
-
-**状态说明：**
-- `processing`: 正在处理中
-- `text`: 文本生成完成，正在生成音频
-- `first`: 第一首音乐生成完成
-- `complete`: 任务完成
-- `failed`: 任务失败
-
-## 工作流程示例
-
-### 生成原创音乐的完整流程：
-
-1. **发起生成请求**
-```json
-{
-  "name": "generate_music",
-  "arguments": {
-    "prompt": "一首欢快的流行歌曲，适合夏天",
-    "style": "流行",
-    "title": "夏日阳光"
-  }
-}
-```
-
-2. **获取任务ID**
-```json
-{
-  "taskId": "task_abc123",
-  "status": "pending",
-  "message": "音乐生成任务已提交，请使用query_progress工具查询进度。",
-  "cost": "¥0.438"
-}
-```
-
-3. **轮询查询进度**
-```json
-{
-  "name": "query_progress",
-  "arguments": {
-    "taskId": "task_abc123"
-  }
-}
-```
-
-4. **获取最终结果**
-当状态变为'complete'时，会返回包含音乐文件信息的完整结果。
-
-## 注意事项
-
-> 也需要设置 `SUNO_SERVICE_BASE`（默认 `https://www.mcpcn.cc`），否则将无法正常访问服务。
-
-1. **API密钥安全**：请确保 `SUNO_API_KEY` 环境变量已正确设置，不要在代码中硬编码API密钥。
-
-2. **文件大小限制**：上传的音频文件长度不得超过2分钟。
-
-3. **文件保存期限**：生成的音乐文件在服务器上保留15天后会被删除。
-
-4. **费用控制**：每次调用生成、翻唱、扩展功能都会产生¥0.438的费用，请合理使用。
-
-5. **轮询间隔**：建议查询进度的间隔为10-30秒，避免过于频繁的请求。
-
-6. **模型兼容性**：在扩展音乐时，使用的模型版本必须与源音乐的生成模型保持一致。
-
-7. **字符限制**：请注意各个参数的字符长度限制，超出限制会导致请求失败。
-
-## 错误处理
-
-服务会返回详细的错误信息，包括：
-- 参数验证错误
-- API请求失败
-- 字符长度超限
-- 任务状态异常
-
-所有错误都会在响应中通过 `isError` 字段标识，并在 `errorMessage` 字段中提供具体的错误描述。
-
-## 技术实现
-
-- 基于 Model Context Protocol (MCP) SDK 构建
-- 使用 Suno4.5 API 进行音乐生成
-- 支持 TypeScript 开发
-- 提供完整的类型定义和输入验证
-
-## 开发和构建
-
-```bash
-# 安装依赖
-npm install
-
-# 开发模式运行
-npm run dev
-
-# 构建项目
-npm run build
-
-# 启动服务
-npm start
-```
+# AI作曲 MCP 服务
+
+**版本 (Version):** 1.0.0
+
+## 描述 (Description)
+
+`mcp-ai-music` 是一个基于 Suno4.5 API 的 AI 作曲 MCP 服务，提供音乐生成、翻唱、扩展和进度查询功能。该服务支持多种音乐风格，可以生成原创音乐、对现有音乐进行翻唱转换，以及扩展音乐长度。
+
+## 功能特点
+
+- **原创音乐生成**：根据提示词和风格生成全新的音乐作品
+- **音乐翻唱**：将现有音乐转换为不同风格，保留核心旋律
+- **音乐扩展**：在保持原始风格的基础上延长音乐时长
+- **实时进度查询**：支持轮询查询任务进度，实时了解生成状态
+- **多模型支持**：支持 V3_5、V4、V4_5 多个AI模型版本
+- **纯音乐模式**：支持生成无歌词的纯音乐版本
+
+## 环境配置
+
+> **重要**：请配置以下必填环境变量：
+> - `SUNO_API_KEY`：Suno API 密钥
+> - `SUNO_SERVICE_BASE`：服务网关地址，默认 `https://www.mcpcn.cc`
+
+### 费用说明
+- 生成音乐：¥0.438/次
+- 翻唱音乐：¥0.438/次  
+- 扩展音乐：¥0.438/次
+- 查询进度：免费
+
+## 使用方法
+
+```json
+{
+  "mcpServers": {
+    "mcp-ai-music": {
+      "command": "node",
+      "args": [
+        "dist/index.js"
+      ],
+      "env": {
+        "SUNO_API_KEY": "您的Suno API密钥",
+        "SUNO_SERVICE_BASE": "https://www.mcpcn.cc/api"
+      },
+      "autoApprove": [
+        "generate_music",
+        "cover_music", 
+        "extend_music",
+        "query_progress"
+      ]
+    }
+  }
+}
+```
+
+## 可用工具 (Available Tools)
+
+该服务提供以下4个工具：
+
+### 1. `generate_music` - 生成音乐
+
+生成原创音乐作品。
+
+**输入参数：**
+- `prompt` (必需): 音乐描述提示词，详细描述想要的音乐风格、情感、乐器等
+  - V3_5/V4 模型：最多 3000 字符
+  - V4_5 模型：最多 5000 字符
+- `style` (可选): 音乐风格，如"古典"、"流行"、"摇滚"等
+  - V3_5/V4 模型：最多 200 字符
+  - V4_5 模型：最多 1000 字符  
+- `title` (可选): 音乐标题，最多 80 字符
+- `instrumental` (可选): 是否生成纯音乐（无歌词），默认 false
+- `model` (可选): AI模型版本，可选 "V3_5"、"V4"、"V4_5"，默认 "V4_5"
+- `negativeTags` (可选): 负面标签，描述不想要的音乐元素
+
+**调用示例：**
+```json
+{
+  "name": "generate_music",
+  "arguments": {
+    "prompt": "一段平静舒缓的钢琴曲，带有柔和的旋律，适合冥想和放松",
+    "style": "古典",
+    "title": "宁静钢琴冥想",
+    "instrumental": true,
+    "model": "V4_5",
+    "negativeTags": "重金属, 强节奏鼓点"
+  }
+}
+```
+
+### 2. `cover_music` - 翻唱音乐
+
+将现有音乐转换为新的风格，保留核心旋律。
+
+**输入参数：**
+- `uploadUrl` (必需): 要翻唱的音频文件URL，音频长度不超过2分钟
+- `prompt` (必需): 翻唱风格描述
+- `style` (可选): 目标音乐风格
+- `title` (可选): 翻唱版本标题
+- `instrumental` (可选): 是否生成纯音乐版本，默认 false
+- `model` (可选): AI模型版本，默认 "V4_5"
+- `negativeTags` (可选): 负面标签
+
+**调用示例：**
+```json
+{
+  "name": "cover_music",
+  "arguments": {
+    "uploadUrl": "https://example.com/audio.mp3",
+    "prompt": "将这首歌转换为爵士风格",
+    "style": "爵士",
+    "title": "爵士翻唱版",
+    "instrumental": false
+  }
+}
+```
+
+### 3. `extend_music` - 扩展音乐
+
+在保留原始音频风格的同时扩展音轨长度。
+
+**输入参数：**
+- `uploadUrl` (必需): 要扩展的音频文件URL，音频长度不超过2分钟
+- `prompt` (必需): 扩展描述，如"用更多舒缓的音符延长音乐"
+- `continueAt` (必需): 从音频的第几秒开始扩展，必须大于0且小于音频总时长
+- `style` (可选): 保持的音乐风格
+- `title` (可选): 扩展版本标题
+- `instrumental` (可选): 是否生成纯音乐版本，默认 false
+- `model` (可选): AI模型版本，必须与源音乐保持一致，默认 "V4_5"
+- `negativeTags` (可选): 负面标签
+
+**调用示例：**
+```json
+{
+  "name": "extend_music",
+  "arguments": {
+    "uploadUrl": "https://example.com/audio.mp3",
+    "prompt": "用更多舒缓的音符延长音乐，保持原有的宁静氛围",
+    "continueAt": 60,
+    "style": "古典",
+    "title": "宁静钢琴延长版",
+    "instrumental": true
+  }
+}
+```
+
+### 4. `query_progress` - 查询进度
+
+查询音乐生成任务的进度状态。
+
+> **重要提示**：由于AI生成音乐需要时间，大模型需要轮询此接口来获取任务状态和结果。建议每10-30秒查询一次，直到状态为'complete'或'failed'。
+
+**输入参数：**
+- `taskId` (必需): 音乐生成任务的ID（从其他工具的返回结果中获取）
+
+**调用示例：**
+```json
+{
+  "name": "query_progress",
+  "arguments": {
+    "taskId": "task_12345"
+  }
+}
+```
+
+**状态说明：**
+- `processing`: 正在处理中
+- `text`: 文本生成完成，正在生成音频
+- `first`: 第一首音乐生成完成
+- `complete`: 任务完成
+- `failed`: 任务失败
+
+## 工作流程示例
+
+### 生成原创音乐的完整流程：
+
+1. **发起生成请求**
+```json
+{
+  "name": "generate_music",
+  "arguments": {
+    "prompt": "一首欢快的流行歌曲，适合夏天",
+    "style": "流行",
+    "title": "夏日阳光"
+  }
+}
+```
+
+2. **获取任务ID**
+```json
+{
+  "taskId": "task_abc123",
+  "status": "pending",
+  "message": "音乐生成任务已提交，请使用query_progress工具查询进度。",
+  "cost": "¥0.438"
+}
+```
+
+3. **轮询查询进度**
+```json
+{
+  "name": "query_progress",
+  "arguments": {
+    "taskId": "task_abc123"
+  }
+}
+```
+
+4. **获取最终结果**
+当状态变为'complete'时，会返回包含音乐文件信息的完整结果。
+
+## 注意事项
+
+> 也需要设置 `SUNO_SERVICE_BASE`（默认 `https://www.mcpcn.cc`），否则将无法正常访问服务。
+
+1. **API密钥安全**：请确保 `SUNO_API_KEY` 环境变量已正确设置，不要在代码中硬编码API密钥。
+
+2. **文件大小限制**：上传的音频文件长度不得超过2分钟。
+
+3. **文件保存期限**：生成的音乐文件在服务器上保留15天后会被删除。
+
+4. **费用控制**：每次调用生成、翻唱、扩展功能都会产生¥0.438的费用，请合理使用。
+
+5. **轮询间隔**：建议查询进度的间隔为10-30秒，避免过于频繁的请求。
+
+6. **模型兼容性**：在扩展音乐时，使用的模型版本必须与源音乐的生成模型保持一致。
+
+7. **字符限制**：请注意各个参数的字符长度限制，超出限制会导致请求失败。
+
+## 错误处理
+
+服务会返回详细的错误信息，包括：
+- 参数验证错误
+- API请求失败
+- 字符长度超限
+- 任务状态异常
+
+所有错误都会在响应中通过 `isError` 字段标识，并在 `errorMessage` 字段中提供具体的错误描述。
+
+## 技术实现
+
+- 基于 Model Context Protocol (MCP) SDK 构建
+- 使用 Suno4.5 API 进行音乐生成
+- 支持 TypeScript 开发
+- 提供完整的类型定义和输入验证
+
+## 开发和构建
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式运行
+npm run dev
+
+# 构建项目
+npm run build
+
+# 启动服务
+npm start
+```

package/dist/index.js

@@ -26,8 +26,8 @@ function getServiceBase() {
         process.env.SUNO_QUERY_BASE_URL ||
         process.env.SUNO_CALLBACK_URL);
 }
-// 构造回调地址
-function buildCallbackUrl(kind) {
+// 构造回调地址，可附带 chatSessionId
+function buildCallbackUrl(kind, chatSessionId) {
     const base = getServiceBase();
     if (!base) {
         throw new Error("未配置 SUNO_SERVICE_BASE（或兼容变量），用于设置服务端基地址");
@@ -37,7 +37,11 @@ function buildCallbackUrl(kind) {
         "upload-cover": "/suno/callback/upload-cover",
         "upload-extend": "/suno/callback/upload-extend",
     };
-    return `${base.replace(/\/$/, "")}${pathMap[kind]}`;
+    const url = `${base.replace(/\/$/, "")}${pathMap[kind]}`;
+    if (chatSessionId) {
+        return `${url}?chat_session_id=${encodeURIComponent(chatSessionId)}`;
+    }
+    return url;
 }
 // 查询同样使用统一基地址
 function getQueryBase() {
@@ -85,17 +89,22 @@ const PROGRESS_QUERY_OUTPUT_SCHEMA = {
 // 工具定义
 const GENERATE_MUSIC_TOOL = {
     name: "generate_music",
-    description: "生成音乐。根据提示词和风格生成原创音乐，支持自定义模式和纯音乐模式。\n\n注意：\n- 生成需要时间，请每10-30秒轮询调用 query_progress 查询进度工具，直到状态为 'complete' 或 'failed'。\n- 平台仅保存音频与封面文件 15 天，请及时下载保存。\n\n参数行为说明：\n- customMode: 是否启用自定义模式（默认 true）。\n- instrumental: 是否为纯音乐。\n- 当 customMode=true 且 instrumental=false 时，prompt 将作为精确歌词使用；\n  当 customMode=false 且 instrumental=false 时，将自动生成歌词；\n  当 instrumental=true 时，始终为纯音乐（不含歌词）。\n\n返回字段说明：\n- taskId: 任务ID，用于查询进度\n- status: 任务状态 (pending)\n- message: 状态描述",
+    description: "生成音乐。根据提示词和风格生成原创音乐，支持自定义模式和纯音乐模式。\n\n注意：\n- 生成需要时间，请每10-30秒轮询调用 query_progress 查询进度工具，直到状态为 'complete' 或 'failed'。\n- 平台仅保存音频与封面文件 15 天，请及时下载保存。\n\n参数行为说明：\n- customMode: 是否启用自定义模式（默认 true）。\n- instrumental: 是否为纯音乐。\n- 当 customMode=true 且 instrumental=false 时，可以同时提供 prompt（音乐描述）和 lyrics（精确歌词）；\n  当 customMode=false 且 instrumental=false 时，只需 prompt，将自动生成歌词；\n  当 instrumental=true 时，始终为纯音乐（不含歌词），只需提供 prompt。\n\n返回字段说明：\n- taskId: 任务ID，用于查询进度\n- status: 任务状态 (pending)\n- message: 状态描述",
     inputSchema: {
         type: "object",
         properties: {
             prompt: {
                 type: "string",
-                description: "音乐描述提示词，详细描述想要的音乐风格、情感、乐器等。长度限制：V3_5和V4模型3000字符，V4_5模型5000字符。注意：当 customMode=true 且 instrumental=false 时，prompt 将作为精确歌词使用。",
+                description: "音乐描述提示词，详细描述想要的音乐风格、情感、乐器等。长度限制：V3_5和V4模型3000字符，V4_5模型5000字符。当 instrumental=false 时，可与 lyrics 字段配合使用。",
+            },
+            lyrics: {
+                type: "string",
+                description: "精确歌词内容，用于 customMode=true 且 instrumental=false 时。当提供此字段时，AI将按照此歌词演唱。长度限制：V3_5和V4模型3000字符，V4_5模型5000字符。",
+                default: "",
             },
             style: {
                 type: "string",
-                description: "音乐风格，如'古典'、'流行'、'摇滚'等。长度限制：V3_5和V4模型200字符，V4_5模型1000字符。",
+                description: "音乐风格，如'古典'、'流行'、'摇滚'、'电子'等。长度限制：V3_5和V4模型200字符，V4_5模型1000字符。",
                 default: "",
             },
             title: {
@@ -105,12 +114,12 @@ const GENERATE_MUSIC_TOOL = {
             },
             customMode: {
                 type: "boolean",
-                description: "是否启用自定义模式。为 true 时：如果 instrumental=true，仅需提供 style 和 title；如果 instrumental=false，需要提供 style、title 和 prompt（prompt 作为精确歌词）。为 false 时：只需 prompt，若 instrumental=false 将自动生成歌词。",
+                description: "是否启用自定义模式。为 true 时：如果 instrumental=true，仅需提供 style 和 title；如果 instrumental=false，需要提供 style、title，可选择提供 prompt（音乐描述）和/或 lyrics（精确歌词）。为 false 时：只需 prompt，若 instrumental=false 将自动生成歌词。",
                 default: true,
             },
             instrumental: {
                 type: "boolean",
-                description: "是否生成纯音乐（无歌词）。当 customMode=true 且该值=false 时，需要提供精确歌词（使用 prompt 作为歌词）；当 customMode=false 且该值=false，将自动生成歌词。",
+                description: "是否生成纯音乐（无歌词）。当 customMode=true 且该值=false 时，可以同时提供 prompt（音乐描述）和 lyrics（精确歌词）；当 customMode=false 且该值=false，将自动生成歌词。",
                 default: false,
             },
             model: {
@@ -131,7 +140,7 @@ const GENERATE_MUSIC_TOOL = {
 };
 const COVER_MUSIC_TOOL = {
     name: "cover_music",
-    description: "翻唱音乐。上传音频文件并转换为新的风格，保留核心旋律。\n\n注意：\n- 生成需要时间，请每10-30秒轮询调用 query_progress 工具，直到状态为 'complete' 或 'failed'。\n- 平台仅保存音频与封面文件 15 天，请及时下载保存。\n\n返回字段说明：\n- taskId: 任务ID，用于查询进度\n- status: 任务状态 (pending)\n- message: 状态描述",
+    description: "翻唱音乐。上传音频文件并转换为新的风格，保留核心旋律。\n\n注意：\n- 生成需要时间，请每10-30秒轮询调用 query_progress 工具，直到状态为 'complete' 或 'failed'。\n- 平台仅保存音频与封面文件 15 天，请及时下载保存。\n- 当 instrumental=false 时，可以同时提供 prompt（风格描述）和 lyrics（精确歌词）。\n\n返回字段说明：\n- taskId: 任务ID，用于查询进度\n- status: 任务状态 (pending)\n- message: 状态描述",
     inputSchema: {
         type: "object",
         properties: {
@@ -141,11 +150,16 @@ const COVER_MUSIC_TOOL = {
             },
             prompt: {
                 type: "string",
-                description: "翻唱风格描述。",
+                description: "翻唱风格描述，描述想要的音乐风格、情感、乐器等。当 instrumental=false 时，可与 lyrics 字段配合使用。",
+            },
+            lyrics: {
+                type: "string",
+                description: "精确歌词内容，用于 instrumental=false 时。当提供此字段时，AI将按照此歌词演唱。长度限制：V3_5和V4模型3000字符，V4_5模型5000字符。",
+                default: "",
             },
             style: {
                 type: "string",
-                description: "目标音乐风格。",
+                description: "目标音乐风格，如'古典'、'流行'、'摇滚'、'电子'等。",
                 default: "",
             },
             title: {
@@ -155,7 +169,7 @@ const COVER_MUSIC_TOOL = {
             },
             instrumental: {
                 type: "boolean",
-                description: "是否生成纯音乐版本。",
+                description: "是否生成纯音乐版本。当该值=false 时，可以同时提供 prompt（风格描述）和 lyrics（精确歌词）。",
                 default: false,
             },
             model: {
@@ -166,7 +180,7 @@ const COVER_MUSIC_TOOL = {
             },
             negativeTags: {
                 type: "string",
-                description: "负面标签。",
+                description: "负面标签，描述不想要的音乐元素。",
                 default: "",
             },
         },
@@ -176,7 +190,7 @@ const COVER_MUSIC_TOOL = {
 };
 const EXTEND_MUSIC_TOOL = {
     name: "extend_music",
-    description: "扩展音乐。在保留原始音频风格的同时扩展音轨长度。\n\n注意：\n- 生成需要时间，请每10-30秒轮询调用 query_progress 工具，直到状态为 'complete' 或 'failed'。\n- 平台仅保存音频与封面文件 15 天，请及时下载保存。\n\n返回字段说明：\n- taskId: 任务ID，用于查询进度\n- status: 任务状态 (pending)\n- message: 状态描述",
+    description: "扩展音乐。在保留原始音频风格的同时扩展音轨长度。\n\n注意：\n- 生成需要时间，请每10-30秒轮询调用 query_progress 工具，直到状态为 'complete' 或 'failed'。\n- 平台仅保存音频与封面文件 15 天，请及时下载保存。\n- 当 instrumental=false 时，可以同时提供 prompt（扩展描述）和 lyrics（精确歌词）。\n\n返回字段说明：\n- taskId: 任务ID，用于查询进度\n- status: 任务状态 (pending)\n- message: 状态描述",
     inputSchema: {
         type: "object",
         properties: {
@@ -186,11 +200,16 @@ const EXTEND_MUSIC_TOOL = {
             },
             prompt: {
                 type: "string",
-                description: "扩展描述，如'用更多舒缓的音符延长音乐'。",
+                description: "扩展描述，如'用更多舒缓的音符延长音乐'。当 instrumental=false 时，可与 lyrics 字段配合使用。",
+            },
+            lyrics: {
+                type: "string",
+                description: "精确歌词内容，用于 instrumental=false 时。当提供此字段时，AI将按照此歌词演唱扩展部分。长度限制：V3_5和V4模型3000字符，V4_5模型5000字符。",
+                default: "",
             },
             style: {
                 type: "string",
-                description: "保持的音乐风格。",
+                description: "保持的音乐风格，如'古典'、'流行'、'摇滚'、'电子'等。",
                 default: "",
             },
             title: {
@@ -205,7 +224,7 @@ const EXTEND_MUSIC_TOOL = {
             },
             instrumental: {
                 type: "boolean",
-                description: "是否生成纯音乐版本。",
+                description: "是否生成纯音乐版本。当该值=false 时，可以同时提供 prompt（扩展描述）和 lyrics（精确歌词）。",
                 default: false,
             },
             model: {
@@ -216,7 +235,7 @@ const EXTEND_MUSIC_TOOL = {
             },
             negativeTags: {
                 type: "string",
-                description: "负面标签。",
+                description: "负面标签，描述不想要的音乐元素。",
                 default: "",
             },
         },
@@ -336,7 +355,7 @@ async function makeApiRequestRaw(url, method, body, retries = 3) {
     }
 }
 // 生成音乐处理函数
-async function handleGenerateMusic(input) {
+async function handleGenerateMusic(input, chatSessionId) {
     try {
         if (!input || typeof input !== 'object') {
             return {
@@ -345,44 +364,107 @@ async function handleGenerateMusic(input) {
                 errorMessage: "输入参数格式错误，预期为包含prompt字段的对象。",
             };
         }
-        const { prompt, style = "", title = "", customMode = true, instrumental = false, model = "V4_5", negativeTags = "" } = input;
-        if (!prompt || typeof prompt !== 'string') {
-            return {
-                content: [],
-                isError: true,
-                errorMessage: "prompt字段是必需的，且必须为字符串类型。",
-            };
+        const { prompt, lyrics = "", style = "", title = "", customMode = true, instrumental = false, model = "V4_5", negativeTags = "" } = input;
+        // 根据API文档，当customMode=false时，只需要prompt
+        // 当customMode=true且instrumental=true时，只需要style和title
+        // 当customMode=true且instrumental=false时，需要style和title，可以选择提供prompt和/或lyrics
+        if (!customMode) {
+            // 非自定义模式：只需要prompt
+            if (!prompt || typeof prompt !== 'string') {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: "非自定义模式下，prompt字段是必需的，且必须为字符串类型。",
+                };
+            }
         }
-        // 验证prompt长度
-        const maxPromptLength = model === "V4_5" ? 5000 : 3000;
-        if (prompt.length > maxPromptLength) {
-            return {
-                content: [],
-                isError: true,
-                errorMessage: `prompt长度超过限制。${model}模型最大允许${maxPromptLength}字符。`,
-            };
+        else if (instrumental) {
+            // 自定义模式且为纯音乐：只需要style和title
+            if (!style || typeof style !== 'string') {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: "自定义纯音乐模式下，style字段是必需的，且必须为字符串类型。",
+                };
+            }
+            if (!title || typeof title !== 'string') {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: "自定义纯音乐模式下，title字段是必需的，且必须为字符串类型。",
+                };
+            }
         }
-        // 验证style长度
-        const maxStyleLength = model === "V4_5" ? 1000 : 200;
-        if (style.length > maxStyleLength) {
-            return {
-                content: [],
-                isError: true,
-                errorMessage: `style长度超过限制。${model}模型最大允许${maxStyleLength}字符。`,
-            };
+        else {
+            // 自定义模式且有歌词：需要style和title，可以选择提供prompt和/或lyrics
+            if (!style || typeof style !== 'string') {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: "自定义有歌词模式下，style字段是必需的，且必须为字符串类型。",
+                };
+            }
+            if (!title || typeof title !== 'string') {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: "自定义有歌词模式下，title字段是必需的，且必须为字符串类型。",
+                };
+            }
+            if (!prompt && !lyrics) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: "自定义有歌词模式下，至少需要提供prompt（音乐描述）或lyrics（精确歌词）中的一个。",
+                };
+            }
+        }
+        // 验证prompt长度（如果提供）
+        if (prompt) {
+            const maxPromptLength = model === "V4_5" ? 5000 : 3000;
+            if (prompt.length > maxPromptLength) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: `prompt长度超过限制。${model}模型最大允许${maxPromptLength}字符。`,
+                };
+            }
+        }
+        // 验证lyrics长度（如果提供）
+        if (lyrics) {
+            const maxLyricsLength = model === "V4_5" ? 5000 : 3000;
+            if (lyrics.length > maxLyricsLength) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: `lyrics长度超过限制。${model}模型最大允许${maxLyricsLength}字符。`,
+                };
+            }
+        }
+        // 验证style长度（如果提供）
+        if (style) {
+            const maxStyleLength = model === "V4_5" ? 1000 : 200;
+            if (style.length > maxStyleLength) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: `style长度超过限制。${model}模型最大允许${maxStyleLength}字符。`,
+                };
+            }
         }
-        // 验证title长度
-        if (title.length > 80) {
+        // 验证title长度（如果提供）
+        if (title && title.length > 80) {
             return {
                 content: [],
                 isError: true,
                 errorMessage: "title长度超过限制，最大允许80字符。",
             };
         }
-        const callbackUrl = buildCallbackUrl("generate");
+        const callbackUrl = buildCallbackUrl("generate", chatSessionId);
         console.error(`使用回调地址: ${callbackUrl}`);
+        // 构建请求体，根据API文档，当customMode=true且instrumental=false时，
+        // 如果提供了lyrics，则使用lyrics作为prompt字段发送给API
         const requestBody = {
-            prompt,
             style,
             title,
             customMode,
@@ -391,6 +473,14 @@ async function handleGenerateMusic(input) {
             negativeTags,
             callBackUrl: callbackUrl, // 必需的参数
         };
+        // 根据Suno API文档，当customMode=true且instrumental=false时，
+        // 如果提供了精确歌词，应该将其作为prompt字段发送
+        if (customMode && !instrumental && lyrics) {
+            requestBody.prompt = lyrics;
+        }
+        else if (prompt) {
+            requestBody.prompt = prompt;
+        }
         const result = await makeApiRequest('/generate', 'POST', requestBody);
         const taskData = {
             taskId: result.data?.taskId || result.taskId || result.id || result.task_id || "unknown",
@@ -419,7 +509,7 @@ async function handleGenerateMusic(input) {
     }
 }
 // 翻唱音乐处理函数
-async function handleCoverMusic(input) {
+async function handleCoverMusic(input, chatSessionId) {
     try {
         if (!input || typeof input !== 'object') {
             return {
@@ -428,7 +518,7 @@ async function handleCoverMusic(input) {
                 errorMessage: "输入参数格式错误，预期为包含uploadUrl和prompt字段的对象。",
             };
         }
-        const { uploadUrl, prompt, style = "", title = "", instrumental = false, model = "V4_5", negativeTags = "" } = input;
+        const { uploadUrl, prompt, lyrics = "", style = "", title = "", instrumental = false, model = "V4_5", negativeTags = "" } = input;
         if (!uploadUrl || typeof uploadUrl !== 'string') {
             return {
                 content: [],
@@ -443,17 +533,45 @@ async function handleCoverMusic(input) {
                 errorMessage: "prompt字段是必需的，且必须为字符串类型。",
             };
         }
+        // 验证prompt长度
+        if (prompt) {
+            const maxPromptLength = model === "V4_5" ? 5000 : 3000;
+            if (prompt.length > maxPromptLength) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: `prompt长度超过限制。${model}模型最大允许${maxPromptLength}字符。`,
+                };
+            }
+        }
+        // 验证lyrics长度（如果提供）
+        if (lyrics) {
+            const maxLyricsLength = model === "V4_5" ? 5000 : 3000;
+            if (lyrics.length > maxLyricsLength) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: `lyrics长度超过限制。${model}模型最大允许${maxLyricsLength}字符。`,
+                };
+            }
+        }
         const requestBody = {
             uploadUrl,
-            prompt,
             style,
             title,
             customMode: true,
             instrumental,
             model,
             negativeTags,
-            callBackUrl: buildCallbackUrl("upload-cover"), // 必需的参数
+            callBackUrl: buildCallbackUrl("upload-cover", chatSessionId), // 必需的参数
         };
+        // 根据Suno API文档，当instrumental=false且提供了lyrics时，使用lyrics作为prompt字段发送给API
+        if (!instrumental && lyrics) {
+            requestBody.prompt = lyrics;
+        }
+        else {
+            requestBody.prompt = prompt;
+        }
         const result = await makeApiRequest('/generate/upload-cover', 'POST', requestBody);
         const taskData = {
             taskId: result.data?.taskId || result.taskId || result.id || result.task_id || "unknown",
@@ -482,7 +600,7 @@ async function handleCoverMusic(input) {
     }
 }
 // 扩展音乐处理函数
-async function handleExtendMusic(input) {
+async function handleExtendMusic(input, chatSessionId) {
     try {
         if (!input || typeof input !== 'object') {
             return {
@@ -491,7 +609,7 @@ async function handleExtendMusic(input) {
                 errorMessage: "输入参数格式错误，预期为包含uploadUrl、prompt和continueAt字段的对象。",
             };
         }
-        const { uploadUrl, prompt, style = "", title = "", continueAt, instrumental = false, model = "V4_5", negativeTags = "" } = input;
+        const { uploadUrl, prompt, lyrics = "", style = "", title = "", continueAt, instrumental = false, model = "V4_5", negativeTags = "" } = input;
         if (!uploadUrl || typeof uploadUrl !== 'string') {
             return {
                 content: [],
@@ -513,18 +631,46 @@ async function handleExtendMusic(input) {
                 errorMessage: "continueAt字段是必需的，且必须为大于0的数字。",
             };
         }
+        // 验证prompt长度
+        if (prompt) {
+            const maxPromptLength = model === "V4_5" ? 5000 : 3000;
+            if (prompt.length > maxPromptLength) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: `prompt长度超过限制。${model}模型最大允许${maxPromptLength}字符。`,
+                };
+            }
+        }
+        // 验证lyrics长度（如果提供）
+        if (lyrics) {
+            const maxLyricsLength = model === "V4_5" ? 5000 : 3000;
+            if (lyrics.length > maxLyricsLength) {
+                return {
+                    content: [],
+                    isError: true,
+                    errorMessage: `lyrics长度超过限制。${model}模型最大允许${maxLyricsLength}字符。`,
+                };
+            }
+        }
         const requestBody = {
             uploadUrl,
             defaultParamFlag: true,
             instrumental,
-            prompt,
             style,
             title,
             continueAt,
             model,
             negativeTags,
-            callBackUrl: buildCallbackUrl("upload-extend"), // 必需的参数
+            callBackUrl: buildCallbackUrl("upload-extend", chatSessionId), // 必需的参数
         };
+        // 根据Suno API文档，当instrumental=false且提供了lyrics时，使用lyrics作为prompt字段发送给API
+        if (!instrumental && lyrics) {
+            requestBody.prompt = lyrics;
+        }
+        else {
+            requestBody.prompt = prompt;
+        }
         const result = await makeApiRequest('/generate/upload-extend', 'POST', requestBody);
         const taskData = {
             taskId: result.data?.taskId || result.taskId || result.id || result.task_id || "unknown",
@@ -613,6 +759,12 @@ async function handleQueryProgress(input) {
             status = 'complete';
         if (status === 'running')
             status = 'processing';
+        // 仅当存在最终音频链接（audioUrl 非空）才认为完成；
+        // 如果只有流式地址（streamAudioUrl）但 audioUrl 为空，则视为进行中
+        const hasFinalAudio = typeof result.audioUrl === 'string' && result.audioUrl.trim() !== '';
+        if (status === 'complete' && !hasFinalAudio) {
+            status = 'processing';
+        }
         let statusMessage = "";
         switch (status) {
             case 'pending':
@@ -641,7 +793,7 @@ async function handleQueryProgress(input) {
             status,
             progress,
             message: statusMessage,
-            result: status === 'complete' ? {
+            result: status === 'complete' && hasFinalAudio ? {
                 // 基本信息
                 taskId: result.taskId,
                 status: result.status,
@@ -811,14 +963,24 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     try {
         const toolName = request.params.name;
         const toolInput = request.params.arguments;
+        // 解析 meta.chatSessionId （如果存在）
+        const chatSessionId = request?.meta?.chatSessionId
+            ?? request?.params?.meta?.chatSessionId
+            ?? undefined;
+        if (chatSessionId) {
+            console.error(`接收到 chatSessionId: ${chatSessionId}`);
+        }
+        else {
+            console.error("未在请求中检测到 chatSessionId（meta.chatSessionId）");
+        }
         console.error(`收到工具调用请求: ${toolName}, 输入: ${JSON.stringify(toolInput)}`);
         switch (toolName) {
             case GENERATE_MUSIC_TOOL.name:
-                return await handleGenerateMusic(toolInput);
+                return await handleGenerateMusic(toolInput, chatSessionId);
             case COVER_MUSIC_TOOL.name:
-                return await handleCoverMusic(toolInput);
+                return await handleCoverMusic(toolInput, chatSessionId);
             case EXTEND_MUSIC_TOOL.name:
-                return await handleExtendMusic(toolInput);
+                return await handleExtendMusic(toolInput, chatSessionId);
             case QUERY_PROGRESS_TOOL.name:
                 return await handleQueryProgress(toolInput);
             default:

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "mcp-ai-music",
-  "version": "1.0.4",
-  "description": "AI作曲MCP服务 - 基于Suno4.5 API的音乐生成、翻唱、扩展和进度查询工具",
-  "main": "dist/index.js",
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "ts-node src/index.ts",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [
-    "AI",
-    "music",
-    "composition",
-    "suno",
-    "mcp",
-    "audio",
-    "generation"
-  ],
-  "author": "",
-  "license": "ISC",
-  "bin": {
-    "mcp-ai-music": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.0",
-    "node-fetch": "^2.7.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.14.1",
-    "@types/node-fetch": "^2.6.12",
-    "typescript": "^5.8.3",
-    "ts-node": "^10.9.2"
-  }
-}
+{
+  "name": "mcp-ai-music",
+  "version": "1.0.7",
+  "description": "AI作曲MCP服务 - 基于Suno4.5 API的音乐生成、翻唱、扩展和进度查询工具",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "AI",
+    "music",
+    "composition",
+    "suno",
+    "mcp",
+    "audio",
+    "generation"
+  ],
+  "author": "",
+  "license": "ISC",
+  "bin": {
+    "mcp-ai-music": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0",
+    "node-fetch": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "@types/node-fetch": "^2.6.12",
+    "typescript": "^5.8.3",
+    "ts-node": "^10.9.2"
+  }
+}