ProjectPulse MCP

ProjectPulse MCP 🏥

AI アシスタント向けの GitHub リポジトリ健全性モニタリング — あらゆる言語、あらゆるリポジトリに対応します。

---

このModel Context Protocol（MCP）サーバーを使うと、AI アシスタントが会話から直接、あらゆる GitHub リポジトリの健全性、セキュリティ、CI/CD の状況、デリバリーメトリクスを分析できます。

📑 目次

• 機能
• 使用例
• ユースケース
• 前提条件
• クイックスタート
• ツール
• 互換性
• アーキテクチャ
• トランスポートモード
• 設定
• テスト
• コントリビューション
• ライセンス

✨ 機能

• 🏥 健全性スコア — A〜F のグレード、カテゴリ別の内訳、改善案を含む、0〜100 の包括的なスコア
• 🔒 セキュリティ — Dependabot アラートとOpenSSF Scorecardのチェックを組み合わせた評価（重み付けは 60/40）
• 📊 DORA メトリクス — GitHub のデータからDORA メトリクスの代替指標を算出：デプロイ頻度、リードタイム、変更失敗率、MTTR
• 🔍 コードスキャン — CodeQL などのコードスキャンアラートを、重大度、メッセージ、作成日とともに表示
• 📦 依存関係分析 — 重大度によるフィルタリングに対応した Dependabot アラート
• ⚙️ CI/CD の状況 — 最近の GitHub Actions ワークフロー実行と結果
• 📋 リポジトリ情報 — スター、フォーク、言語、ライセンスなどの一般的なメタデータ
• 📝 ベストプラクティス — オープンソースリポジトリの品質を評価する 12 項目のチェックリスト（README、LICENSE、SECURITY.md、テンプレート、ブランチ保護など）と A〜F のグレード

📸 使用例

すべてのスクリーンショットは、MCP Inspectorからリアルタイムで取得したものです。

get_health_score — カテゴリー別内訳付きのA～F評価

get_dora_metrics — GitHubデータに基づくDORAデリバリーメトリクス

compare_repos — ヘルススコアの並列比較ランキング

check_ci_status — 最近のGitHub Actionsワークフロー実行履歴

get_repo_health — リポジトリのメタデータと統計情報

analyze_dependencies — Dependabotの脆弱性アラート

check_best_practices — A～F評価付きのオープンソースリポジトリ品質チェックリスト

💡 使用例

これらのプロンプトをコピーして、Claude、Cursor、Windsurf、またはMCP互換のアシスタントに貼り付けてください。

デューデリジェンス — ライブラリの採用

"facebook/reactが本番環境で使用できる状態か評価してください。ヘルススコア、セキュリティの脆弱性（DependabotとCodeQL）、CIパイプラインが安定して成功しているかを確認してください。"

使用するツール：get_health_score、analyze_dependencies、analyze_code_scanning、check_ci_status

代替候補の比較

"expressjs/express、fastify/fastify、koajs/koaのどれを選ぶべきか検討しています。それぞれのヘルススコアを比較し、技術的リスクが最も低いものを教えてください。"

使用するツール：compare_repos

スプリントレビュー — DORAメトリクス

"vercel/next.jsの過去30日間のDORAメトリクスを算出してください。スプリントレビューでデリバリーパフォーマンスを発表したいです。"

使用するツール：get_dora_metrics

トレンドのモニタリング

"microsoft/vscodeのヘルススコアを確認してください。前回確認したときから改善しましたか、それとも悪化しましたか？"

使用するツール：get_health_score（繰り返し呼び出すとトレンド比較も含まれます）

簡易セキュリティ監査

"pallets/flaskのセキュリティ監査を実施してください。Dependabotのアラート、CodeQLの脆弱性、CIのビルド状況を確認し、全体像を教えてください。"

使用するツール：analyze_dependencies、analyze_code_scanning、check_ci_status

---

📋 前提条件

• Node.js v18以降 — ダウンロード
• npm（Node.jsに同梱）
• GitHub Personal Access Token（公開リポジトリでは任意、プライベートリポジトリとセキュリティデータでは必須）

🚀 クイックスタート

Claude Code（CLI）

claude mcp add projectpulse -- npx projectpulse-mcp

注記： Claude Codeを実行するディレクトリに、GITHUB_TOKENを記載した.envファイルが必要です。

Claude Desktop

ステップ 1：GitHub トークンを取得する

1. GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens に移動します
2. 名前を付けます（例：projectpulse）
3. 監視するリポジトリを選択します（または「All repositories」）
4. Permissions で、次の項目に Read-only アクセスを許可します：
   • Code scanning alerts
   • Dependabot alerts
   • Metadata（デフォルトで有効）
5. Generate token をクリックし、トークンをコピーします

ステップ 2：Claude Desktop を設定する

1. Claude Desktop を開きます
2. Settings（歯車アイコン）> Developer > Edit Config に移動します
3. claude_desktop_config.json が開きます。"mcpServers" 内に projectpulse のエントリーを追加します：

{
  "mcpServers": {
    "projectpulse": {
      "command": "npx",
      "args": ["-y", "projectpulse-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_paste_your_token_here"
      }
    }
  }
}

4. ファイルを保存し、Claude Desktop を再起動します

ステップ 3：動作を確認する

新しい Claude Desktop の会話で、次のように尋ねてみます：

「facebook/react のヘルススコアを確認して」

Claude は get_health_score ツールを呼び出し、詳細な内訳とともに A～F の評価を返します。

トラブルシューティング

問題	解決方法
ツールが表示されない	設定ファイルを編集した後、Claude Desktop を再起動します
「Rate limit exceeded」エラー	設定で GITHUB_TOKEN が正しく設定されていることを確認します
Dependabot／CodeQL のデータがない	トークンに Code scanning alerts と Dependabot alerts の権限が必要です
npx が見つからない	Node.js（v18 以降）をインストールし、npx が PATH に含まれていることを確認します

その他の MCP クライアント（Cursor、Windsurf など）

次の設定で新しい MCP サーバーを構成します：

• Transport：stdio
• Command：npx
• Arguments：-y projectpulse-mcp
• Environment：GITHUB_TOKEN = お使いの GitHub PAT

🛠️ ツール

get_health_score

A～F の評価を含む 0～100 のヘルススコアを算出します。CI の信頼性（25％）、コードの鮮度（20％）、セキュリティ態勢（25％）、コミュニティの活動（15％）、メンテナンスの品質（15％）という、重み付けされた 5 つのカテゴリを評価します。スコアが低いカテゴリに対して、実行可能な改善案を返します。同じリポジトリに対して繰り返し呼び出すと、前回の確認からのスコア変化を示す 傾向比較が含まれます。複数の GitHub API エンドポイントと OpenSSF Scorecard に問い合わせます。

副作用： 傾向のスナップショットをローカルディスク（~/.projectpulse/snapshots/）に保存します。

入力： owner、repo 質問例： 「microsoft/vscode のヘルススコアは？」

get_dora_metrics

公開 GitHub データからプロキシ DORA メトリクスを算出します：デプロイ頻度（リリースから算出）、変更のリードタイム（PR の作成からマージまで）、変更失敗率（CI の失敗率）、平均復旧時間（CI の失敗から次の成功まで）。データが不十分なメトリクスは null を返します。複数の GitHub API エンドポイント（リリース、プルリクエスト、アクション）に問い合わせるため、単一エンドポイントを使うツールより API の使用量が多くなります。

入力： owner、repo、days（任意、7～90、デフォルトは 30） 質問例： 「過去 60 日間の vercel/next.js の DORA メトリクスを見せて」

compare_repos

2～5 個のリポジトリのヘルススコアを並べて比較します。各リポジトリのヘルスの内訳全体を、スコア順に返します。代替候補の評価や、プロジェクトと類似プロジェクトとのベンチマークに役立ちます。API 呼び出し数は、比較するリポジトリ数に応じて増加します。

入力： repos（{owner, repo} の配列） 質問例： 「expressjs/express、fastify/fastify、koajs/koa のヘルスを比較して」

get_repo_health

リポジトリの基本的なメタデータ（スター数、フォーク数、オープンな Issue の数、主要言語、ライセンス、最終プッシュ日、デフォルトブランチ、アーカイブ状態）を取得します。概要を手早く確認する場合に使います。算出された評価を確認するには、代わりに get_health_score を使います。

入力： owner、repo 質問例： 「torvalds/linux の一般情報を教えて」

analyze_dependencies

脆弱なパッケージ依存関係（npm、pip、Maven など）に関する Dependabot のセキュリティアラートを、重大度（critical、high、medium、low）ごとにグループ化して一覧表示します。特定の重大度レベルで絞り込むこともできます。Dependabot alerts 権限を持つトークンが必要です。

入力： owner、repo、severity（任意） 質問例： 「my-org/my-app の重大な依存関係の脆弱性を表示して」

check_ci_status

GitHub Actions の 最新の CI/CD ワークフロー実行について、ステータス（success、failure、in_progress）、結論、ブランチ、所要時間、タイムスタンプを返します。デプロイやマージの前にビルドが成功しているか確認するのに便利です。

入力： owner、repo、limit（任意、デフォルトは 10） 質問例： 「facebook/react の CI ビルドは成功していますか？」

analyze_code_scanning

CodeQL などのコードスキャンアラートについて、ルール ID、重大度、脆弱性のメッセージ、影響を受けるファイルと行番号、作成日を一覧表示します。Code scanning alerts 権限を持つトークンが必要です。オプションで CodeQL スキャンを開始し、結果を待つこともできます（Advanced Setup が必要で、Default Setup では利用できません）。

入力： owner、repo、trigger_scan（任意、デフォルトは false）、poll_timeout_seconds（任意、デフォルトは 300）、poll_interval_seconds（任意、デフォルトは 15） 質問例： 「my-org/my-api にコードスキャンで検出された脆弱性はありますか？」

check_best_practices

リポジトリが オープンソースコミュニティのベストプラクティスに従っているかを評価します。README、LICENSE、SECURITY.md、CONTRIBUTING.md、CODE_OF_CONDUCT、Issue／PR テンプレート、ブランチ保護、Dependabot の設定、CI/CD ワークフロー、説明、トピックを対象に、重み付けされた 12 項目をチェックします。重み付けされた 0～100 のスコアと A～F の評価、各チェックの合格／不合格／不明のステータス、および不足項目ごとの具体的な提案を返します。ブランチ保護のチェックには管理者トークンのアクセスが必要です。アクセスできない場合は減点されずに「不明」として返されます。

入力： owner、repo 質問例： 「my-org/my-repo はオープンソースのベストプラクティスに従っていますか？」

ping

シンプルな接続確認です。メッセージとともに「pong」を返します。MCP サーバーが実行中かどうかの確認に使用します。

入力： message

🆕 新機能

HTTP トランスポート（v1.7.0）

ProjectPulse は stdio に加えて、Streamable HTTP トランスポートに対応しました。これにより、スタンドアロンの HTTP サーバーとして実行できます。Docker コンテナ、リモート環境へのデプロイ、異なるランタイム間の連携（例：ネットワーク経由で Node.js の MCP ツールを利用する .NET クライアント）に最適です。

デフォルトの動作に変更はありません。npx projectpulse-mcp は引き続き stdio を使用します。HTTP モードを有効にするには、次のようにします。

MCP_TRANSPORT=http MCP_PORT=3000 node dist/index.js

環境変数	デフォルト	説明
MCP_TRANSPORT	stdio	トランスポートモード：stdio または http
MCP_PORT	3000	HTTP サーバーのポート（MCP_TRANSPORT=http の場合のみ使用）

Docker の例：

projectpulse:
  image: node:22-slim
  command: >-
    sh -c "npm install -g projectpulse-mcp &&
           node /usr/local/lib/node_modules/projectpulse-mcp/dist/index.js"
  environment:
    - MCP_TRANSPORT=http
    - MCP_PORT=3000
    - GITHUB_TOKEN=${GITHUB_TOKEN}

ヘルスチェックのエンドポイントは GET / で利用できます（サーバー名とバージョンを含む JSON を返します）。MCP プロトコルのエンドポイントは POST /mcp です。

OpenSSF Scorecard との統合

セキュリティスコアは Dependabot アラート（60%）と OpenSSF Scorecard のチェック（40%）を組み合わせ、より包括的な評価を提供するようになりました。セキュリティに関連する 12 項目を評価します。Scorecard がないリポジトリでは、Dependabot のみを使ったスコアに自動的に切り替わります。

DORA メトリクス

新しい get_dora_metrics ツールは、公開されている GitHub データから代理となる DORA メトリクスを算出します。

メトリクス	ソース	単位
デプロイ頻度	リリース	リリース／週
変更のリードタイム	PR の作成 → マージ	時間（中央値）
変更失敗率	CI ワークフローの結論	パーセント
平均復旧時間	CI の失敗 → 次の成功	時間（中央値）

データが不十分な場合、メトリクスは null を返します。どのリポジトリでも安全に利用できます。

🔌 互換性

ProjectPulse は、MCP 互換クライアントであればどれでも使用できます。以下でテスト済みです。

クライアント	トランスポート	ステータス
Claude Desktop	stdio	✅ テスト済み
Claude Code (CLI)	stdio	✅ テスト済み
Cursor	stdio	✅ テスト済み
Windsurf	stdio	✅ テスト済み
MCP Inspector	stdio	✅ テスト済み
Docker / リモート	HTTP	✅ テスト済み
任意の MCP クライアント	stdio または HTTP	✅ 互換性あり

🏗️ アーキテクチャ

┌─────────────────────────────────────────────────┐
│                  MCP Client                     │
│        (Claude, Cursor, Windsurf, etc.)         │
└────────────────────┬────────────────────────────┘
                     │ stdio or HTTP
┌────────────────────▼────────────────────────────┐
│            ProjectPulse MCP Server              │
│                                                 │
│  ┌─────────────┐  ┌─────────────┐              │
│  │  Tool Layer  │  │  Transport  │              │
│  │  (8 tools)   │  │ stdio/HTTP  │              │
│  └──────┬──────┘  └─────────────┘              │
│         │                                       │
│  ┌──────▼──────┐  ┌─────────────┐              │
│  │  GitHub API  │  │   OpenSSF   │              │
│  │  (Octokit)   │  │  Scorecard  │              │
│  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────┘

• ツールレイヤー：8 個の独立したツールがあり、それぞれ専用のファイルに配置されています（src/tools/）
• GitHub API：すべての呼び出しは、レート制限処理を備えた共有 Octokit クライアント（src/github/client.ts）を経由します
• OpenSSF Scorecard：セキュリティスコアの評価に、公開 API を統合しています
• 入力検証：MCP 境界で Zod スキーマを使用します
• トランスポート：stdio（デフォルト）または Streamable HTTP。環境変数で設定できます

🚢 トランスポートモード

	stdio（デフォルト）	HTTP
有効化	npx projectpulse-mcp	MCP_TRANSPORT=http node dist/index.js
最適な用途	ローカル MCP クライアント	Docker、リモート、ランタイム間の接続
ヘルスチェック	該当なし	GET / → JSON
MCP エンドポイント	stdin/stdout	POST /mcp
必要な設定	なし	MCP_TRANSPORT=http、必要に応じて MCP_PORT

Docker の例については、新機能：HTTP トランスポートを参照してください。

⚙️ 設定

GITHUB_TOKEN

レート制限を回避し、セキュリティデータ（Dependabot、CodeQL アラート）にアクセスするには必須です。

オプション A：Fine-grained PAT（推奨）

1. Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. 対象のリポジトリを選択します
3. 次の項目に読み取り専用アクセスを付与します：
   • Code scanning alerts
   • Dependabot alerts
   • Metadata（デフォルト）

オプション B：Classic Token repo + security_events スコープを指定して生成します。

トークンの設定方法：

• Claude Desktop：claude_desktop_config.json に設定します（クイックスタートを参照）
• Claude Code / ローカル：.env ファイルを作成します：

  GITHUB_TOKEN=ghp_your_token_here
  

🧪 テスト

8 個のツールすべてに専用のテストスイートがあります。テストでは、GitHub API のレスポンスをモックし、Vitest を使用します。

# Run all tests
npm test

# Watch mode
npm run test:watch

ツール	テストファイル	ステータス
get_health_score	src/tools/get-health-score.test.ts	✅
get_dora_metrics	src/tools/get-dora-metrics.test.ts	✅
compare_repos	src/tools/compare-repos.test.ts	✅
get_repo_health	src/tools/get-repo-health.test.ts	✅
analyze_dependencies	src/tools/analyze-dependencies.test.ts	✅
check_ci_status	src/tools/check-ci-status.test.ts	✅
analyze_code_scanning	src/tools/analyze-code-scanning.test.ts	✅
check_best_practices	src/tools/check-best-practices.test.ts	✅

👤 作者

alexbypa — GitHub · npm

🤝 コントリビューション

コントリビューション、課題、機能リクエストを歓迎します！

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. テストを実行し（npm test）、すべて成功することを確認します
4. 変更をコミットします
5. ブランチにプッシュし、プルリクエストを作成します

未対応のタスクやバグ報告については、課題ページを参照してください。

⭐ 応援する

このプロジェクトが役に立ったら、スターを付けてください！

📝 ライセンス

MIT — 詳細は LICENSE ファイルを参照してください。