symfony-agent-mcp

Features • Quick Start • Integration • Usage • Documentation • Contributing • License

---

A production-ready Model Context Protocol (MCP) server for Symfony applications. Gives AI assistants deep, read-only introspection into your entire Symfony codebase — routes, controllers, services, entities, database schema, migrations, events, forms, security, Doctrine, Messenger, Twig, API Platform, and much more.

---

Features

1,677 Tools across 16 Categories

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")

Security-first design

• Read-only — never writes, modifies, or executes anything
• Auto-redaction — passwords, tokens, API keys, and database credentials are replaced with [REDACTED] before any data reaches the AI
• DLP pipeline — multi-layer Data Loss Prevention scanner (regex patterns + structural detection for credit cards, JWTs, SSH keys, cloud credentials, etc.)
• Path validation — directory traversal attacks are blocked at the input layer
• No code execution — PHP files are parsed statically (no eval, no PHP runtime)
• No network calls — all data comes from local files only
• Prompt injection filter — tool output is scanned for injection patterns before being forwarded to the AI

---

Quick Start

Option A: npx (no install required)

npx @shakaran/symfony-agent-mcp

Option B: Install globally

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

Option C: From source

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

See GETTING_STARTED.md for a step-by-step guide including Node.js setup, troubleshooting, and first-use verification.

---

Integration

One-click Install

Claude Code

Run once to register the server:

# 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

To make it available globally across all projects, add the --scope user flag:

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

Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

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

Cursor

Add to .cursor/mcp.json:

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

VS Code Copilot

Add to .vscode/mcp.json:

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

---

Usage

Every tool accepts an app_path parameter pointing to the root of your Symfony application:

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

Example prompts you can use with Claude:

• "Show me all routes with POST methods and their controllers"
• "Which services are tagged with doctrine.event_listener?"
• "List the last 50 lines of the production log"
• "Are there any circular dependencies in the service container?"
• "What Doctrine entities have relationships with User?"
• "Show me the migration history and any destructive migrations"
• "Which controllers have no security attributes?"

---

Configuration

All configuration is done via environment variables passed to the MCP server process.

Tool Discovery

Security & Access

Rate Limiting

Transport

Example: Claude Code with dynamic tools disabled

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

Example: token budget increased to 80 000 tokens

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

---

Local Install (from source)

Use this when you want to run the server from a local clone (no npm publish needed).

# 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

Then configure your MCP client to point at the built file:

Claude Code (run once):

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"]
    }
  }
}

Tip: After rebuilding (pnpm build), restart your MCP client to pick up the changes.

---

What It Reads

The server reads files directly from your Symfony app — no database connection, no PHP runtime needed:

• config/routes.yaml, config/routes/*.yaml — YAML routes
• PHP 8 #[Route] attributes on controllers in src/Controller/
• config/services.yaml — DI container services
• config/packages/*.yaml — Framework, security, doctrine, messenger, mailer config
• src/Entity/*.php — Doctrine entity files (PHP 8 attributes + annotations)
• var/log/*.log — Application logs
• migrations/, src/Migrations/ — Doctrine migration files
• composer.json, composer.lock — Package info
• .env, .env.local, .env.*.local — Environment variables (sensitive values auto-redacted)

---

Symfony Compatibility

---

Requirements

• Node.js ≥ 22.0.0
• pnpm ≥ 11.0.0 (or npm/yarn for development)

---

Development

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

See DEVELOPMENT.md for the full development guide: architecture overview, adding new tools, testing strategy, and contribution guidelines.

---

Documentation

---

Contributing

Issues and pull requests are welcome at github.com/shakaran/symfony-agent-mcp.

Please read DEVELOPMENT.md before submitting a PR, and SECURITY.md for the responsible disclosure policy.

---

Project standards

See SECURITY.md for the threat model, the assurance case and the remediation thresholds, and ROADMAP.md for what is planned.

License

MIT © Ángel Guzmán Maeso