DeepSource MCP Server

DeepSource MCP サーバー

DeepSource と連携し、AI アシスタントがコード品質のメトリクス、問題、分析結果にアクセスできるようにする Model Context Protocol（MCP）サーバーです。

目次

• 概要
• クイックスタート
• インストール
• 設定
• 利用可能なツール
• 使用例
• アーキテクチャ
• 開発
• トラブルシューティングと FAQ
• コントリビューション
• ライセンス
• 外部リソース

概要

DeepSource MCP サーバーを使うと、AI アシスタントは Model Context Protocol を通じて、Claude などの DeepSource のコード品質分析機能を利用できます。この連携により、AI アシスタントは次のことができます。

• コードのメトリクスと分析結果を取得する
• アナライザー、パス、タグで問題にアクセスし、絞り込む
• 品質ステータスを確認し、しきい値を設定する
• プロジェクトの品質を経時的に分析する
• セキュリティコンプライアンスレポート（OWASP、SANS、MISRA-C）にアクセスする
• 依存関係の脆弱性を監視する
• 品質ゲートとしきい値を管理する

クイックスタート

1. DeepSource API キーを取得する

1. DeepSource アカウントにログインします
2. Settings → API Access に移動します
3. Generate New Token をクリックします
4. API キーをコピーし、安全に保管します

2. Claude Desktop にインストールする

1. Claude Desktop を開きます
2. Settings → Developer → Edit Config に移動します
3. 次の設定を mcpServers セクションに追加します。

{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}

4. Claude Desktop を再起動します

3. 接続をテストする

Claude に「アクセスできる DeepSource プロジェクトを教えてください」と尋ねます。

正しく設定されていれば、Claude は利用可能なプロジェクトを一覧表示します。

インストール

NPX（推奨）

DeepSource MCP サーバーを使う最も簡単な方法です。

{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "INFO",
        "RETRY_MAX_ATTEMPTS": "3",
        "RETRY_BASE_DELAY_MS": "1000",
        "RETRY_MAX_DELAY_MS": "30000",
        "RETRY_BUDGET_PER_MINUTE": "10",
        "CIRCUIT_BREAKER_THRESHOLD": "5",
        "CIRCUIT_BREAKER_TIMEOUT_MS": "30000"
      }
    }
  }
}

Docker

コンテナー環境で使用する場合：

{
  "mcpServers": {
    "deepsource": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DEEPSOURCE_API_KEY",
        "-e",
        "LOG_FILE=/tmp/deepsource-mcp.log",
        "-v",
        "/tmp:/tmp",
        "sapientpants/deepsource-mcp-server"
      ],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}

ローカル開発

開発またはカスタマイズを行う場合：

{
  "mcpServers": {
    "deepsource": {
      "command": "node",
      "args": ["/path/to/deepsource-mcp-server/dist/index.js"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

設定

環境変数

変数	必須	デフォルト	説明
DEEPSOURCE_API_KEY	はい	-	認証に使用する DeepSource API キー
LOG_FILE	いいえ	-	ログファイルのパス。設定されていない場合、ログは書き込まれません
LOG_LEVEL	いいえ	DEBUG	最小ログレベル：DEBUG、INFO、WARN、ERROR
RETRY_MAX_ATTEMPTS	いいえ	3	失敗したリクエストの最大再試行回数
RETRY_BASE_DELAY_MS	いいえ	1000	指数バックオフの基準遅延時間（ミリ秒）
RETRY_MAX_DELAY_MS	いいえ	30000	再試行間の最大遅延時間（ミリ秒）
RETRY_BUDGET_PER_MINUTE	いいえ	10	すべての操作を通じて1分間に許可される最大再試行回数
CIRCUIT_BREAKER_THRESHOLD	いいえ	5	サーキットブレーカーが開くまでの失敗回数
CIRCUIT_BREAKER_TIMEOUT_MS	いいえ	30000	サーキットブレーカーが復旧を試みるまでの時間（ミリ秒）

パフォーマンスに関する考慮事項

• ページネーション：応答時間とデータの完全性のバランスを取るため、適切なページサイズ（10～50項目）を使用してください
• 自動再試行：サーバーは、以下を備えたインテリジェントな再試行ロジックを実装しています：
  • サンダリングハードを防ぐジッター付き指数バックオフ
  • カスケード障害を防ぐサーキットブレーカーパターン
  • リソース消費を制限する再試行予算
  • API からの Retry-After ヘッダーの尊重
• レート制限：レート制限されたリクエスト（429）は、適切な遅延を設けて自動的に再試行されます
• フォールトトレランス：一時的な障害（ネットワーク、502、503、504）は適切に処理されます
• キャッシュ：結果はキャッシュされません。頻繁にアクセスするデータにはキャッシュの実装を検討してください

利用可能なツール

1. projects

利用可能なすべての DeepSource プロジェクトを一覧表示します。

パラメーター：なし

応答例：

[
  {
    "key": "https://[email protected]",
    "name": "my-python-project"
  }
]

2. project_issues

フィルタリングとページネーションを使用して、DeepSource プロジェクトの課題を取得します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
first	number	いいえ	返す項目数（前方ページネーション）
after	string	いいえ	前方ページネーション用のカーソル
last	number	いいえ	返す項目数（後方ページネーション）
before	string	いいえ	後方ページネーション用のカーソル
path	string	いいえ	ファイルパスで課題をフィルタリング
analyzerIn	string[]	いいえ	アナライザーでフィルタリング（例：["python", "javascript"]）
tags	string[]	いいえ	課題タグでフィルタリング

応答例：

{
  "issues": [
    {
      "id": "T2NjdXJyZW5jZTpnZHlqdnlxZ2E=",
      "title": "Avoid using hardcoded credentials",
      "shortcode": "PY-D100",
      "category": "SECURITY",
      "severity": "CRITICAL",
      "file_path": "src/config.py",
      "line_number": 42
    }
  ],
  "totalCount": 15,
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "YXJyYXljb25uZWN0aW9uOjQ="
  }
}

3. runs

フィルタリングして、プロジェクトの解析実行一覧を取得します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
first	number	いいえ	返す項目数（前方ページネーション）
after	string	いいえ	前方ページネーション用のカーソル
last	number	いいえ	返す項目数（後方ページネーション）
before	string	いいえ	後方ページネーション用のカーソル
analyzerIn	string[]	いいえ	アナライザーでフィルタリング

4. run

特定の解析実行の詳細を取得します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
runIdentifier	string	はい	runUid（UUID）または commitOid（コミットハッシュ）
isCommitOid	boolean	いいえ	runIdentifier がコミットハッシュかどうか（デフォルト：false）

5. recent_run_issues

ブランチで直近に実行された解析の問題を取得します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
branchName	string	はい	ブランチ名
first	number	いいえ	返す項目数
after	string	いいえ	前方ページネーション用のカーソル

6. dependency_vulnerabilities

プロジェクトの依存関係にあるセキュリティ脆弱性を取得します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
first	number	いいえ	返す項目数
after	string	いいえ	前方ページネーション用のカーソル

レスポンスの例：

{
  "vulnerabilities": [
    {
      "id": "VUL-001",
      "package": "requests",
      "version": "2.25.0",
      "severity": "HIGH",
      "cve": "CVE-2021-12345",
      "description": "Remote code execution vulnerability"
    }
  ],
  "totalCount": 3
}

7. quality_metrics

フィルタリングを指定して、コード品質メトリクスを取得します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
shortcodeIn	string[]	いいえ	メトリクスコードでフィルタリング（下記参照）

利用可能なメトリクス：

• LCV - 行カバレッジ
• BCV - 分岐カバレッジ
• DCV - ドキュメントカバレッジ
• DDP - 重複コードの割合
• SCV - ステートメントカバレッジ
• TCV - 合計カバレッジ
• CMP - コード成熟度

8. update_metric_threshold

品質メトリクスのしきい値を更新します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
repositoryId	string	はい	GraphQL リポジトリ ID
metricShortcode	string	はい	メトリクスのショートコード（例：「LCV」）
metricKey	string	はい	言語またはコンテキストのキー
thresholdValue	number|null	いいえ	新しいしきい値。削除する場合は null

9. update_metric_setting

メトリクスのレポートと適用の設定を更新します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
repositoryId	string	はい	GraphQL リポジトリ ID
metricShortcode	string	はい	メトリクスのショートコード
isReported	boolean	はい	このメトリクスをレポートするかどうか
isThresholdEnforced	boolean	はい	しきい値を適用するかどうか

10. compliance_report

セキュリティコンプライアンスレポートを取得します。

パラメーター	型	必須	説明
projectKey	string	はい	DeepSource プロジェクトの一意の識別子
reportType	string	はい	レポートの種類（以下を参照）

利用可能なレポートの種類：

• OWASP_TOP_10 - Web アプリケーションのセキュリティ脆弱性
• SANS_TOP_25 - 最も危険なソフトウェアエラー
• MISRA_C - セーフティクリティカルな C コードのガイドライン
• CODE_COVERAGE - コードカバレッジレポート
• CODE_HEALTH_TREND - 時間の経過に伴う品質の傾向
• ISSUE_DISTRIBUTION - 問題の分類
• ISSUES_PREVENTED - 防止された問題の数
• ISSUES_AUTOFIXED - 自動修正された問題の数

使用例

コード品質の傾向を監視する

プロジェクトの品質メトリクスを経時的に追跡します：

"Show me the code coverage trend for my main branch"

これにより、複数のツールを組み合わせて次の処理を行います：

1. main ブランチの最近の実行を取得する
2. 各実行のカバレッジメトリクスを取得する
3. 傾向を表示する

品質ゲートを設定する

CI/CD 用の品質ゲートを実装します：

"Set up quality gates: 80% line coverage, 0 critical security issues"

次の処理を行います：

1. 行カバレッジのしきい値を 80% に更新する
2. しきい値の適用を設定する
3. 現在の重大なセキュリティ問題を確認する

セキュリティ脆弱性を調査する

包括的なセキュリティ分析を行います：

"Analyze all security vulnerabilities in my project including dependencies"

次の処理を行います：

1. 依存関係の脆弱性をスキャンする
2. コードのセキュリティ問題を分析する
3. OWASP Top 10 への準拠を確認する
4. 優先順位を付けた修正案を提示する

コードレビューの支援

AI を活用したコードレビューの分析結果を取得します：

"What are the most critical issues in the recent commits to feature/new-api?"

次の処理を行います：

1. ブランチで最も新しい実行を見つける
2. 重大度が「Critical」および「High」の問題に絞り込む
3. ファイルと問題の種類ごとにグループ化する
4. 修正案を提示する

チームの生産性メトリクス

チームのコード品質メトリクスを追跡します：

"Show me code quality metrics across all our Python projects"

次の情報を集計します：

1. プロジェクトごとのカバレッジメトリクス
2. 重大度別の問題数
3. 過去 1 か月間の傾向
4. チームのパフォーマンスに関する分析情報

アーキテクチャ

DeepSource MCP Server では、保守性と型安全性を確保するために、最新の TypeScript パターンを使用しています。

主なコンポーネント

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude/AI      │────▶│   MCP Server     │────▶│  DeepSource API │
│  Assistant      │◀────│  (TypeScript)    │◀────│   (GraphQL)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘

1. MCP サーバー統合（src/index.ts）

   • ツールハンドラーを登録して実装する
   • MCP プロトコルの通信を管理する
   • エラーとログを処理する

2. DeepSource クライアント（src/deepsource.ts）

   • GraphQL API と通信する
   • 認証と再試行ロジックを処理する
   • レスポンスの解析と検証を行う

3. 型システム（src/types/）

   • 型安全性のためにブランド型を使用する
   • 状態管理に判別可能なユニオン型を使用する
   • 実行時検証に Zod スキーマを使用する

型安全性の機能

ブランド型

// Prevent mixing different ID types
type ProjectKey = string & { readonly __brand: 'ProjectKey' };
type RunId = string & { readonly __brand: 'RunId' };

判別可能なユニオン型

type RunState =
  | { status: 'PENDING'; queuePosition?: number }
  | { status: 'SUCCESS'; finishedAt: string }
  | { status: 'FAILURE'; error?: { message: string } };

開発

前提条件

• Node.js 22.19.0 以上
• pnpm 10.15.1 以上
• Docker（任意、コンテナーのビルド用）

セットアップ

# Clone the repository
git clone https://github.com/sapientpants/deepsource-mcp-server.git
cd deepsource-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

開発コマンド

注：MCP サーバーは stdio 経由で通信するため、単独では実行できません。対話形式でデバッグするには pnpm run inspect を使用してください。

コマンド	説明
pnpm install	依存関係をインストールする
pnpm run build	TypeScript コードをビルドする
pnpm run watch	ウォッチモードでビルドする
pnpm run clean	ビルド成果物を削除する
pnpm run inspect	MCP Inspector でデバッグする
pnpm test	すべてのテストを実行する
pnpm test:watch	ウォッチモードでテストを実行する
pnpm test:coverage	カバレッジレポートを生成する
pnpm run lint	lint の問題をチェックする
pnpm run lint:fix	lint の問題を修正する
pnpm run format	コードのフォーマットをチェックする
pnpm run format:fix	コードのフォーマットを修正する
pnpm run check-types	TypeScript の型をチェックする
pnpm run ci	CI パイプライン全体を実行する

トラブルシューティングと FAQ

よくある問題

認証エラー

Error: Invalid API key or unauthorized access

解決策：DEEPSOURCE_API_KEY が正しく、必要な権限を持っていることを確認してください。

プロジェクトが見つからない

Error: No projects found

解決策：API キーで DeepSource の少なくとも 1 つのプロジェクトにアクセスできることを確認してください。

レート制限超過

Error: API rate limit exceeded

解決策：サーバーは自動再試行を実装しています。しばらく待つか、リクエスト頻度を下げてください。

ページネーションカーソルが無効

Error: Invalid cursor for pagination

解決策：カーソルには有効期限があります。最初から新しいページネーションを開始してください。

FAQ

Q: どの DeepSource プランが必要ですか？ A: MCP サーバーはすべての DeepSource プランで利用できます。セキュリティコンプライアンスレポートなどの一部機能には、特定のプラン機能が必要な場合があります。

Q: セルフホスト版の DeepSource でも使えますか？ A: はい。環境変数で API エンドポイントを設定してください（v1.3.0 で対応予定）。

Q: 問題をデバッグするにはどうすればよいですか？ A: LOG_LEVEL=DEBUG を設定してデバッグログを有効にし、LOG_FILE で指定されたログファイルを確認してください。

Q: API キーは安全ですか？ A: API キーはローカルの Claude Desktop 設定にのみ保存され、DeepSource の API 以外に送信されることはありません。

Q: カスタムツールを提供できますか？ A: はい！ガイドラインについては、コントリビューションのセクションをご覧ください。

コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドをご覧ください。

開発ワークフロー

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. テストを実行します（pnpm test）
5. Conventional Commits に従って変更をコミットします（以下を参照）
6. ブランチにプッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

コミットメッセージ規約

このプロジェクトでは、コミットメッセージの一貫性を保つために Conventional Commits を使用しています。コミットは commitlint で検証されます。

形式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

種類

• feat：新機能
• fix：バグ修正
• docs：ドキュメントのみの変更
• style：コードの意味に影響しない変更（フォーマットなど）
• refactor：バグ修正でも機能追加でもないコード変更
• perf：パフォーマンスの改善
• test：不足しているテストの追加、または既存テストの修正
• build：ビルドシステムまたは依存関係に影響する変更
• ci：CI 設定ファイルおよびスクリプトの変更
• chore：src ファイルまたは test ファイルを変更しないその他の変更
• revert：以前のコミットの取り消し

例

# Feature
git commit -m "feat: add support for filtering issues by severity"

# Bug fix with scope
git commit -m "fix(api): handle null response from DeepSource API"

# Breaking change
git commit -m "feat!: change API response format

BREAKING CHANGE: Response format now uses camelCase instead of snake_case"

コード規約

• TypeScript のベストプラクティスに従ってください
• テストカバレッジを 80% 超に維持してください
• 意味のあるコミットメッセージを使用してください
• 新機能に合わせてドキュメントを更新してください

ライセンス

MIT - 詳細については LICENSE ファイルをご覧ください。

外部リソース

• Model Context Protocol 仕様
• DeepSource ドキュメント
• DeepSource API リファレンス

---

DeepSource MCP サーバーコミュニティにより ❤️ を込めて作られました