Plan of Go app go gh-extensions

plan-go-gh-ext.md

プランを書きます。まず現状把握と設計の足場固めを並行でやります。スキル込みでプラン書きます。ローカル環境のexecute_codeですね。バックエンドはSSHなので直接ファイル操作はterminalで行きます。書き込むツールが見えないので、bash経由で保存します。利用可能なターミナル系ツールがTelegramから直接叩けない状況ですね (このセッションではterminal/read_file/write_fileがリストに無い)。プランの内容をチャットに直接お届けするので、ファイル保存はデスクトップ側のHermesで続きをお願いします。

---

📋 GitHub Cleanup MCP Server — 実装プラン

For Hermes: subagent-driven-development で task-by-task 実行

Goal: WebUIで一括削除できないGitHub操作を、MCPツールとして自然言語で操作可能にするサーバを作る。認証は gh auth token 経由なのでPAT管理不要。

Architecture: Go binary + 公式 modelcontextprotocol/go-sdk。gh api をラップ。トランスポートは stdio (Claude Desktop / Claude Code) と streamable-http (VS Code Copilot)。

Tech Stack: Go 1.23+, modelcontextprotocol/go-sdk, cli/go-gh/v2、stdlib中心。

---

なぜ作るか (背景)

リソース	WebUI一括削除	gh一括削除	我々のツール
Issues (絞り込み)	❌	⚠️ 限定的	✅
Projects v2 Lists	❌	❌	✅
Notifications	❌	❌	✅ 一括既読化
Stars	❌	❌	✅ トピックで一括解除
Releases (drafts)	❌	⚠️	✅
Copilot agent sessions	❌ (Stop/Archiveのみ)	❌ (issue #3072)	⏸ stub (API未公開)

⚠️と✅を埋める。⏸は将来API公開されたときに即対応できるようstubで枠を確保。

---

MCPツール一覧 (最終形)

全ての破壊的ツールはデフォルトdry-run。 confirm=true の2回目呼び出しで初めて実行する "plan/execute" 分離。

// 1. Issues
issues_delete(query: string, confirm: bool = false)
 → { matched: int, deletion_plan: [{number, title, labels, created_at}] }

// 2. Projects v2 Lists
projects_delete_lists(project_id: string, list_ids: [string], confirm: bool = false)
  → { matched: int, deletion_plan: [{list_id, name, item_count}] }

// 3. Notifications
notifications_mark_read(notification_ids: [string] | "all", confirm: bool = false)

// 4. Stars
stars_unstar(query: string, confirm: bool = false)
  → { matched: int, deletion_plan: [{full_name, description}] }

// 5. Releases
releases_delete(tag_pattern: string, draft_only: bool = true, confirm: bool = false)

// 6. Copilot agent sessions (API公開待ちstub)
copilot_agents_delete(state: "open" | "all", confirm: bool = false)
  → { note: "GitHub has not published a public API. Tracked at github.com/github/copilot-cli/issues/3072" }

// 7. Read-only
me() → { login, scopes, rate_limit_remaining }

---

ファイル構成

github-cleanup-mcp/
├── go.mod, go.sum, README.md, LICENSE
├── cmd/github-cleanup-mcp/main.go
├── internal/
│   ├── auth/ # GH_TOKEN + gh auth token fallback
│   ├── ghclient/     # REST + GraphQL wrapper、429自動retry
│   ├── tools/        # 7ツール + registry
│   ├── server/       # MCPサーバ配線
│   └── safety/       # dryrun/confirm guard
├── testdata/fixtures/
└── .github/workflows/ci.yml

---

Phase別タスク (19個, 推定10–12時間)

Phase 0 — Skeleton (5 tasks)

• 0.1 go mod init + main.goスケルトン → "no auth token"でexit1確認
• 0.2 MCP SDK導入 + stdio transport最小ループ
• 0.3 auth.Token() — env → gh auth token のフォールバック (TDD)
• 0.4 ghclient.Client — REST GET/DELETE + 429リトライ (httptestでTDD)
• 0.5 safety.Guard — DryRun or !Confirm 時は fn() を呼ばない

Phase 1 — Issues (基準実装, 3 tasks)

• 1.1 tools.Registry + server.New() 配線 (ダミー ping でスモーク)
• 1.2 issues_delete 本体 — /search/issues → plan → confirm=true で DELETE /repos/.../issues/{n} (注: GitHubは hard-delete せず close するので説明に明記)
• 1.3 フィクスチャベース統合テスト

Phase 2 — Projects v2 Lists (2 tasks)

• 2.1 GraphQL helper (REST helperと同形)
• 2.2 projects_delete_lists — query { node(id) { ... on ProjectV2 { lists { ... } } } } で計画 → deleteProjectV2List mutationで実行。mutationがpublic schemaに無い場合は明示的にエラー返却 (silent no-opは避ける)

Phase 3 — 残り4ツール (5 tasks、並列可)

• 3.1 notifications_mark_read — GET /notificationsページング → PATCH /notifications/threads/{id} or PUT /notifications (all)
• 3.2 stars_unstar — GET /search/repositories でトピック→リポ解決 → DELETE /user/starred/...
• 3.3 releases_delete — draft_only=true デフォルト (公開releaseは保護)
• 3.4 copilot_agents_delete — issue #3072 stub返却
• 3.5 me — GET /user + GET /rate_limit (確認不要)

Phase 4 — Polish (4 tasks)

• 4.1 README + Claude Desktop config例- 4.2 GitHub Actions CI (go test -race ./... + go vet)
• 4.3 go install手順 + v0.1.0タグ
• 4.4 起動バナー — transport/auth/rate_limit をstderrにJSONでログ

---

各タスクの粒度

Task 1 = 2〜5分の集中作業 (plan-skill方針):

• 失敗テスト書く → 実行して失敗確認 → 最小実装 → テストpass → commit

各タスクに Files: (Create/Modify/Test)、完全なテストコード、実装コード、コマンド、期待出力、commit メッセージを記載。

---

検証戦略

• Unit: 全パッケージ go test ./... exit 0
• Integration: httptest mock + testdata/fixtures
• Manual smoke: Claude Desktopに command: /usr/local/bin/github-cleanup-mcp を登録 → "wontfix ラベルの issue 全削除プランを見せて" → plan確認 → "実行して" で confirm → 実際にclose確認
• CI: push毎に go test -race ./...

---

リスク・トレードオフ・オープンQ1. Projects v2 list削除mutation — public schemaに無い可能性大。silent no-opではなく明示的エラーを返す設計。それでも計画立案は動くので将来API公開された瞬間に実装を追加できる構造。

2. Rate limit — N件削除 = Nリクエスト。--max=500 セーフティキャップ + --sleep=Xms で調整。READMEに明記。

3. 必要PATスコープ — repo, project, notifications, delete_repo (stars)。最小セットをREADMEに。

4. Copilot agent sessions — issue #3072。stubで schema を確定しておき、公開時に実装追加のみ。

5. MCP確認UI — 標準的な "本当に実行する?" プロンプトは未成熟。plan/confirm分離が現状の最も安全な interop ストーリー。

6. オープンQ (要返信):

   • Q1: 最初のターゲットorg/repoは? →推奨: GITHUB_DEFAULT_ORG 環境変数 + 呼び出し時 --org 上書き
   • Q2: --experimental フラグで内部API fallback を解禁する方針でいい? (Projects list削除がpublic mutation無い場合の逃げ道)

---

v0.1 で やらない こと

• Action workflows cleanup → gh-actions-cache 系extension領域
• Dependabot alerts bulk dismiss → 公開API無い
• GitHub Packages artifact cleanup → 同上
• マルチアカウント → v0.1は単一トークンで十分

---

進捗を進めるときの流れ

デスクトップ側でHermesに「プラン実行して」と頼むと、subagent-driven-development スキルが task-by-task で新鮮なサブエージェントをディスパッチ。各タスク完了後に spec compliance と code quality の2段階レビューが入ります。

Q1 と Q2 に答えてもらえれば、Task 0.1 から着手します。 それと、Phase分けや「やらないこと」リストに過不足あったら指摘してください。