Hub Mirror MCP Server

🚀 Hub-Mirror MCP Server

一个基于 Model Context Protocol (MCP) 的自动化镜像搬运与加速工具。专为解决国内开发者拉取 Google (gcr.io)、Kubernetes (registry.k8s.io) 等海外容器镜像缓慢的问题而设计。

它能作为一个“AI 技能”无缝集成到 Cursor、Claude Desktop 等 AI 编辑器或对话器中，让你只需一句话即可完成镜像搬运。

✨ 核心特性

• 🤖 AI 驱动交互：无需繁琐配置，直接告诉 AI 你需要拉取的镜像名。
• 📦 零配置基建 (IaC)：初次运行自动同步 GitHub 工作流和秘钥，实现真正的一键启动。
• ⚡️ 异步加速架构：基于 GitHub Actions 搬运，国内满速拉取，规避大型镜像超时问题。
• 🛡️ 智能分批提交：内置镜像上限校验，支持交互式分批建议，防止任务熔断。
• 🛠️ 双传输协议：支持 Stdio (生产模式) 和 SSE (调试模式)。

🛠️ 快速开始

1. 准备工作

在开始前，请确保您手头有以下信息（详情参考 PREREQUISITES.md）：

• GitHub Token: 需要 repo 和 workflow 权限。
• 国内镜像仓库: 如阿里云 ACR 或腾讯云镜像仓库。
• 网络代理: 重要！ 本地环境需开启代理以确保能连通 GitHub。

2. 安装与启动

# 进入项目目录
cd hub-mirror

# 安装依赖
npm install

# 编译代码
npm run build

# 启动服务 (Stdio 模式)
npm start

3. 配置到 AI 客户端

您可以参考 操作指南 (OPERATION_GUIDE.md) 获取完整的配置 JSON 示例。

🏗️ 架构设计

graph LR
    User[AI Agent] -- MCP Protocol --> Server[MCP Server]
    Server -- API Trigger --> GH[GitHub Actions Engine]
    GH -- Pull/Push --> Registry[Overseas Registry]
    Registry -- Mirror --> Domestic[Domestic Registry]
    Domestic -- User Pull --> Dev[Local Dev Env]

详细架构分析请查看：MCP 架构分析报告。

📚 详细文档

• 📖 准备工作：硬件、账号与 Token 准备。
• 📖 操作指南：详细的部署、配置与常见问题处理（包含 MCP JSON 配置）。
• 📖 开发成果演示：功能点汇总与交互示例。

⚠️ 常见问题说明

• AI 查不到进度？：部分 AI 客户端存在工具调用频率限制（熔断），建议手动输入“继续”重置计数。
• 镜像拉取失败？：Server 会自动提取失败步骤并给出 GitHub 日志链接，方便一键排错。

📄 开源协议

本项目基于 MIT 协议。