Laravel Docs MCP Server

Laravel MCP Companion

以前の名称は Laravel Docs MCP Server です

⚠️ ベータ版ソフトウェア - このプロジェクトは現在活発に開発中です。機能が変更されたり、互換性を損なう変更が発生したりする可能性があります。

Laravel MCP Companion は、Laravel エコシステム向けのドキュメント集約・ナビゲーションツールです。Laravel エコシステム全体の質の高いドキュメントを一元化して整理し、AI アシスタントから簡単に見つけられるようにします。

他のツールとの比較

機能	Laravel Boost	Context7	Laravel MCP Companion
主な用途	コード生成	一般的なドキュメント	Laravel ドキュメント
最適な用途	開発中	あらゆるライブラリ	学習とリファレンス
プロジェクトを認識したコンテキスト	✅	❌	❌
Laravel の複数バージョンに対応（6.x - 最新版）	❌	❌	✅
Laravel サービスのドキュメント（Forge、Vapor、Nova、Envoyer）	❌	❌	✅
学習パスと難易度レベル	❌	❌	✅
「X が必要」なときのドキュメント検索	❌	❌	✅
厳選された Laravel パッケージのおすすめ	❌	❌	✅
オフラインでのドキュメント閲覧	❌	❌	✅
TOON 形式の出力（トークンを30～60％削減）	❌	❌	✅
一般的なドキュメント（Laravel 以外）	❌	✅	❌

コードを書いていて、プロジェクトを認識したコンテキストが必要な場合は Boost を使いましょう。 Laravel 以外のライブラリには Context7 を使いましょう。学習、調査、または Laravel のドキュメントをリファレンスとして使う場合は Companion を使いましょう。

利用できる機能：

• 複数バージョンの Laravel ドキュメント（6.x から最新版まで）と強化された検索
• 学習パス - トピックとスキルレベルに応じた体系的な学習手順
• 「X が必要」なときの検索 - 必要な内容を説明すると、関連するドキュメントを表示
• 難易度による絞り込み - コンテンツを初級・中級・上級に分類
• 15のセマンティックカテゴリ - トピック別にドキュメントを閲覧
• Laravel サービスの自動検出 - Forge、Vapor、Envoyer、Nova（117以上のセクション）
• コミュニティパッケージのドキュメント - Spatie、Livewire、Inertia、Filament の42,000行以上
• パッケージ統合ガイド - 厳選された22のパッケージのインストールと設定
• パッケージ間の互換性 - 相性のよいパッケージを確認
• Laravel コアのドキュメント、サービス、パッケージ、学習リソースを横断する統合検索
• 毎日の更新 - 最新のドキュメントと自動的に同期

インストール

公式 MCP Registry に io.github.brianirish/laravel-mcp-companion として登録されています。レジストリに 対応したクライアントは、そこから直接インストールできます。手動で設定する場合：

Claude Desktop

1. Claude Desktop の設定を開く

   • Claude メニュー → 設定 → 開発者 → 設定を編集

2. 設定ファイルに追加します：

   {
     "mcpServers": {
       "laravel-mcp-companion": {
         "command": "docker",
         "args": ["run", "--rm", "-i", "ghcr.io/brianirish/laravel-mcp-companion:latest"]
       }
     }
   }
   

3. 変更を反映するため、Claude Desktop を再起動します

設定ファイルの場所：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code

claude mcp add コマンドを使用します：

# Add with Docker
claude mcp add laravel-mcp-companion -- docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest

# Or add to project-specific config (for team sharing)
claude mcp add laravel-mcp-companion --scope project -- docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest

--scope project オプションを指定すると、プロジェクトのルートに .mcp.json ファイルが作成され、バージョン管理にコミットできます。

設定オプション

これらのオプションは Docker コマンドとともに使用できます。例：

# Pin to a specific older Laravel version
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --version 11.x

# Force update all documentation
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --force-update

オプション	説明	デフォルト
--version VERSION	Laravel のバージョン（例：「11.x」、「12.x」）	最新
--docs-path PATH	ドキュメントのディレクトリ	./docs
--log-level LEVEL	DEBUG、INFO、WARNING、ERROR、CRITICAL	INFO
--update-docs	起動時にドキュメントを更新	false
--force-update	ドキュメントを強制的に更新	false
--transform-mode MODE	ツールの公開モード：search、code、none（環境変数：TRANSFORM_MODE）	search
--host HOST	HTTP モードでバインドするインターフェース（環境変数：HOST）	127.0.0.1（Docker では 0.0.0.0）
--cors-origin ORIGIN	HTTP トランスポートへの呼び出しを許可するブラウザーのオリジン。複数指定可能（環境変数：CORS_ORIGINS）	なし（CORS は無効）
--allowed-host HOST	HTTP モードで許可する追加の Host ヘッダー。複数指定可能（環境変数：ALLOWED_HOSTS）	localhost、127.0.0.1、::1
--auth-jwks-uri URI	HTTP モードでベアラートークン認証を有効にする JWKS エンドポイント（環境変数：AUTH_JWKS_URI）	なし（認証は無効）
--auth-issuer ISSUER	--auth-jwks-uri とともに指定する必須のトークン発行者（環境変数：AUTH_ISSUER）	なし
--auth-audience AUD	--auth-jwks-uri とともに指定する必須のトークンオーディエンス（環境変数：AUTH_AUDIENCE）	なし
--auth-required-scope SCOPE	すべてのトークンに必要なスコープ。複数指定可能（環境変数：AUTH_REQUIRED_SCOPES）	なし
--rate-limit RPS	HTTP モードで受け付ける MCP リクエスト数／秒。運用エンドポイントは制限されません（環境変数：RATE_LIMIT_RPS）	なし（制限なし）
--rate-limit-burst N	トークンバケットのバースト容量（環境変数：RATE_LIMIT_BURST）	max(10, 2×RPS)

ドキュメントを最新の状態に保つ

ドキュメントはイメージに含まれており、ドキュメントが更新されるたびに新しいイメージが公開されるため、:latest には公開済みの最新スナップショットが含まれます。ただし、docker run では、すでに手元にあるコピーが再利用されます。イメージを一度取得すると、再度取得するまで同じものを実行し続けます。いつでも更新できます。

docker pull ghcr.io/brianirish/laravel-mcp-companion:latest

または、MCP の設定に --pull=always を追加すると、起動のたびに新しいイメージがあるか確認します。起動に少し時間がかかり、接続が必要になるため、デフォルトではなくオプトインになっています。

"args": ["run", "--rm", "-i", "--pull=always",
         "ghcr.io/brianirish/laravel-mcp-companion:latest"]

自分で確認し続ける必要はありません。サーバーは、提供している Laravel バージョンのドキュメントがどれくらい古いかをアシスタントに知らせます。そのため、そのスナップショットより新しい情報について質問すると、古いページに基づいて回答する代わりに、そのことを伝えて更新を提案します。直接「Laravel のドキュメントはどのくらい最新ですか？」と尋ねることもできます。

新しいイメージを取得せずにその場で更新するには、--update-docs を使うと、起動時に選択した Laravel バージョンの最新ドキュメントを取得します。Forge、Vapor、Nova、Envoyer およびコミュニティパッケージのドキュメントは別途更新され、アシスタントが呼び出せる update_external_laravel_docs ツールを通じて取得します。

--rm を指定すると、コンテナーの終了時にダウンロードした内容が破棄されるため、起動のたびに再取得されます。名前付きボリュームを使えば保持できますが、次の点に注意してください。

docker run --rm -i -v laravel-mcp-docs:/app/docs \
  ghcr.io/brianirish/laravel-mcp-companion:latest --update-docs

ボリュームはイメージのドキュメントを上書きします。 データが格納されると /app/docs が隠されるため、新しいイメージを取得してもサーバーが読み取る内容は更新されません。ボリュームが正本となり、更新には --update-docs を使うようになります。更新を明示的に管理したい場合はボリュームを使い、イメージに任せたい場合は通常の docker pull を使ってください。

変換モード

デフォルトでは、サーバーはすべてのツールを一覧表示しません。代わりに、検索を優先したコンパクトなインターフェースを公開し、AI クライアントのコンテキストウィンドウを小さく保ちます。

• search（デフォルト） — search_tools（ツールカタログを対象にした BM25 関連性検索）と call_tool（任意の基盤ツールを呼び出すプロキシ）を公開します。search_laravel_docs は引き続き固定で、直接呼び出せます。
• code（実験的） — Code Mode メタツール（tags、search、get_schema、execute）を公開します。これらを使うと、クライアントはツールを検出し、サンドボックス化された Python でツールを連携させられます。fastmcp[code-mode] の追加パッケージが必要です（requirements.txt に含まれています）。HTTP 経由でこれを公開しないでください。execute はコード実行エンドポイントです。
• none — 0.9 より前の動作で、すべてのツールを直接一覧表示します。MCP クライアントが合成検索ツールを適切に扱えない場合に使用してください。

# Restore the old flat tool listing
docker run --rm -i ghcr.io/brianirish/laravel-mcp-companion:latest --transform-mode none

HTTP トランスポートのセキュリティ

認証はデフォルトで無効です。 HTTP ポートにアクセスできるユーザーは誰でもすべてのツールを呼び出せるため、ネットワークに公開することはドキュメントツリー全体へのアクセスを許可することと同じだと考えてください。または、ベアラートークン認証を有効にしてください。

# Validate tokens issued by a real OAuth 2.1 authorization server
python laravel_mcp_companion.py --transport http \
  --auth-jwks-uri https://auth.example/.well-known/jwks.json \
  --auth-issuer https://auth.example \
  --auth-audience laravel-mcp-companion

# Development only: fixed tokens from the environment (never a CLI flag,
# so secrets stay out of process listings)
AUTH_STATIC_TOKENS="my-token:my-client" python laravel_mcp_companion.py --transport http

このサーバーはリソースサーバーです。トークンを検証しますが、発行することはありません。 --auth-jwks-uri を指定する場合、発行者とオーディエンスは必須です。 あらゆる発行者のトークンや、別のサービス向けに発行されたトークンを受け入れるのは、 認証を装っているにすぎません。認証されていないリクエストには WWW-Authenticate ヘッダーを付けて 401 を返します（RFC 9728）。設定に誤りがある場合は、 リクエスト時ではなく起動時にエラーになります。 認証が適用されるのは HTTP トランスポートのみです。stdio のアクセス制御はプロセスの境界で行われます。

デフォルト設定は安全性を重視しています。

• Docker の外では 127.0.0.1 にバインドします。 コンテナ内では 0.0.0.0 にバインドします。この場合、アクセス制御はコンテナの境界と明示的な -p によるポート公開が担います。
• Host と Origin の検証は有効です。 これにより、被害者のブラウザーを利用した DNS リバインディング攻撃やローカルホストへの無断アクセスを防ぎます。
• --cors-origin を渡さない限り、CORS は無効です。 ワイルドカードのオリジンは拒否され、クロスオリジンで認証情報が許可されることはありません。

デフォルトでは、Host の値として localhost、127.0.0.1、::1 のみが許可されます。ループバック以外のインターフェースにバインドする場合、クライアントが実際に使用するホスト名を追加してください。追加しないと、すべてのリクエストが 421 で拒否されます。

python laravel_mcp_companion.py --transport http \
  --host 0.0.0.0 \
  --allowed-host mcp.internal.example \
  --cors-origin https://app.example

認識されていない Host を含むリクエストには 421 が返され、許可されていない Origin からのリクエストには 403 が返されます。コマンドラインで --allowed-host または --cors-origin を渡すと、対応する環境変数に追加するのではなく、その値で置き換えられます。ローカルホスト以外に公開する場合は、認証を行うリバースプロキシを前段に配置してください。HTTP では --transform-mode code を使用しないでください。execute はコード実行エンドポイントです。

レート制限（HTTP モード）

デフォルトでは無効です。--rate-limit 20 を指定すると、単一のグローバルトークンバケットにより、MCP リクエスト（ツール呼び出し、検索、プロトコルの操作）を毎秒 20 件に制限します。これは合計スループットの上限であり、クライアントごとの公平性を保つものではありません（認証がなければ、制限のキーとして使える信頼性の高いクライアント ID がありません）。運用エンドポイント（/healthz、/metrics、/.well-known/...）は意図的に制限対象外です。ロードバランサーのヘルスチェックを制限すると、正常なインスタンスがダウンと判断されます。また、これらのハンドラーは単純な読み取り処理です。この制限では、初期化ハンドシェイクを含むすべての MCP リクエストがカウントされます。そのため、バーストのデフォルト値は max(10, 2×RPS) のままです。値を下げる場合は、クライアントのハンドシェイクに必要なリクエスト数を十分に上回るバースト値を設定してください。制限されたリクエストには適切な MCP エラーが返され、トークンバケットが補充されると再び成功するようになります。

運用エンドポイント（HTTP モード）

• GET /healthz — 稼働状態／準備状態を示す JSON を返します。常に公開されます（ロードバランサーは OAuth を実行できません）。ok と degraded はどちらも 200 を返します。degraded はドキュメントのコピーが古くなっており、より新しいイメージを取得する必要があることを示します。ドキュメントがまったく読み取れない場合は 503 を返し、ここにトラフィックをルーティングすべきではありません。
• GET /metrics — Prometheus テキスト形式で、ツールごとの呼び出しカウンター、レイテンシーヒストグラム、リクエスト数、稼働時間、ドキュメントの経過時間を返します。認証が設定されていない環境では公開されます。認証が設定されている場合は、有効なベアラートークンが必要です。

機能（v0.13.0）

ドキュメントの集約

• 複数バージョンの Laravel ドキュメント - 6.x から最新バージョンまでのすべてのバージョンに対応
• 自動検出エンジン - Forge、Vapor、Nova、Envoyer の新しいドキュメントを検出
• コミュニティパッケージのドキュメント - Spatie、Livewire、Inertia、Filament から 42,000 行以上
• 毎日の更新 - 最新のドキュメントと自動的に同期

学習と探索

• 学習パス - Laravel のあらゆるトピックを対象とした、構造化された一連の学習パスをインタラクティブに提供します。パスを指定せずに質問すると、厳選された 10 個のパスのうち、どれを希望するかサーバーが尋ねます
• 難易度レベル - 初級、中級、上級で絞り込めます
• 15 のカテゴリー - 認証、データベース、テストなどから探せます
• 「X が必要」ファインダー - 自然言語でドキュメントを見つけられます
• 関連リソース - 関連するドキュメントを自動的に見つけます

検索とナビゲーション

• 関連度順のセクション検索 - 「失敗したキュージョブを再試行するには」のように平易な言葉で質問すると、関連度順に並んだ該当 セクション を、スニペット、アンカー、ソースラベルとともに取得できます
• セクション単位の読み取り - 必要なセクションだけを取得できます。ドキュメントファイル全体では 30,000 トークンを超えることがありますが、セクションは通常数百トークンなので、回答のための余裕を残し、実際のコードも含められます
• ユースケースのマッピング - 必要な内容を説明すると、関連パッケージを取得できます
• パッケージ統合ガイド - 厳選された 22 個のパッケージについて、インストールとセットアップを案内します
• パッケージ間の互換性 - パッケージの組み合わせに関するドキュメントを提供します
• 統合検索 - コアバージョン、サービス、取得済みのパッケージドキュメント、学習リソースなど、すべてのコーパスを横断して検索できます。sources フィルターで対象を絞り込めます

MCP 2025-11-25 の機能

• タスク対応の更新 - ドキュメントの更新は MCP タスクとして実行されます。接続を数分間保持せずに、送信、ポーリング、結果の取得ができます
• 構造化出力 - 表形式のツールは、TOON テキストとともに実際のスキーマを含む structuredContent を返します
• エリシテーション - 有用な場合はインタラクティブな選択肢を提示し、この機能に対応していないクライアントには通常の一覧を代替として表示します
• レジストリ掲載 - server.json メタデータ、HTTP モードでの .well-known による検出、リリースタグに基づく自動公開に対応し、公式 MCP Registry からインストールできます

本番環境での運用（HTTP モード）

• ヘルスチェックとメトリクス - ロードバランサー向けの GET /healthz と、ツールごとのカウンター、レイテンシーヒストグラム、ドキュメントの経過時間を含む Prometheus 用の GET /metrics
• OAuth 2.1 リソースサーバー - オプションでベアラートークンを検証します（JWKS または静的な開発用トークンに対応）。設定ミスは起動時に失敗し、障害時はアクセスを拒否します
• レート制限 - MCP のインターフェース全体に適用できるオプトイン方式のトークンバケット。デフォルトではハンドシェイクを考慮したバーストを設定します
• デフォルトで堅牢 - ループバックへのバインド、Host／Origin の検証、ワイルドカード CORS の不使用、検索、一覧表示、読み取りで一貫して適用されるパス封じ込め

品質

• 製品カバレッジ 81％、CI ゲートは 80％。実際の stdio および HTTP トランスポートを使ったエンドツーエンドテストと、レポートのみを行うレイテンシーベンチマークも備えています。ウォーム状態での検索の p95 は数ミリ秒で、v1.0.0 の目標である 100ms を達成しています

今後の予定

• v1.0.0：初の安定版リリース — API の凍結、破壊的変更に関する方針、LTS の提供

ロードマップの詳細については、ROADMAP.md を参照してください。

TOON 形式の出力

Laravel MCP Companion は、構造化出力に TOON（Token-Oriented Object Notation） を使用し、JSON／Markdown と比べて トークンを 30～60％節約します。

出力例

パッケージを検索したりドキュメントを一覧表示したりすると、効率的な構造化データが得られます。

context: "authentication for SPA"
count: 2
packages[2]{id,name,description,categories,install}:
  laravel/sanctum,Laravel Sanctum,"Featherweight authentication for SPAs",[authentication,spa],"composer require laravel/sanctum"
  laravel/passport,Laravel Passport,"Full OAuth2 implementation",[authentication,api],"composer require laravel/passport"

同等の JSON と比べてください（トークン数はほぼ 2 倍です）。

{"context":"authentication for SPA","count":2,"packages":[{"id":"laravel/sanctum","name":"Laravel Sanctum",...}]}

TOON を使う理由

• トークン効率に優れる：LLM は TOON をネイティブに理解するため、解析のオーバーヘッドがありません
• 構造化データ：JSON の冗長さを避けながら、配列、オブジェクト、メタデータを扱えます
• AI に最適：LLM のコンテキストウィンドウに合わせて特別に設計されています

自動検出と更新頻度

このアプリケーションには、Laravel のドキュメントを自動で検出してインデックス化するインテリジェントな自動検出システムが備わっています。毎日、次の処理を行います。

• Laravel の各サービス（Forge、Vapor、Nova、Envoyer）にわたって、新しいドキュメントセクションを自動検出します
• 6.x 以降のすべてのバージョンについて、最新の Laravel コアドキュメントを取得します
• コミュニティパッケージのドキュメント（Spatie、Livewire、Inertia、Filament）を取得します
• ドキュメントサイトの構造変更に自動で適応します
• 更新が見つかった場合、新しいパッチリリースを自動生成します

開発

前提条件

• Python 3.12+
• Node.js 18+（MCP Inspector 用）

セットアップ

git clone https://github.com/brianirish/laravel-mcp-companion
cd laravel-mcp-companion
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt -r requirements-dev.txt

テストの実行

# All tests with coverage
pytest --cov --cov-report=html

# Unit tests only
pytest tests/unit/

# Integration tests only
pytest tests/integration/

# Protocol compliance tests
pytest tests/protocol/ -m protocol

MCP Inspector を使った手動テスト

MCP Inspector は、MCP サーバーをテストするための視覚的な UI を提供します。

# Launch Inspector (opens browser at http://localhost:6274)
npx @modelcontextprotocol/inspector python laravel_mcp_companion.py

# With specific version
npx @modelcontextprotocol/inspector python laravel_mcp_companion.py --version 11.x

Inspector を使って次の操作を行えます。

• Tools タブ：自動生成された入力フォームを使って、すべてのツールをテストします
• Resources タブ：laravel:// および laravel-external:// リソースを参照します
• Prompts タブ：プロンプトテンプレートをテストします

コード品質

ruff check --fix .     # Linting
mypy --ignore-missing-imports .  # Type checking
black .                # Formatting

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

貢献

貢献を歓迎します！ガイドラインについては CONTRIBUTING.md を参照してください。

謝辞

• 優れたドキュメントを提供している Laravel
• エコシステムへの貢献をしている Laravel パッケージの作者