{ "markdown": "# symfony-agent-mcp\n\n[![npm version](https://img.shields.io/npm/v/@shakaran/symfony-agent-mcp)](https://www.npmjs.com/package/@shakaran/symfony-agent-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)\n[![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](DEVELOPMENT.md)\n[![GitHub issues](https://img.shields.io/github/issues/shakaran/symfony-agent-mcp)](https://github.com/shakaran/symfony-agent-mcp/issues)\n[![GitHub stars](https://img.shields.io/github/stars/shakaran/symfony-agent-mcp)](https://github.com/shakaran/symfony-agent-mcp/stargazers)\n[![Build Status](https://github.com/shakaran/symfony-agent-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/shakaran/symfony-agent-mcp/actions)\n[![Coverage](https://codecov.io/gh/shakaran/symfony-agent-mcp/graph/badge.svg)](https://codecov.io/gh/shakaran/symfony-agent-mcp)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/shakaran/symfony-agent-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/shakaran/symfony-agent-mcp)\n[![Glama score](https://glama.ai/mcp/servers/shakaran/symfony-agent-mcp/badges/score.svg)](https://glama.ai/mcp/servers/shakaran/symfony-agent-mcp)\n[![smithery badge](https://smithery.ai/badge/shakaran/symfony-agent-mcp)](https://smithery.ai/servers/shakaran/symfony-agent-mcp)\n[![OpenSSF Baseline](https://www.bestpractices.dev/projects/14217/baseline)](https://www.bestpractices.dev/projects/14217)\n\n[Features](#features) • [Quick Start](#quick-start) • [Integration](#integration) • [Usage](#usage) • [Documentation](#documentation) • [Contributing](#contributing) • [License](#license)\n\n---\n\nA production-ready **Model Context Protocol (MCP) server** for Symfony applications.\nGives AI assistants deep, read-only introspection into your entire Symfony codebase —\nroutes, controllers, services, entities, database schema, migrations, events, forms,\nsecurity, Doctrine, Messenger, Twig, API Platform, and much more.\n\n| Client | Install |\n|---------------------|----------------------------------------------------------------|\n| **Claude Code** | Run `claude mcp add` → [setup](#claude-code) |\n| **Claude Desktop** | Add to `claude_desktop_config.json` → [setup](#claude-desktop) |\n| **Cursor** | Add to `.cursor/mcp.json` → [setup](#cursor) |\n| **VS Code Copilot** | Add to `.vscode/mcp.json` → [setup](#vs-code-copilot) |\n| **Any MCP client** | stdio transport, `command: npx @shakaran/symfony-agent-mcp` |\n\n---\n\n## Features\n\n### 1,677 Tools across 16 Categories\n\n```text\nAvailable tool categories (16 categories, 1,677 tools total, ~164,615 tokens if all active)\n\n Category │ Tools │ Est. tokens │ Description\n ─────────────────┼────────────┼───────────────┼────────────────────────────────────────────────────────\n symfony-core │ 548 tools │ ~ 53939 tokens │ Routes, services, controllers, events, commands, bundles, DI container, kernel\n database │ 176 tools │ ~ 17121 tokens │ Entities, migrations, Doctrine ORM, relationships, query patterns, indexes, DBAL\n security │ 132 tools │ ~ 12950 tokens │ Voters, firewalls, authenticators, JWT, OAuth, CSRF, access control, secrets vault\n frontend │ 121 tools │ ~ 11568 tokens │ Twig, translations, asset mapper, Symfony UX, Turbo, live components, Webpack\n testing │ 110 tools │ ~ 10559 tokens │ PHPUnit, Behat, Cypress, Playwright, Psalm, PHPStan, Rector, static analysis\n integrations │ 106 tools │ ~ 10939 tokens │ Stripe, Slack, Sentry, Elasticsearch, Twilio, SendGrid, Mailgun, Datadog, OpenAI\n serializer │ 91 tools │ ~ 9031 tokens │ Serializer, validation, forms, constraints, DTOs, transformers, normalizers\n messaging │ 87 tools │ ~ 8455 tokens │ Messenger, notifier, webhooks, Mercure, mailer, transports, stamps, failure handling\n api │ 68 tools │ ~ 6438 tokens │ API Platform, OpenAPI, GraphQL, REST patterns, versioning, rate limits, Nelmio\n infrastructure │ 68 tools │ ~ 6794 tokens │ Docker, CI/CD, Kubernetes, Terraform, Helm, Nginx, serverless, cloud platforms\n cache-sessions │ 62 tools │ ~ 5945 tokens │ Cache pools, HTTP cache, sessions, rate limiter, lock, cache warmers, OPcache\n config │ 35 tools │ ~ 3157 tokens │ Environment config, framework settings, Monolog, CORS, locale, feature flags\n code-quality │ 25 tools │ ~ 2447 tokens │ Profiler, dead code detection, dependency graph, accessibility, code metrics\n cloud-aws │ 18 tools │ ~ 1945 tokens │ AWS S3, SES, Cognito, ECS, Lambda/Bref, Parameter Store, Secrets Manager, CloudFront\n cloud-other │ 16 tools │ ~ 1851 tokens │ Azure Blob/Pipelines, Google Cloud Run/Storage, Firebase, DigitalOcean, Consul\n queues │ 14 tools │ ~ 1476 tokens │ RabbitMQ, Kafka, SQS FIFO/DLQ, Pusher, Redis pub/sub and streams\n\nTo activate a category: call activate_category(category: \"\")\nTo search for specific tools: call search_tools(query: \"what you want to do\")\n```\n\n### [Security-first design](SECURITY.md)\n\n- **Read-only** — never writes, modifies, or executes anything\n- **Auto-redaction** — passwords, tokens, API keys, and database credentials are replaced with `[REDACTED]` before any data reaches the AI\n- **DLP pipeline** — multi-layer Data Loss Prevention scanner (regex patterns + structural detection for credit cards, JWTs, SSH keys, cloud credentials, etc.)\n- **Path validation** — directory traversal attacks are blocked at the input layer\n- **No code execution** — PHP files are parsed statically (no `eval`, no PHP runtime)\n- **No network calls** — all data comes from local files only\n- **Prompt injection filter** — tool output is scanned for injection patterns before being forwarded to the AI\n\n---\n\n## Quick Start\n\n### Option A: npx (no install required)\n\n```bash\nnpx @shakaran/symfony-agent-mcp\n```\n\n### Option B: Install globally\n\n```bash\nnpm install -g @shakaran/symfony-agent-mcp\nsymfony-agent-mcp\n```\n\n### Option C: From source\n\n```bash\ngit clone https://github.com/shakaran/symfony-agent-mcp\ncd symfony-agent-mcp\npnpm install\npnpm build\npnpm start\n```\n\nSee [GETTING_STARTED.md](GETTING_STARTED.md) for a step-by-step guide including Node.js setup, troubleshooting, and first-use verification.\n\n---\n\n## Integration\n\n### One-click Install\n\n| Client | Install |\n|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Cursor** | \"Install |\n| **VS Code** | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22symfony-agent-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40shakaran%2Fsymfony-agent-mcp%22%5D%7D) |\n| **VS Code Insiders** | [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22symfony-agent-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40shakaran%2Fsymfony-agent-mcp%22%5D%7D) |\n| **Windsurf** | [![Install in Windsurf](https://img.shields.io/badge/Windsurf-Install_MCP_Server-00B8A9?style=for-the-badge&logo=codeium&logoColor=white)](https://windsurf.com/editor/directory/mcp/install?name=symfony-agent-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAc2hha2FyYW4vc3ltZm9ueS1hZ2VudC1tY3AiXX0=) |\n| **Claude Code** | [![Install in Claude Code](https://img.shields.io/badge/Claude_Code-Add_MCP_Server-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](#claude-code) |\n| **Claude Desktop** | [![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Add_MCP_Server-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](#claude-desktop) |\n\n### Claude Code\n\nRun once to register the server:\n\n```bash\n# npx (no local install required)\nclaude mcp add symfony -- npx @shakaran/symfony-agent-mcp\n\n# Or from a local source build\nclaude mcp add symfony -- node /path/to/symfony-agent-mcp/dist/server.js\n```\n\nTo make it available globally across all projects, add the `--scope user` flag:\n\n```bash\nclaude mcp add --scope user symfony -- npx @shakaran/symfony-agent-mcp\n```\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration file (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"symfony\": {\n \"command\": \"npx\",\n \"args\": [\"@shakaran/symfony-agent-mcp\"]\n }\n }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n \"symfony\": {\n \"command\": \"npx\",\n \"args\": [\"@shakaran/symfony-agent-mcp\"]\n }\n}\n```\n\n### VS Code Copilot\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"symfony\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"@shakaran/symfony-agent-mcp\"]\n }\n }\n}\n```\n\n---\n\n## Usage\n\nEvery tool accepts an `app_path` parameter pointing to the root of your Symfony application:\n\n```text\nlist_routes(app_path: \"/var/www/myapp\")\n→ Found 42 routes: GET /api/users [api_users], POST /login [app_login], …\n\nget_entity_details(app_path: \"/var/www/myapp\", entity_name: \"User\")\n→ Entity: User | Table: users\n Properties: id (int, PK), email (string 180), isActive (bool)\n Relationships: OneToMany → Post (author)\n\nget_error_summary(app_path: \"/var/www/myapp\")\n→ Last 24h: 3 CRITICAL, 12 ERROR, 47 WARNING\n\nget_code_quality_report(app_path: \"/var/www/myapp\")\n→ God classes: UserManager (1240 lines), dead services: 4, N+1 risks: 7\n```\n\nExample prompts you can use with Claude:\n\n- *\"Show me all routes with POST methods and their controllers\"*\n- *\"Which services are tagged with `doctrine.event_listener`?\"*\n- *\"List the last 50 lines of the production log\"*\n- *\"Are there any circular dependencies in the service container?\"*\n- *\"What Doctrine entities have relationships with User?\"*\n- *\"Show me the migration history and any destructive migrations\"*\n- *\"Which controllers have no security attributes?\"*\n\n---\n\n## Configuration\n\nAll configuration is done via environment variables passed to the MCP server process.\n\n### Tool Discovery\n\n| Variable | Default | Description |\n|-----------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `SYMFONY_MCP_DYNAMIC_TOOLS` | `true` | Enable dynamic tool discovery. When `true`, `tools/list` returns only 5 meta-tools instead of all 1,677. Set to `false` to restore the legacy behaviour (all tools always visible). |\n| `SYMFONY_MCP_TOKEN_BUDGET` | `40000` | Maximum estimated tokens that can be activated per session. Activation is blocked when this limit would be exceeded; pass `force=true` in `activate_category` to override. |\n\n### Security & Access\n\n| Variable | Default | Description |\n|-------------------------------|----------|-----------------------------------------------------------------------------------------------------------|\n| `SYMFONY_MCP_ALLOWED_PATHS` | *(any)* | Colon-separated list of absolute app paths the server may inspect. Example: `/var/www/app1:/var/www/app2` |\n| `SYMFONY_MCP_REQUIRE_SYMFONY` | `true` | Set to `false` to skip Symfony project validation (useful for testing). |\n| `SYMFONY_MCP_ALLOWED_TOOLS` | *(all)* | Comma-separated allowlist of tool names. Only listed tools are callable. |\n| `SYMFONY_MCP_BLOCKED_TOOLS` | *(none)* | Comma-separated denylist. Takes precedence over the allowlist. |\n| `SYMFONY_MCP_SIGNING_SECRET` | *(off)* | 32+ character secret for request signing. Enables per-request authentication. |\n| `SYMFONY_MCP_SESSION_SECRET` | *(off)* | Secret for session token generation. |\n| `SYMFONY_MCP_SESSION_TOKEN` | *(off)* | Token to validate on incoming requests. |\n| `SYMFONY_MCP_SESSION_STRICT` | `false` | Set to `true` to reject requests without a valid session token. |\n| `SYMFONY_MCP_SESSION_WINDOW` | `300` | Session token validity window in seconds. |\n\n### Rate Limiting\n\n| Variable | Default | Description |\n|------------------------------|---------|-------------------------------------------------|\n| `SYMFONY_MCP_RATE_LIMIT` | `60` | Max requests per window. Set to `0` to disable. |\n| `SYMFONY_MCP_RATE_WINDOW_MS` | `60000` | Rate limit window in milliseconds (1 minute). |\n| `SYMFONY_MCP_RATE_BURST` | `10` | Max burst requests in 1 second. |\n\n### Transport\n\n| Variable | Default | Description |\n|-------------------------------|---------|------------------------------------------------------------------------------------|\n| `SYMFONY_MCP_HTTP_PORT` | *(off)* | Port for HTTP/SSE transport. When set, starts an HTTP server in addition to stdio. |\n| `SYMFONY_MCP_STDIO` | `true` | Set to `false` to disable stdio transport (useful when running HTTP-only). |\n| `SYMFONY_MCP_TOOL_TIMEOUT_MS` | `30000` | Per-tool execution timeout in milliseconds. |\n\n### Example: Claude Code with dynamic tools disabled\n\n```json\n{\n \"mcpServers\": {\n \"symfony\": {\n \"command\": \"npx\",\n \"args\": [\"@shakaran/symfony-agent-mcp\"],\n \"env\": {\n \"SYMFONY_MCP_DYNAMIC_TOOLS\": \"false\"\n }\n }\n }\n}\n```\n\n### Example: token budget increased to 80 000 tokens\n\n```json\n{\n \"mcpServers\": {\n \"symfony\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/symfony-agent-mcp/dist/server.js\"],\n \"env\": {\n \"SYMFONY_MCP_TOKEN_BUDGET\": \"80000\"\n }\n }\n }\n}\n```\n\n---\n\n## Local Install (from source)\n\nUse this when you want to run the server from a local clone (no npm publish needed).\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/shakaran/symfony-agent-mcp\ncd symfony-agent-mcp\n\n# 2. Install dependencies (Node.js ≥ 22 required)\npnpm install # or: npm install\n\n# 3. Build TypeScript → dist/\npnpm build # or: npm run build\n\n# 4. Test the server responds\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node dist/server.js\n```\n\nThen configure your MCP client to point at the built file:\n\n**Claude Code** (run once):\n\n```bash\nclaude mcp add symfony -- node /absolute/path/to/symfony-agent-mcp/dist/server.js\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"symfony\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/symfony-agent-mcp/dist/server.js\"]\n }\n }\n}\n```\n\n**VS Code** (`.vscode/mcp.json`):\n\n```json\n{\n \"servers\": {\n \"symfony\": {\n \"type\": \"stdio\",\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/symfony-agent-mcp/dist/server.js\"]\n }\n }\n}\n```\n\n> **Tip:** After rebuilding (`pnpm build`), restart your MCP client to pick up the changes.\n\n---\n\n## What It Reads\n\nThe server reads files directly from your Symfony app — no database connection, no PHP runtime needed:\n\n- `config/routes.yaml`, `config/routes/*.yaml` — YAML routes\n- PHP 8 `#[Route]` attributes on controllers in `src/Controller/`\n- `config/services.yaml` — DI container services\n- `config/packages/*.yaml` — Framework, security, doctrine, messenger, mailer config\n- `src/Entity/*.php` — Doctrine entity files (PHP 8 attributes + annotations)\n- `var/log/*.log` — Application logs\n- `migrations/`, `src/Migrations/` — Doctrine migration files\n- `composer.json`, `composer.lock` — Package info\n- `.env`, `.env.local`, `.env.*.local` — Environment variables (sensitive values auto-redacted)\n\n---\n\n## Symfony Compatibility\n\n| Symfony | PHP | ORM mapping |\n|---------|------|---------------------------|\n| 5.4 LTS | 8.0+ | Annotations or Attributes |\n| 6.x | 8.0+ | Attributes |\n| 7.x | 8.2+ | Attributes |\n| 8.x | 8.2+ | Attributes |\n\n---\n\n## Requirements\n\n- **Node.js** ≥ 22.0.0\n- **pnpm** ≥ 11.0.0 (or npm/yarn for development)\n\n---\n\n## Development\n\n```bash\npnpm install\npnpm dev # watch mode (TypeScript → dist/)\npnpm test # run all tests\npnpm lint # ESLint\npnpm typecheck # tsc --noEmit\n```\n\nSee [DEVELOPMENT.md](DEVELOPMENT.md) for the full development guide: architecture overview, adding new tools, testing strategy, and contribution guidelines.\n\n---\n\n## Documentation\n\n| Document | Description |\n|------------------------------------------|-------------------------------------------------------------------------------------------------------|\n| [GETTING_STARTED.md](GETTING_STARTED.md) | Step-by-step setup, Node.js prerequisites, troubleshooting |\n| [ARCHITECTURE.md](ARCHITECTURE.md) | System design, security pipeline, component overview, all 1,677 tools across 16 categories documented |\n| [DEVELOPMENT.md](DEVELOPMENT.md) | Development workflow, adding tools, testing, contributing |\n| [SECURITY.md](SECURITY.md) | Threat model, DLP pipeline, responsible disclosure policy |\n| [CHANGELOG.md](CHANGELOG.md) | Release history and roadmap |\n| [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) | High-level project overview and statistics |\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome at [github.com/shakaran/symfony-agent-mcp](https://github.com/shakaran/symfony-agent-mcp).\n\nPlease read [DEVELOPMENT.md](DEVELOPMENT.md) before submitting a PR, and [SECURITY.md](SECURITY.md) for the responsible disclosure policy.\n\n---\n\n## Project standards\n\n| Standard | Status |\n|------------------------|--------------------------------------------------|\n| OpenSSF Baseline | Level 1, 2 and 3 |\n| OpenSSF Best Practices | Passing |\n| OpenSSF Scorecard | 7.4 / 10 |\n| Supply chain | Published from CI with SLSA provenance and SBOM |\n| Reproducible build | Verified in CI, byte-identical across builds |\n| Code scanning | Zero open alerts |\n| Secret scanning | Zero open alerts |\n| Tests | 1,019 — `src/utils/` at 100%, transport at 99.5% |\n| Licensing | MIT, SPDX headers on every source file |\n| Sign-off | Developer Certificate of Origin, checked in CI |\n\nSee [SECURITY.md](SECURITY.md) for the threat model, the assurance case and the\nremediation thresholds, and [ROADMAP.md](ROADMAP.md) for what is planned.\n\n## License\n\nMIT © [Ángel Guzmán Maeso](https://github.com/shakaran)\n", "bytes": 21689, "sha": "c987159cbea2dccb668e6ba4b77d0b3eed7639db4f4fad47448b97c568d2353d", "repo_slug": "shakaran/symfony-agent-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_shakaran_symfony_agent_mcp_996b1316/readme" }