symfony-agent-mcp

# symfony-agent-mcp

[![npm version](https://img.shields.io/npm/v/@shakaran/symfony-agent-mcp)](https://www.npmjs.com/package/@shakaran/symfony-agent-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](DEVELOPMENT.md)
[![GitHub issues](https://img.shields.io/github/issues/shakaran/symfony-agent-mcp)](https://github.com/shakaran/symfony-agent-mcp/issues)
[![GitHub stars](https://img.shields.io/github/stars/shakaran/symfony-agent-mcp)](https://github.com/shakaran/symfony-agent-mcp/stargazers)
[![Build Status](https://github.com/shakaran/symfony-agent-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/shakaran/symfony-agent-mcp/actions)
[![Coverage](https://codecov.io/gh/shakaran/symfony-agent-mcp/graph/badge.svg)](https://codecov.io/gh/shakaran/symfony-agent-mcp)
[![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)
[![Glama score](https://glama.ai/mcp/servers/shakaran/symfony-agent-mcp/badges/score.svg)](https://glama.ai/mcp/servers/shakaran/symfony-agent-mcp)
[![smithery badge](https://smithery.ai/badge/shakaran/symfony-agent-mcp)](https://smithery.ai/servers/shakaran/symfony-agent-mcp)
[![OpenSSF Baseline](https://www.bestpractices.dev/projects/14217/baseline)](https://www.bestpractices.dev/projects/14217)

[Features](#features) • [Quick Start](#quick-start) • [Integration](#integration) • [Usage](#usage) • [Documentation](#documentation) • [Contributing](#contributing) • [License](#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.

| Client | Install |
| --- | --- |
| **Claude Code** | Run `claude mcp add` → [setup](#claude-code) |
| **Claude Desktop** | Add to `claude_desktop_config.json` → [setup](#claude-desktop) |
| **Cursor** | Add to `.cursor/mcp.json` → [setup](#cursor) |
| **VS Code Copilot** | Add to `.vscode/mcp.json` → [setup](#vs-code-copilot) |
| **Any MCP client** | stdio transport, `command: npx @shakaran/symfony-agent-mcp` |

---

## Features

### 1,677 Tools across 16 Categories

```text
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](SECURITY.md)

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

```bash
npx @shakaran/symfony-agent-mcp
```

### Option B: Install globally

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

### Option C: From source

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

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

---

## Integration

### One-click Install

| Client | Install |
| --- | --- |
| **Cursor** | <a href="https://cursor.com/install-mcp?name=symfony-agent-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAc2hha2FyYW4vc3ltZm9ueS1hZ2VudC1tY3AiXX0="><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/deeplink/mcp-install-dark.svg"><img alt="Install in Cursor" src="https://cursor.com/deeplink/mcp-install-light.svg"></picture></a> |
| **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) |
| **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) |
| **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=) |
| **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) |
| **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) |

### Claude Code

Run once to register the server:

```bash
# 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:

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

### Claude Desktop

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

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

### Cursor

Add to `.cursor/mcp.json`:

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

### VS Code Copilot

Add to `.vscode/mcp.json`:

```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:

```text
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"*
- *