🛝

ghub-deskによるGitHub組織の収集・再開・参照

に公開
AI
GitHub
OSS
Model Context Protocol
tech

取得と再開の運用ポイント

前回の記事では、
ghub-desk の概要とはじめ方について紹介しました。

GitHub の組織管理（メンバー、チーム、リポジトリなど）は標準の管理画面を使って運用していましたが、使い勝手に限界を感じる場面が増えてきました。
そこで、より効率的に管理するための CLI ツールとして ghub-desk を作りました。
MCP サーバーにも対応しており、AI エージェントと連携することで、日常的な言葉で組織情報を操作・管理できます

https://github.com/takihito/ghub-desk

リポジトリ内のpull_info.sh に組織情報を取得する手順をスクリプトとしてまとめています。

ユーザー周りの収集・参照

ユーザ周りの収集・参照 を実例ベースでまとめました。

  • ユーザ基本情報
    ghub-desk pull --users で取得し、ghub-desk view --users で一覧表示します。詳細な情報が必要な場合は --detail-users を指定し取得します。
  • ユーザがアクセスできるリポジトリ
    事前に --repos-users および --repos-teams を pull しておくことで、
    ghub-desk view --user-repos <username> から、直接権限・チーム経由権限の両方を一覧できます。
  • ユーザが所属するチーム
    ghub-desk pull --all-teams-users 実行後、
    ghub-desk view --user-teams <username> で確認できます。
    チーム情報から確認する場合は ghub-desk view --team-user <team-slug> を使用してください。

TIPS

  • 最初に init db でローカル DB を作成し、組織名とトークン（PAT または GitHub App のいずれか一方）を設定した config ファイルを用意します。
  • 規模の大きな組織では pull --all-repos-users や --all-repos-teams の完走に時間がかかります。セッション機構があるので、Ctrl+Cなどで途中停止しても再開することができます。
  • --stdout を指定すると、API レスポンスを標準出力に流しつつ DB へ保存できます。

ローカルへの取得と中断からの再開

  • pull コマンドで、組織・チーム・ユーザ情報をローカルの SQLite DB に保存できます。
    --users、--teams、--repos-users などを個別に実行しても、--all-* 系で一括取得しても問題ありません。
  • 取得中に SIGINT（Ctrl+C）や SIGTERM を受信しても、進捗とメタデータはセッションファイルに保存されるので、再実行時にはセッションを参照し、中断したページから自動的に取得を再開することができます。
  • GitHub API の呼び出し間隔は --interval-time で調整可能です（デフォルト 3 秒）。レートリミットや組織の運用ポリシーに応じて値を変更してください。

コマンド例

# 1. 初期セットアップ（DB 作成と設定ファイルの雛形生成）
ghub-desk init db
ghub-desk init config --target-file ~/.config/ghub-desk/config.yaml

# 2. 組織・チーム・ユーザの取得（Ctrl+C で中断しても途中から再開可能）
ghub-desk pull --users
ghub-desk pull --repos
ghub-desk pull --teams
ghub-desk pull --all-repos-users        # 全リポジトリの直接コラボレーター
ghub-desk pull --all-repos-teams        # 全リポジトリのチーム権限
ghub-desk pull --all-teams-users        # 全チームの所属ユーザ

# 3. ユーザ情報の参照
ghub-desk view --users                  # ユーザ基本情報一覧
ghub-desk view --user <username>           # 単一ユーザの詳細
ghub-desk view --user-teams <username>     # 所属チーム一覧
ghub-desk view --user-repos <username>     # アクセス可能リポジトリ（直接＋チーム）

# 4. チーム視点での参照
ghub-desk view --team-user <team-slug>  # チーム所属ユーザ
ghub-desk view --team-repos <team-slug> # チームがアクセス可能なリポジトリ

AI エージェントと MCP 連携について

AIエージェントが対応していれば resource URI でAPIのドキュメントを参照することができます。これに沿った形でAIが挙動してくれます。

  • resource URI:
    • resource://ghub-desk/mcp-overview
    • resource://ghub-desk/mcp-tools
    • resource://ghub-desk/mcp-safety

AIエージェントへのMCP設定

codex, Gemini, ClaudeDesktopでの挙動を確認できました。
現時点ではClaude Desktopが一番スムーズに動いてくれるように感じます。

  • claude_desktop_config.json
{
  "mcpServers": {
    "ghub-desk": {
      "command": "/usr/local/bin/ghub-desk",
      "args": ["mcp"]
    }
  }
}

Discussion