Tongyi Wanx MCP Server

🚀 通义万相 MCP 服务器

这是一个基于 TypeScript 的 Model Context Protocol (MCP) 服务器，专门提供阿里云通义万相的文生图(Text-to-Image)和文生视频(Text-to-Video)能力。该服务器借助 MCP 协议，允许大语言模型（LLM）直接调用通义万相的图像和视频生成 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 无缝协作。

📦 安装指南

安装依赖

npm install

构建项目

npm run build

启动服务器

npm start

💻 使用示例

基础用法

以百炼平台为例，配置服务器的使用示例：

{
  "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 分钟
  }
};

🔧 技术细节

环境要求

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

注意事项

⚠️ 重要提示

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

📄 参考资料

• 通义万相 API 文档
• Model Context Protocol (MCP) 规范