核心架构¶
本部分深入探讨 MiniMax-MCP 服务器的内部设计、通信机制和配置系统。
系统设计¶
MiniMax-MCP 服务器基于 FastMCP 框架构建，充当 MCP 客户端（如 Claude Desktop, Cursor）与 MiniMax 后端 API 之间的桥梁。
设计原则： - 协议兼容：严格遵循 Model Context Protocol (MCP)，确保与兼容客户端的互操作性。 - 模块化：将不同的 MiniMax 功能（如 TTS、图像生成、视频生成）封装为独立的 MCP 工具，便于管理和扩展。 - 配置驱动：通过环境变量进行灵活配置，包括 API 密钥、主机地址、资源处理模式等，适应不同部署环境。 - 错误处理：提供清晰、具体的错误信息反馈给客户端，帮助用户快速定位和解决问题。
来源：基于 server.py 描述和 README.md 推断
通信模式¶
服务器支持两种与 MCP 客户端的通信传输类型：
| 特性 | stdio (标准输入/输出) | SSE (Server-Sent Events) |
|---|---|---|
| 运行环境 | 适用于本地运行 | 可本地运行，也适合云端部署 |
| 通信方式 | 通过进程的标准输入/输出流 | 通过 HTTP 网络连接 |
| 输入资源 | 支持处理本地文件路径或 URL | 云端部署时，推荐使用 URL |
选择哪种模式通常由 MCP 客户端决定和配置。
来源：README.md
配置系统¶
服务器的主要配置通过环境变量完成。关键变量包括：
MINIMAX_API_KEY: MiniMax API 密钥 (必需)。MINIMAX_API_HOST: MiniMax API 主机地址 (必需)。MINIMAX_MCP_BASE_PATH: 本地资源存储路径 (可选, 仅在MINIMAX_API_RESOURCE_MODE=local时使用)。MINIMAX_API_RESOURCE_MODE: 资源返回模式 (url或local, 可选, 默认为url)。MINIMAX_MCP_LOG_LEVEL: 服务器日志级别 (可选, 如INFO,DEBUG)。
客户端配置: MCP 客户端（如 Claude Desktop, Cursor）通常使用 JSON 文件来配置要启动的 MCP 服务器，包括指定服务器启动命令 (uvx minimax-mcp -y) 以及传递上述环境变量。
来源：README.md, server.py
错误处理¶
服务器包含基本的错误处理逻辑：
- 认证错误: 如果 MINIMAX_API_KEY 与 MINIMAX_API_HOST 区域不匹配，服务器会返回类似 Invalid API key 的错误。
- API 调用错误: 当调用 MiniMax 后端 API 失败时，服务器会尝试将 API 返回的错误信息传递给客户端。
- 工具内部错误: 服务器代码会捕获并处理预期的内部错误，并向客户端返回信息性的错误消息。
来源：README.md, server.py