Yellhorn MCP

Yellhorn MCP

タスクや機能を実装するための詳細な作業計画を作成する機能を提供する、Model Context Protocol（MCP）サーバーです。これらの作業計画は、高性能なモデル（gemini 2.5 pro や o3 deep research API など）を使って生成され、デフォルトではコードベース全体がコンテキストウィンドウに挿入されます。また、使用するモデルによっては、URL コンテキストへのアクセスやウェブ検索も可能です。高性能な推論モデルを使って作業計画を作成するこの方法は、Claude Code などのコーディングアシスタントや、MCP に対応したほかのコーディングエージェントが実行する作業を定義するうえで非常に役立ちます。また、こうしたコーディングモデルの出力をレビューする際の参照資料となり、指定された元の要件が正確に満たされているか確認できます。

特長

• 作業計画の作成：プロンプトに基づき、コードベース全体を考慮した詳細な実装計画を作成します。作業計画は GitHub issue として投稿され、コーディングエージェントが利用できる MCP リソースとして公開されます。
• コード差分の評価：コードベース全体のコンテキストを使って、元の作業計画に照らして Git の差分を評価するツールを提供します。実装が元の要件から逸脱していないか確認し、逸脱している場合は要件に沿うための変更方法を詳しく提示します。
• GitHub とのシームレスな連携：ラベル付き issue を自動作成し、元の作業計画 issue を参照する評価用の子 issue を投稿します。
• コンテキストの制御：.gitignore と同様に、.yellhornignore ファイルを使って AI のコンテキストから特定のファイルやディレクトリを除外できます。
• MCP リソース：作業計画を標準的な MCP リソースとして公開し、簡単に一覧表示、取得できます。
• Google 検索によるグラウンディング：Gemini モデルではデフォルトで有効になっており、Markdown 形式で自動整形された引用情報とともに検索機能を利用できます。
• 自動チャンク分割：モデルのコンテキスト上限を超える大規模なコードベースを、プロンプトを賢く分割して処理します。
• レート制限への対応：レート制限や一時的な障害に対して、指数バックオフによる堅牢な再試行ロジックを備えています。
• コストの追跡：すべての API 呼び出しについて、コストをリアルタイムで見積もり、使用状況を追跡します。
• 複数モデルへの対応：OpenAI（GPT-4o、GPT-5、o3、o4-mini）、xAI Grok（Grok-4、Grok-4 Fast）、Gemini（2.5-pro、2.5-flash）をサポートする統一インターフェースを提供します。GPT-5 では推論モードにも対応しています。

インストール

プロジェクトの初期設定（uv）

# Install from source
git clone https://github.com/msnidal/yellhorn-mcp.git
cd yellhorn-mcp

# Provision the environment and install all dependency groups
uv sync --group dev

# Optional: activate the environment for direct shell usage
source .venv/bin/activate

# Verify the CLI entrypoint
uv run yellhorn-mcp --help

uv sync は .venv を作成し、パッケージを編集可能モードでインストールして、pyproject.toml で定義されている dev 依存関係グループを適用します。

PyPI からインストール

uv pip install yellhorn-mcp

設定

サーバーには、以下の環境変数が必要です。

• GEMINI_API_KEY：Gemini API キー（Gemini モデルで必須）
• OPENAI_API_KEY：OpenAI API キー（OpenAI モデルで必須）
• XAI_API_KEY：xAI API キー（Grok モデルで必須）
• REPO_PATH：リポジトリへのパス（デフォルトは現在のディレクトリ）
• YELLHORN_MCP_MODEL：使用するモデル（デフォルトは "gemini-2.5-pro"）。使用できるオプション：
  • Gemini モデル："gemini-2.5-pro"、"gemini-2.5-flash"、"gemini-2.5-flash-lite"
  • OpenAI モデル："gpt-4o"、"gpt-4o-mini"、"o4-mini"、"o3"、"gpt-4.1"
  • GPT-5 モデル："gpt-5"、"gpt-5-mini"、"gpt-5-nano"（gpt-5 と gpt-5-mini は推論モードに対応）
  • xAI Grok モデル："grok-4"（256K コンテキスト）と "grok-4-fast"（2M コンテキスト）
  • Deep Research モデル："o3-deep-research"、"o4-mini-deep-research"
  • 注：Deep Research モデル（GPT-5 を含む）では、調査機能を強化するために web_search_preview と code_interpreter ツールが自動的に有効になります
• YELLHORN_MCP_REASONING_EFFORT：GPT-5 モデルの推論レベルを設定します。オプション："low"、"medium"、"high"。対応モデル（gpt-5、gpt-5-mini）では、コストが高くなる代わりに推論能力が向上します。このレベルによって推論に使用する計算量が決まり、レベルが高いほどコストは増加しますが、より詳細な推論が可能になります。サーバーはこの値をすべての GPT-5 リクエストに転送するようになり、コスト指標には適切な推論プレミアムが自動的に含まれます。
• YELLHORN_MCP_SEARCH：Google Search Grounding を有効または無効にします（Gemini モデルではデフォルトで "on"）。オプション：
  • "on" - Gemini モデルで Search Grounding を有効にします
  • "off" - すべてのモデルで Search Grounding を無効にします

ℹ️ Grok モデルでは公式の xai-sdk を使用するようになりました。環境にインストールされていることを確認してください（プロジェクトの依存関係には含まれていますが、カスタムデプロイでは明示的に追加する必要があります）。

サーバーを使用するには、GitHub CLI（gh）もインストールし、認証しておく必要があります。

使用方法

はじめに

Codex CLI の設定

以下のサーバー設定を、Codex CLI の config.toml（デフォルトでは ~/.config/codex/config.toml）に追加します。GEMINI_API_KEY（または OPENAI_API_KEY／XAI_API_KEY に置き換えてモデルを調整）と REPO_PATH の値を、ご利用の環境に合わせて更新してください。

[mcp_servers.yellhorn-mcp]
command = "uv"
args = ["run", "yellhorn-mcp"]
env = { "GEMINI_API_KEY" = "your-api-key", "REPO_PATH" = "/path/to/your/repo" }

設定を更新したら、Codex を再起動して新しい MCP サーバーを読み込ませてください。

VSCode/Cursor の設定

VSCode または Cursor で Yellhorn MCP を設定するには、ワークスペースのルートに .vscode/mcp.json ファイルを作成し、以下の内容を記述します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gemini-api-key",
      "description": "Gemini API Key"
    }
  ],
  "servers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "yellhorn-mcp"],
      "env": {
        "GEMINI_API_KEY": "${input:gemini-api-key}",
        "REPO_PATH": "${workspaceFolder}"
      }
    }
  }
}

Claude Code の設定

Claude Code で Yellhorn MCP を直接設定するには、プロジェクトのルートに .mcp.json ファイルを追加し、以下の内容を記述します。

{
  "mcpServers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "yellhorn-mcp", "--model", "o3"],
      "env": {
        "YELLHORN_MCP_SEARCH": "on"
      }
    }
  }
}

ツール

curate_context

コードベースを分析し、AI コンテキストに含めるディレクトリを一覧にした .yellhorncontext ファイルを作成します。このツールは、達成したいタスクを理解して関連するディレクトリのホワイトリストを作成することで、AI コンテキストを最適化します。これにより、トークン使用量を大幅に削減し、AI が関連コードに集中できるようになります。

入力：

• user_task：達成したいタスクの説明
• codebase_reasoning：（任意）コードベース分析のレベルを制御します：
  • "file_structure"：（デフォルト）基本的なファイル構造の分析（最速）
  • "lsp"：関数シグネチャとドキュメント文字列のみ（軽量）
  • "full"：ファイルの内容全体（最も包括的）
  • "none"：コードベースのコンテキストなし
• ignore_file_path：（任意）無視ファイルのパス（デフォルトは .yellhornignore）
• output_path：（任意）コンテキストファイルの出力先パス（デフォルトは .yellhorncontext）
• depth_limit：（任意）分析するディレクトリの最大深度（0 = 制限なし）
• disable_search_grounding：（任意）true に設定すると、このリクエストで Google Search Grounding を無効にします

出力：

• 以下を含む JSON 文字列：
  • context_file_path：作成された .yellhorncontext ファイルのパス
  • directories_included：コンテキストに含まれるディレクトリ数
  • files_analyzed：選定時に分析されたファイル数

.yellhorncontext ファイルはホワイトリストとして機能します。以降の workplan／judgement 呼び出しでは、パターンに一致するファイルのみが含まれます。これにより、トークン使用量を大幅に削減し、AI が関連コードに集中できるようになります。

.yellhorncontext の出力例：

src/api/
src/models/
tests/api/
*.config.js

create_workplan

タイトルと詳細な説明に基づいて、詳細な作業計画を含む GitHub issue を作成します。

入力：

• title：GitHub issue のタイトル（issue のタイトルと見出しに使用されます）
• detailed_description：作業計画の詳細な説明です。ここに記載された URL は抽出され、「References」セクションに含まれます。
• codebase_reasoning：（任意）AI による強化を行うかどうかを制御します：
  • "full"：（デフォルト）AI を使用し、コードベースのコンテキスト全体を使って作業計画を強化します
  • "lsp"：軽量なコードベースのコンテキスト（関数／メソッドのシグネチャ、クラス属性、Python と Go の構造体フィールド）を使って AI を使用します
  • "none"：AI による強化をスキップし、提供された説明をそのまま使用します
• debug：（任意）true に設定すると、生成に使用されたプロンプト全文を issue にコメントとして追加します
• disable_search_grounding：（任意）true に設定すると、このリクエストで Google Search Grounding を無効にします

出力：

• 以下を含む JSON 文字列：
  • issue_url：作成された GitHub issue の URL
  • issue_number：GitHub issue の番号

get_workplan

作業計画に関連付けられた内容（GitHub issue の本文）を取得します。

入力：

• issue_number：作業計画の GitHub issue 番号。
• disable_search_grounding：（任意）true に設定すると、このリクエストで Google Search Grounding を無効にします

出力：

• 作業計画 issue の内容を文字列として返します

revise_workplan

既存の作業計画を、改訂指示に基づいて更新します。指定された GitHub issue から現在の作業計画を取得し、指示に従って AI で改訂します。

入力：

• issue_number：改訂する作業計画が記載された GitHub issue の番号
• revision_instructions：作業計画の改訂方法を説明する指示
• codebase_reasoning：（任意）AI による拡張を行うかどうかを指定します。
  • "full"：（デフォルト）コードベースのコンテキスト全体を使用して AI で改訂します
  • "lsp"：軽量なコードベースのコンテキスト（関数／メソッドのシグネチャのみ）を使用して AI で改訂します
  • "file_structure"：ディレクトリ構造のみを使用して AI で改訂します（最速）
  • "none"：最小限のコードベースのコンテキストを使用します
• debug：（任意）true に設定すると、生成に使用したプロンプト全文を issue にコメントとして追加します
• disable_search_grounding：（任意）true に設定すると、このリクエストの Google Search Grounding を無効にします

出力：

• 次を含む JSON 文字列：
  • issue_url：更新された GitHub issue の URL
  • issue_number：GitHub issue の番号

judge_workplan

GitHub issue に記載された作業計画に照らして、2 つの git ref（ブランチまたはコミット）を比較するコード判定を非同期で開始します。プレースホルダーの GitHub サブ issue をただちに作成し、その後 AI による判定を非同期で処理して、結果でサブ issue を更新します。

入力：

• issue_number：作業計画が記載された GitHub issue の番号。
• base_ref：比較対象のベースとなる Git ref（コミット SHA、ブランチ名、タグ）。デフォルトは 'main' です。
• head_ref：比較対象のヘッドとなる Git ref（コミット SHA、ブランチ名、タグ）。デフォルトは 'HEAD' です。
• codebase_reasoning：（任意）提供するコードベースのコンテキストを指定します。
  • "full"：（デフォルト）コードベースのコンテキスト全体を使用します
  • "lsp"：より軽量なコードベースのコンテキストを使用します（Python と Go の関数シグネチャのみ、および差分ファイル全体）
  • "file_structure"：処理を高速化するため、ファイルの内容を含めず、ディレクトリ構造のみを使用します
  • "none"：処理を最速にするため、コードベースのコンテキストを完全に省略します
• debug：（任意）true に設定すると、生成に使用したプロンプト全文をサブ issue にコメントとして追加します
• disable_search_grounding：（任意）true に設定すると、このリクエストの Google Search Grounding を無効にします

作業計画に記載された URL はすべて抽出され、判定結果の References セクションに保持されます。

出力：

• 次を含む JSON 文字列：
  • message：判定タスクが開始されたことを示す確認メッセージ
  • subissue_url：結果が投稿される、作成済みプレースホルダーサブ issue の URL
  • subissue_number：プレースホルダーサブ issue の GitHub issue 番号

ファイルフィルタリングシステム

Yellhorn MCP は、AI コンテキストに含めるファイルを制御する、高度な多層ファイルフィルタリングシステムを提供します。このシステムでは、優先順位に従ってファイルを含めるかどうかを決定します。

フィルターレイヤー（優先順位順）

1. .yellhorncontext のホワイトリスト：このファイルが存在し、パターンが含まれている場合、そのパターンに一致するファイルのみが含まれます
2. .yellhorncontext のブラックリスト：ブラックリストのパターン（! で始まる）に一致するファイルは除外されます
3. .yellhornignore のホワイトリスト：ホワイトリストのパターン（! で始まる）に一致するファイルは明示的に含まれます
4. .yellhornignore のブラックリスト：これらのパターンに一致するファイルは除外されます
5. .gitignore のブラックリスト：git によって無視されるファイルは自動的に除外されます

常に無視されるパターン

他の設定にかかわらず、次のパターンは常に無視されます。

• .git/ - Git メタデータ
• __pycache__/ - Python キャッシュファイル
• node_modules/ - Node.js の依存関係
• *.pyc - Python コンパイル済みファイル
• .venv/、venv/ - Python 仮想環境

ファイル形式

.yellhornignore と .yellhorncontext の両ファイルでは、gitignore に似た構文を使用します。

• 1 行につき 1 つのパターン
• # で始まる行はコメントです
• 空行は無視されます
• ホワイトリストのパターン（明示的に含める）には ! の接頭辞を使用します
• ディレクトリパターンは / で終わる必要があります

.yellhornignore の例

# Exclude test files
tests/
*.test.js

# Exclude build artifacts
dist/
build/

# But include important test utilities
!tests/utils/

.yellhorncontext の例

# Only include source code and documentation
src/
docs/
README.md

# Exclude generated files even in src
!src/generated/

リソースへのアクセス

Yellhorn MCP は、ワークプランへのアクセスを提供する標準 MCP リソース API も実装しています。

• list-resources：すべてのワークプラン（yellhorn-mcp ラベルが付いた GitHub の issue）を一覧表示します
• get-resource：issue 番号を指定して、特定のワークプランの内容を取得します

標準の MCP CLI コマンドからアクセスできます。

# List all workplans
mcp list-resources yellhorn-mcp

# Get a specific workplan by issue number
mcp get-resource yellhorn-mcp 123

開発

# Ensure the environment is up to date
uv sync --group dev

# Run tests
uv run --group dev pytest

# Run tests with coverage report
uv run --group dev pytest -- --cov=yellhorn_mcp --cov-report term-missing

# Add or remove dependencies
uv add some-package
uv remove some-package

# Regenerate the lockfile (commit the result)
uv lock

CI/CD

このプロジェクトでは、継続的インテグレーションとデプロイに GitHub Actions を使用しています。

• テスト：プルリクエストと main ブランチへのプッシュ時に自動で実行されます

  • flake8 によるリンティング
  • black によるフォーマットチェック
  • pytest によるテスト

• 公開：バージョンタグがプッシュされると、PyPI に自動で公開されます

  • タグは pyproject.toml のバージョンと一致している必要があります（例：v0.2.2）
  • GitHub リポジトリのシークレット（PYPI_API_TOKEN）として保存された PyPI API トークンが必要です

新しいバージョンをリリースするには：

1. pyproject.toml と yellhorn_mcp/__init__.py のバージョンを更新します
2. CHANGELOG.md に新しい変更を記載します
3. 変更をコミットします：git commit -am "Bump version to X.Y.Z"
4. コミットにタグを付けます：git tag vX.Y.Z
5. 変更とタグをプッシュします：git push && git push --tags

変更履歴については、変更履歴を参照してください。

詳しい手順については、使用ガイドを参照してください。

ライセンス

MIT