harbor-registry-mcp

harbor-registry-mcp

Harbor Registry 用の MCP サーバーです。LLM エージェント（Claude Code、Cursor、OpenCode など）を使って、プロジェクト、リポジトリ、アーティファクトの一覧表示、ストレージレポートの実行、クリーンアップ候補の検索、タグのないアーティファクトや古いアーティファクトの削除ができます。安全対策も備えており、一括削除はデフォルトでドライランになります。

Python、FastMCP、stdio トランスポートを使用しています。

SaaS、セルフホスト、オンプレミスを問わず、あらゆる Harbor 2.x インスタンスで動作します。

なぜ新たな Harbor MCP が必要なのか？

コミュニティ製の Harbor MCP はいくつかあります（nomagicln/mcp-harbor、bupd/harbor-mcp-server）が、基本的な一覧表示／取得エンドポイントしか公開していません。この MCP では、ストレージレポート、クリーンアップ候補、タグのないアーティファクトの削除、ドライラン付きの古いアーティファクトの削除を追加しています。これらは、DevOps エンジニアがディスク容量を確保するために実際に必要とする操作です。

主な設計上の特長

• ツールのアノテーション — 読み取り専用ツールには readOnlyHint: True を設定し、破壊的な操作を行うツール（harbor_delete_*）には destructiveHint: True を設定して、MCP クライアントが確認を求めるようにしています。
• デフォルトでドライラン — 一括クリーンアップ（harbor_delete_untagged、harbor_delete_old_artifacts）では、実行するにはエージェントが 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 です。実際に削除するには、エージェントが明示的に 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