mcpcn-image-hd-zoom 0.1.13

MCP服务器：图像超分辨率工具，提供AI图像放大和清晰度增强功能

阿里云图像超分辨率 MCP 服务器

基于阿里云视觉智能开放平台的图像超分辨率 MCP 服务器，通过 AI 算法将图像放大 2-4 倍并显著提升清晰度。

✨ 核心特性

• 🚀 支持任意 URL：无需上传到阿里云 OSS，支持任意可访问的 HTTP/HTTPS 图片链接
• 🔍 AI 超分辨率：智能算法放大图像同时保持细节清晰
• 📐 灵活放大：支持 2 倍、3 倍、4 倍放大
• 🎨 格式支持：输出 JPG 或 PNG 格式
• ⚙️ 质量可控：可调节输出质量（1-100）
• ⚡ 混合模式：2分40秒内同步返回结果，超时则自动切换为后台异步执行

📦 安装

方式 1：使用 uvx（推荐）

无需安装，直接运行：

uvx mcp-image-super-resolution

方式 2：通过 pip 安装

pip install mcp-image-super-resolution

方式 3：从源码安装

git clone https://github.com/fengjinchao/mcp-image-super-resolution.git
cd mcp-image-super-resolution
pip install -e .

🔑 配置阿里云凭证

1. 获取 AccessKey

1. 访问 阿里云 AccessKey 管理页面
2. 创建 AccessKey ID 和 AccessKey Secret
3. 如使用 RAM 用户，需授予 AliyunVIAPIFullAccess 权限

2. 配置环境变量

export ALIBABA_CLOUD_ACCESS_KEY_ID="你的 AccessKey ID"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="你的 AccessKey Secret"

🔧 在 MCP 客户端中配置

Claude Desktop 配置示例

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "aliyun-image-super-resolution": {
      "command": "uvx",
      "args": ["mcp-image-super-resolution"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "你的 AccessKey ID",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "你的 AccessKey Secret"
      }
    }
  }
}

Cline / Kiro 配置示例

在 .cline/mcp_settings.json 或 .kiro/settings/mcp.json 中添加：

{
  "mcpServers": {
    "aliyun-image-super-resolution": {
      "command": "mcp-image-super-resolution",
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "你的 AccessKey ID",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "你的 AccessKey Secret"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

📖 使用指南

工具 1: submit_super_resolution_task

提交图像超分辨率处理任务（混合模式）。

工作模式

• 同步模式：任务在 2分40秒 内完成时，直接返回处理结果和下载链接
• 异步模式：任务超过 2分40秒 时，返回任务ID，后台继续处理，完成后会收到推送通知

参数

参数	类型	必填	默认值	说明
image_url	string	✅	-	图片 URL（支持任意可访问的 HTTP/HTTPS 链接）
scale	int	❌	2	放大倍数（2、3 或 4）
output_format	string	❌	jpg	输出格式（jpg 或 png）
output_quality	int	❌	100	输出质量（1-100）

示例

对话示例：

用户：帮我把这张图片放大 3 倍
https://example.com/my-photo.jpg

返回结果（同步模式 - 任务快速完成）：

{
  "status": "success",
  "message": "✅ Image super-resolution completed",
  "job_id": "ABC123-DEF456-GHI789",
  "request_id": "ABC123-DEF456-GHI789",
  "scale": 3,
  "output_url": "https://viapi-cn-shanghai.oss-cn-shanghai.aliyuncs.com/...",
  "output_format": "jpg",
  "elapsed_seconds": 8
}

返回结果（异步模式 - 任务超时）：

{
  "status": "async",
  "message": "Image processing takes longer time, switched to background async execution",
  "job_id": "ABC123-DEF456-GHI789",
  "request_id": "ABC123-DEF456-GHI789",
  "scale": 3,
  "tip": "Task will execute in background, push notification will be sent when completed."
}

---

工具 2: query_task

查询异步任务的处理状态和结果（可选）。

使用场景

在混合模式下，大多数任务会在 2分40秒 内完成并直接返回结果。此工具仅在以下情况需要使用：

1. 任务因超时切换为异步模式时
2. 用户主动要求查看进度时

异步任务完成后会自动发送推送通知。

参数

参数	类型	必填	说明
job_id	string	✅	任务 ID（由 submit_super_resolution_task 返回）

示例

对话示例：

用户：查询任务 ABC123-DEF456-GHI789 的状态

返回结果（处理中）：

{
  "success": true,
  "job_id": "ABC123-DEF456-GHI789",
  "status": "PROCESSING",
  "message": "任务处理中，请稍后再查询"
}

返回结果（处理成功）：

{
  "success": true,
  "job_id": "ABC123-DEF456-GHI789",
  "status": "PROCESS_SUCCESS",
  "output_url": "https://viapi-cn-shanghai.oss-cn-shanghai.aliyuncs.com/...",
  "message": "任务处理成功"
}

返回结果（处理失败）：

{
  "isError": true,
  "error_code": "InvalidImage.Format",
  "error_message": "图片格式不支持，请使用 JPG 或 PNG 格式"
}

📋 任务状态说明

状态	说明
SUBMITTED	任务已提交
PROCESSING	任务处理中
PROCESS_SUCCESS / SUCCESS	任务处理成功
PROCESS_FAILED / FAILED	任务处理失败

⚠️ 注意事项

1. 服务开通：需要先开通阿里云视觉智能开放平台服务
2. 费用说明：API 调用会产生费用，请查看阿里云定价文档
3. 图片要求：
   • 支持任意可访问的 HTTP/HTTPS URL（无需上传到阿里云 OSS）
   • 建议图片大小不超过 4MB
   • 图片 URL 必须可从公网访问（不支持 localhost、内网 IP 或需要认证的 URL）
4. 处理时间：通常为 3-10 秒，视图片大小而定
5. 混合模式：
   • 任务提交后自动开始轮询查询（每3秒一次）
   • 2分40秒内完成：直接返回处理结果和下载链接
   • 超过2分40秒：返回任务ID，切换为后台异步执行，完成后会收到推送通知
   • 异步任务可使用 query_task 手动查询状态

🔧 常见问题

问题 1：图片下载失败

错误信息：

Error: 无法下载图片: HTTP Error 403: Forbidden

原因：提供的 URL 无法访问或需要认证

解决方案：

• ✅ 确保图片 URL 可以从公网访问
• ✅ 在浏览器中测试 URL 是否能打开
• ✅ 避免使用 localhost、内网 IP 或需要登录的 URL
• ✅ 检查图片服务器是否允许外部访问（CORS、防盗链等）

问题 2：任务一直处于 PROCESSING 状态

原因：图片较大或服务繁忙

解决方案：

• 等待更长时间（最多 30 秒）
• 如果超过 1 分钟仍未完成，可能是服务异常，请重新提交

问题 3：凭证错误

错误信息：

Error: InvalidCredentials

解决方案：

• 检查 AccessKey ID 和 Secret 是否正确
• 确认 RAM 用户是否有 AliyunVIAPIFullAccess 权限
• 检查环境变量是否正确配置

🛠️ 技术实现

本项目优先使用阿里云 SDK 的普通请求方法，将图片 URL 直接传给阿里云：

1. URL 直传：将 image_url 作为 ImageUrl 参数提交给阿里云
2. 回退处理：如果阿里云无法拉取该 URL，则从提供的 URL 下载图片到内存，并通过 SDK 的 Advance 方法作为图片流提交
3. 异步查询：通过 job_id 查询处理结果

这种方式优先避免在 MCP 服务端中转图片二进制；仅在 URL 直传失败时才回退到流上传。

📚 相关文档

• 阿里云图像超分辨率 API 文档
• Model Context Protocol (MCP)
• FastMCP 框架
• 阿里云 VIAPI 使用案例

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE 文件

👨‍💻 作者

fengjinchao - [e-mail]

---

💡 提示：如果你觉得这个项目有用，请给个 ⭐ Star！