JinDaGe - tongyi-wanx-mcp-server MCP Details

article

README

🚀 通义万相 MCP 服务器

通义万相 MCP 服务器基于 TypeScript 构建，遵循 Model Context Protocol (MCP) 规范。它为阿里云通义万相的文生图（Text-to-Image）和文生视频（Text-to-Video）能力提供支持，允许大语言模型（LLM）通过 MCP 协议直接调用图像和视频生成 API。

🚀 快速开始

通义万相 MCP 服务器是一个强大的工具，它允许大语言模型（LLM）通过 MCP 协议直接调用阿里云通义万相的图像和视频生成 API。下面以百炼平台为例，展示如何快速集成该服务器：

{
  "mcpServers": {
    "tongyi-wanxiang": {
      "command": "npx",
      "args": [
        "-y",
        "tongyi-wanx-mcp-server@latest"
      ],
      "env": {
        "DASHSCOPE_API_KEY": "<你的通义万相 API 访问密钥>"
      }
    }
  }
}

✨ 主要特性

文生图能力集成：接入阿里云通义万相文生图 API，支持高质量的 AI 图像生成。
文生视频能力集成：接入阿里云通义万相文生视频 API，支持高质量的 AI 视频生成。
异步任务处理：支持长时间运行的图像和视频生成任务，通过异步轮询获取最终结果。
MCP 协议支持：符合 Model Context Protocol 规范，可与支持 MCP 的 LLM 无缝协作。

📦 安装指南

环境要求

Node.js >= 16.x
npm >= 8.x 或 pnpm

安装步骤

安装依赖：
```
npm install
```
构建项目：
```
npm run build
```
启动服务器：
```
npm start
```

💻 使用示例

基础用法

以百炼平台为例，在配置文件中集成通义万相 MCP 服务器：

{
  "mcpServers": {
    "tongyi-wanxiang": {
      "command": "npx",
      "args": [
        "-y",
        "tongyi-wanx-mcp-server@latest"
      ],
      "env": {
        "DASHSCOPE_API_KEY": "<你的通义万相 API 访问密钥>"
      }
    }
  }
}

📚 详细文档

API 接口说明

文生图生成接口

参数：
- prompt：图像描述的文本。
- width：图像宽度，默认为 512。
- height：图像高度，默认为 512。
- negative_prompt（可选）：减少生成图像中出现的内容。
返回值：

{
  "task_id": string // 任务唯一标识符
}

文生图结果获取接口

参数：
- task_id：文生图生成时返回的任务 ID。
返回值：

{
  "status": "completed" || "processing" || "failed",
  "result_url": string, // 图像 URL，仅在完成时返回
  "error_message": string // 错误信息，失败时返回
}

文生视频生成接口

参数：
- prompt：视频描述的文本。
- width：视频宽度，默认为 512。
- height：视频高度，默认为 512。
- duration（可选）：视频时长，默认为 10 秒。
- negative_prompt（可选）：减少生成视频中出现的内容。
返回值：

{
  "task_id": string // 任务唯一标识符
}

文生视频结果获取接口

参数：
- task_id：文生视频生成时返回的任务 ID。
返回值：

{
  "status": "completed" || "processing" || "failed",
  "result_url": string, // 视频 URL，仅在完成时返回
  "error_message": string // 错误信息，失败时返回
}

配置文件

// config.ts
export const CONFIG = {
  // 图像生成相关配置
  IMAGE_GENERATION: {
    pollingInterval: 1000, // 轮询间隔时间，默认为 1 秒
    maxRetries: 5,         // 最大重试次数，默认为 5 次
    timeout: 30000         // 任务超时时间，默认为 30 秒
  },

  // 视频生成相关配置
  VIDEO_GENERATION: {
    pollingInterval: 2000, // 轮询间隔时间，默认为 2 秒
    maxRetries: 10,       // 最大重试次数，默认为 10 次
    timeout: 600000        // 任务超时时间，默认为 10 分钟
  }
};

🔧 技术细节

本服务器基于 TypeScript 开发，遵循 Model Context Protocol (MCP) 规范。通过异步轮询机制处理长时间运行的图像和视频生成任务，确保任务的高效执行。同时，服务器支持与支持 MCP 的大语言模型（LLM）无缝协作，为用户提供便捷的图像和视频生成服务。

📄 许可证

文档中未提及许可证相关信息，故跳过此章节。

⚠️ 重要提示

API 权限：请确保您拥有有效的通义万相 API 访问密钥，并妥善保管。
异步处理：图像生成可能需要数秒到数十秒不等，视频生成耗时更长，需耐心等待。
轮询机制：服务器端的轮询间隔和重试次数应根据具体场景进行合理设置，避免资源浪费。
错误处理：对于失败的任务，请检查 error_message 以获取更多信息，并采取相应措施。

tongyi-wanx-mcp-server