Symfony Agent MCP

symfony-agent-mcp

機能 • クイックスタート • 連携 • 使い方 • ドキュメント • コントリビューション • ライセンス

---

Symfony アプリケーション向けの、本番環境に対応した Model Context Protocol (MCP) サーバーです。 AI アシスタントが、Symfony のコードベース全体を読み取り専用で詳細に調査できます — ルート、コントローラー、サービス、エンティティ、データベーススキーマ、マイグレーション、イベント、フォーム、 セキュリティ、Doctrine、Messenger、Twig、API Platform など、幅広く対応しています。

クライアント	インストール
Claude Code	claude mcp add を実行 → セットアップ
Claude Desktop	claude_desktop_config.json に追加 → セットアップ
Cursor	.cursor/mcp.json に追加 → セットアップ
VS Code Copilot	.vscode/mcp.json に追加 → セットアップ
任意の MCP クライアント	stdio トランスポート、command: npx @shakaran/symfony-agent-mcp

---

機能

16 カテゴリーにわたる 1,677 個のツール

Available tool categories (16 categories, 1,677 tools total, ~164,615 tokens if all active)

  Category         │ Tools      │ Est. tokens    │ Description
  ─────────────────┼────────────┼───────────────┼────────────────────────────────────────────────────────
  symfony-core     │  548 tools │ ~ 53939 tokens │ Routes, services, controllers, events, commands, bundles, DI container, kernel
  database         │  176 tools │ ~ 17121 tokens │ Entities, migrations, Doctrine ORM, relationships, query patterns, indexes, DBAL
  security         │  132 tools │ ~ 12950 tokens │ Voters, firewalls, authenticators, JWT, OAuth, CSRF, access control, secrets vault
  frontend         │  121 tools │ ~ 11568 tokens │ Twig, translations, asset mapper, Symfony UX, Turbo, live components, Webpack
  testing          │  110 tools │ ~ 10559 tokens │ PHPUnit, Behat, Cypress, Playwright, Psalm, PHPStan, Rector, static analysis
  integrations     │  106 tools │ ~ 10939 tokens │ Stripe, Slack, Sentry, Elasticsearch, Twilio, SendGrid, Mailgun, Datadog, OpenAI
  serializer       │   91 tools │ ~  9031 tokens │ Serializer, validation, forms, constraints, DTOs, transformers, normalizers
  messaging        │   87 tools │ ~  8455 tokens │ Messenger, notifier, webhooks, Mercure, mailer, transports, stamps, failure handling
  api              │   68 tools │ ~  6438 tokens │ API Platform, OpenAPI, GraphQL, REST patterns, versioning, rate limits, Nelmio
  infrastructure   │   68 tools │ ~  6794 tokens │ Docker, CI/CD, Kubernetes, Terraform, Helm, Nginx, serverless, cloud platforms
  cache-sessions   │   62 tools │ ~  5945 tokens │ Cache pools, HTTP cache, sessions, rate limiter, lock, cache warmers, OPcache
  config           │   35 tools │ ~  3157 tokens │ Environment config, framework settings, Monolog, CORS, locale, feature flags
  code-quality     │   25 tools │ ~  2447 tokens │ Profiler, dead code detection, dependency graph, accessibility, code metrics
  cloud-aws        │   18 tools │ ~  1945 tokens │ AWS S3, SES, Cognito, ECS, Lambda/Bref, Parameter Store, Secrets Manager, CloudFront
  cloud-other      │   16 tools │ ~  1851 tokens │ Azure Blob/Pipelines, Google Cloud Run/Storage, Firebase, DigitalOcean, Consul
  queues           │   14 tools │ ~  1476 tokens │ RabbitMQ, Kafka, SQS FIFO/DLQ, Pusher, Redis pub/sub and streams

To activate a category: call activate_category(category: "<key>")
To search for specific tools: call search_tools(query: "what you want to do")

セキュリティを最優先した設計

• 読み取り専用 — 書き込み、変更、実行は一切行いません
• 自動マスキング — パスワード、トークン、API キー、データベースの認証情報は、AI にデータが渡される前に [REDACTED] に置き換えられます
• DLP パイプライン — 多層のデータ損失防止スキャナー（正規表現パターンと、クレジットカード、JWT、SSH キー、クラウド認証情報などの構造検出）
• パス検証 — ディレクトリトラバーサル攻撃は入力レイヤーでブロックされます
• コード実行なし — PHP ファイルは静的に解析されます（eval も PHP ランタイムも使用しません）
• ネットワーク呼び出しなし — すべてのデータはローカルファイルのみから取得します
• プロンプトインジェクションフィルター — ツールの出力は AI に転送される前にインジェクションパターンをスキャンされます

---

クイックスタート

オプション A：npx（インストール不要）

npx @shakaran/symfony-agent-mcp

オプション B：グローバルにインストール

npm install -g @shakaran/symfony-agent-mcp
symfony-agent-mcp

オプション C：ソースから

git clone https://github.com/shakaran/symfony-agent-mcp
cd symfony-agent-mcp
pnpm install
pnpm build
pnpm start

Node.js のセットアップ、トラブルシューティング、初回使用時の確認を含む手順ガイドについては、GETTING_STARTED.md を参照してください。

---

連携

ワンクリックインストール

クライアント	インストール
Cursor
VS Code
VS Code Insiders
Windsurf
Claude Code
Claude Desktop

Claude Code

サーバーを登録するには、一度だけ次のコマンドを実行します。

# npx (no local install required)
claude mcp add symfony -- npx @shakaran/symfony-agent-mcp

# Or from a local source build
claude mcp add symfony -- node /path/to/symfony-agent-mcp/dist/server.js

すべてのプロジェクトでグローバルに利用できるようにするには、--scope user フラグを追加します。

claude mcp add --scope user symfony -- npx @shakaran/symfony-agent-mcp

Claude Desktop

Claude Desktop の設定ファイル（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "symfony": {
      "command": "npx",
      "args": ["@shakaran/symfony-agent-mcp"]
    }
  }
}

Cursor

.cursor/mcp.json に追加します。

{
  "symfony": {
    "command": "npx",
    "args": ["@shakaran/symfony-agent-mcp"]
  }
}

VS Code Copilot

.vscode/mcp.json に追加します。

{
  "servers": {
    "symfony": {
      "type": "stdio",
      "command": "npx",
      "args": ["@shakaran/symfony-agent-mcp"]
    }
  }
}

---

使用方法

すべてのツールは、Symfony アプリケーションのルートを指定する app_path パラメーターを受け取ります。

list_routes(app_path: "/var/www/myapp")
→ Found 42 routes: GET /api/users [api_users], POST /login [app_login], …

get_entity_details(app_path: "/var/www/myapp", entity_name: "User")
→ Entity: User  |  Table: users
  Properties: id (int, PK), email (string 180), isActive (bool)
  Relationships: OneToMany → Post (author)

get_error_summary(app_path: "/var/www/myapp")
→ Last 24h: 3 CRITICAL, 12 ERROR, 47 WARNING

get_code_quality_report(app_path: "/var/www/myapp")
→ God classes: UserManager (1240 lines), dead services: 4, N+1 risks: 7

Claude で使用できるプロンプトの例：

• 「POST メソッドを持つすべてのルートと、そのコントローラーを表示してください」
• 「doctrine.event_listener タグが付いたサービスはどれですか？」
• 「本番ログの最後の 50 行を一覧表示してください」
• 「サービスコンテナーに循環依存はありますか？」
• 「User とリレーションを持つ Doctrine エンティティは何ですか？」
• 「マイグレーション履歴と、破壊的なマイグレーションがあれば表示してください」
• 「セキュリティ属性が設定されていないコントローラーはどれですか？」

---

設定

すべての設定は、MCP サーバープロセスに渡される環境変数で行います。

ツールの検出

変数	デフォルト	説明
SYMFONY_MCP_DYNAMIC_TOOLS	true	動的なツール検出を有効にします。true の場合、tools/list は 1,677 個すべてではなく、5 個のメタツールのみを返します。従来の動作（常にすべてのツールを表示）に戻すには、false に設定します。
SYMFONY_MCP_TOKEN_BUDGET	40000	セッションごとに有効化できるトークンの推定最大数です。この上限を超える場合は有効化がブロックされます。上書きするには、activate_category に force=true を渡します。

セキュリティとアクセス

変数	デフォルト	説明
SYMFONY_MCP_ALLOWED_PATHS	(任意)	サーバーによる検査を許可するアプリケーションの絶対パスを、コロン区切りで指定します。例：/var/www/app1:/var/www/app2
SYMFONY_MCP_REQUIRE_SYMFONY	true	Symfony プロジェクトの検証をスキップするには、false に設定します（テストに便利です）。
SYMFONY_MCP_ALLOWED_TOOLS	(すべて)	ツール名の許可リストをカンマ区切りで指定します。リストにあるツールのみ呼び出せます。
SYMFONY_MCP_BLOCKED_TOOLS	(なし)	拒否リストをカンマ区切りで指定します。許可リストより優先されます。
SYMFONY_MCP_SIGNING_SECRET	(無効)	リクエスト署名用の 32 文字以上のシークレットです。有効にすると、リクエストごとの認証が行われます。
SYMFONY_MCP_SESSION_SECRET	(無効)	セッショントークン生成用のシークレットです。
SYMFONY_MCP_SESSION_TOKEN	(無効)	受信リクエストで検証するトークンです。
SYMFONY_MCP_SESSION_STRICT	false	有効なセッショントークンのないリクエストを拒否するには、true に設定します。
SYMFONY_MCP_SESSION_WINDOW	300	セッショントークンの有効期間（秒）です。

レート制限

変数	デフォルト	説明
SYMFONY_MCP_RATE_LIMIT	60	期間ごとの最大リクエスト数です。無効にするには 0 に設定します。
SYMFONY_MCP_RATE_WINDOW_MS	60000	レート制限の期間（ミリ秒、1 分）です。
SYMFONY_MCP_RATE_BURST	10	1 秒あたりの最大バーストリクエスト数です。

トランスポート

変数	デフォルト	説明
SYMFONY_MCP_HTTP_PORT	(off)	HTTP/SSE トランスポート用のポートです。設定すると、stdio に加えて HTTP サーバーを起動します。
SYMFONY_MCP_STDIO	true	stdio トランスポートを無効にするには false に設定します（HTTP のみで実行する場合に便利です）。
SYMFONY_MCP_TOOL_TIMEOUT_MS	30000	ツールごとの実行タイムアウト（ミリ秒）です。

例：動的ツールを無効にした Claude Code

{
  "mcpServers": {
    "symfony": {
      "command": "npx",
      "args": ["@shakaran/symfony-agent-mcp"],
      "env": {
        "SYMFONY_MCP_DYNAMIC_TOOLS": "false"
      }
    }
  }
}

例：トークンの上限を 80 000 トークンに増やす

{
  "mcpServers": {
    "symfony": {
      "command": "node",
      "args": ["/path/to/symfony-agent-mcp/dist/server.js"],
      "env": {
        "SYMFONY_MCP_TOKEN_BUDGET": "80000"
      }
    }
  }
}

---

ローカルインストール（ソースから）

ローカルのクローンからサーバーを実行する場合は、こちらを使用してください（npm で公開する必要はありません）。

# 1. Clone the repo
git clone https://github.com/shakaran/symfony-agent-mcp
cd symfony-agent-mcp

# 2. Install dependencies (Node.js ≥ 22 required)
pnpm install         # or: npm install

# 3. Build TypeScript → dist/
pnpm build           # or: npm run build

# 4. Test the server responds
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/server.js

次に、ビルドしたファイルを参照するように MCP クライアントを設定します。

Claude Code（一度だけ実行）：

claude mcp add symfony -- node /absolute/path/to/symfony-agent-mcp/dist/server.js

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "symfony": {
      "command": "node",
      "args": ["/absolute/path/to/symfony-agent-mcp/dist/server.js"]
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "symfony": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/symfony-agent-mcp/dist/server.js"]
    }
  }
}

ヒント： 再ビルド（pnpm build）した後、変更を反映するために MCP クライアントを再起動してください。

---

読み取り対象

このサーバーは Symfony アプリからファイルを直接読み取ります。データベース接続も PHP ランタイムも必要ありません。

• config/routes.yaml、config/routes/*.yaml — YAML ルート
• src/Controller/ 内のコントローラーにある PHP 8 の #[Route] 属性
• config/services.yaml — DI コンテナーのサービス
• config/packages/*.yaml — フレームワーク、セキュリティ、Doctrine、Messenger、Mailer の設定
• src/Entity/*.php — Doctrine エンティティファイル（PHP 8 の属性とアノテーション）
• var/log/*.log — アプリケーションログ
• migrations/、src/Migrations/ — Doctrine のマイグレーションファイル
• composer.json、composer.lock — パッケージ情報
• .env、.env.local、.env.*.local — 環境変数（機密値は自動的にマスキングされます）

---

Symfony の互換性

Symfony	PHP	ORM マッピング
5.4 LTS	8.0+	アノテーションまたは属性
6.x	8.0+	属性
7.x	8.2+	属性
8.x	8.2+	属性

---

要件

• Node.js ≥ 22.0.0
• pnpm ≥ 11.0.0（または開発用の npm/yarn）

---

開発

pnpm install
pnpm dev            # watch mode (TypeScript → dist/)
pnpm test           # run all tests
pnpm lint           # ESLint
pnpm typecheck      # tsc --noEmit

開発ガイドの全文（アーキテクチャの概要、新しいツールの追加、テスト戦略、コントリビューションのガイドライン）については、DEVELOPMENT.md を参照してください。

---

ドキュメント

ドキュメント	説明
GETTING_STARTED.md	手順に沿ったセットアップ、Node.js の前提条件、トラブルシューティング
ARCHITECTURE.md	システム設計、セキュリティパイプライン、コンポーネントの概要、16 カテゴリーにわたる全 1,677 ツールの説明
DEVELOPMENT.md	開発ワークフロー、ツールの追加、テスト、コントリビューション
SECURITY.md	脅威モデル、DLP パイプライン、責任ある脆弱性開示ポリシー
CHANGELOG.md	リリース履歴とロードマップ
PROJECT_SUMMARY.md	プロジェクトの概要と統計

---

貢献

Issue やプルリクエストは、github.com/shakaran/symfony-agent-mcp で歓迎します。

PR を送信する前に DEVELOPMENT.md を、責任ある脆弱性開示ポリシーについては SECURITY.md をお読みください。

---

プロジェクトの標準

標準	状況
OpenSSF Baseline	レベル 1、2、3
OpenSSF Best Practices	合格
OpenSSF Scorecard	7.4 / 10
サプライチェーン	SLSA provenance と SBOM を含め、CI から公開
再現可能なビルド	CI で検証済み。ビルド間でバイト単位の一致を確認
コードスキャン	未解決のアラートなし
シークレットスキャン	未解決のアラートなし
テスト	1,019 件 — src/utils/ は 100%、トランスポートは 99.5%
ライセンス	MIT。すべてのソースファイルに SPDX ヘッダーを記載
サインオフ	Developer Certificate of Origin。CI で確認

脅威モデル、保証ケース、修正のしきい値については SECURITY.md を、今後の計画については ROADMAP.md をご覧ください。

ライセンス

MIT © Ángel Guzmán Maeso