harbor-registry-mcp

harbor-registry-mcp

适用于 Harbor Registry 的 MCP 服务。让 LLM Agent（Claude Code、Cursor、OpenCode 等）列出项目、仓库和制品，生成存储报告、查找清理候选项，并删除未标记或较旧的制品——所有操作都带有安全保障（批量删除默认采用试运行模式）。

Python、FastMCP、stdio 传输。

适用于任何 Harbor 2.x 实例，无论是 SaaS 还是可自托管／本地部署。

为什么还要做另一个 Harbor MCP？

社区中已有一些 Harbor MCP（nomagicln/mcp-harbor、bupd/harbor-mcp-server），但它们只提供基本的列表／获取接口。本项目新增了存储报告、清理候选项、删除未标记制品，以及支持试运行的旧制品删除——这些正是 DevOps 工程师回收磁盘空间所需的操作。

设计亮点

• 工具注解——只读工具设有 readOnlyHint: True；有破坏性的工具（harbor_delete_*）带有 destructiveHint: True，以便 MCP 客户端请求确认。
• 默认采用试运行模式——两种批量清理操作（harbor_delete_untagged、harbor_delete_old_artifacts）都如此；Agent 必须传入 dry_run=False 才会执行。
• 结构化输出——每个工具都会返回类型化载荷（TypedDict）和 Markdown 摘要。
• 结构化错误——将 401／403／404／429／5xx 映射为可执行的提示。
• Pydantic 输入验证——验证每个参数。
• 漏洞快照——启用 with_scan_overview 后，harbor_list_artifacts 会显示扫描状态和数量。

功能（8 个工具）

发现与检查

• harbor_list_projects — 列出项目，包含仓库数量和可见性
• harbor_list_repos — 列出项目中的仓库
• harbor_list_artifacts — 列出仓库中的制品，包含标签／大小／扫描状态
• harbor_storage_report — 完整的项目存储明细（所有仓库 × 所有制品）

清理规划

• harbor_cleanup_candidates — 建议要删除的内容（未标记、从未拉取、旧版本）

清理执行（有破坏性）

• harbor_delete_artifact — 按标签或摘要删除单个制品
• harbor_delete_untagged — 删除项目／仓库中的所有未标记制品（默认采用试运行模式）
• harbor_delete_old_artifacts — 每个仓库保留最新的 N 个制品，删除其余制品（默认采用试运行模式）

安装

需要 Python 3.10+。

# via uvx (recommended)
uvx --from harbor-registry-mcp harbor-registry-mcp

# or via pipx
pipx install harbor-registry-mcp

配置

claude mcp add harbor -s project \
  --env HARBOR_URL=https://harbor.example.com \
  --env HARBOR_USERNAME='robot$your-robot' \
  --env HARBOR_PASSWORD=your-robot-token \
  --env HARBOR_SSL_VERIFY=true \
  -- uvx --from harbor-registry-mcp harbor-registry-mcp

或在 .mcp.json 中：

{
  "mcpServers": {
    "harbor": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "harbor-registry-mcp", "harbor-registry-mcp"],
      "env": {
        "HARBOR_URL": "https://harbor.example.com",
        "HARBOR_USERNAME": "robot$your-robot",
        "HARBOR_PASSWORD": "${HARBOR_PASSWORD}",
        "HARBOR_SSL_VERIFY": "true"
      }
    }
  }
}

检查：

claude mcp list
# harbor: uvx --from harbor-registry-mcp harbor-registry-mcp - ✓ Connected

环境变量

变量	必需	描述
HARBOR_URL	是	Harbor URL（末尾不要加斜杠）
HARBOR_USERNAME	是	Harbor 用户名——建议使用机器人账户
HARBOR_PASSWORD	是	密码或机器人令牌
HARBOR_SSL_VERIFY	否	true／false。默认值：true。

使用示例

• “生成项目 einvy-pub 的存储报告”
• “查找 qa-assistant 中的清理候选项——保留最新的 3 个”
• “删除 qa-assistant 中所有未标记的制品”
• “试运行删除 qa-assistant/pgvector-rag 中的旧制品，保留最新的 1 个”
• “einvy-pub/my-image 中有什么？”

安全

• 读取工具使用 readOnlyHint: True——无需确认。
• 删除工具使用 destructiveHint: True——客户端应请求确认。
• harbor_delete_untagged 和 harbor_delete_old_artifacts 均默认使用 dry_run=True；Agent 必须显式设置 dry_run=False 才会实际删除。
• harbor_cleanup_candidates 是只读的——它只会建议候选项，不会删除任何内容。

开发

git clone https://github.com/mshegolev/harbor-registry-mcp.git
cd harbor-registry-mcp
pip install -e '.[dev]'
pytest

许可证

MIT © Mikhail Shchegolev