Symfony Agent MCP

symfony-agent-mcp

功能 • 快速开始 • 集成 • 使用方法 • 文档 • 参与贡献 • 许可证

---

适用于生产环境的 Symfony 应用模型上下文协议（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

---

功能

1,677 个工具，分为 16 类

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

请参阅 GETTING_STARTED.md，了解分步指南，其中包括 Node.js 设置、故障排查和首次使用验证。

---

集成

一键安装

客户端	安装
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"]
    }
  }
}

---

使用

每个工具都接受一个 app_path 参数，用于指向 Symfony 应用的根目录：

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 行”
• “服务容器中是否存在循环依赖？”
• “哪些 Doctrine 实体与 User 存在关联？”
• “显示迁移历史记录以及所有具有破坏性的迁移”
• “哪些控制器没有安全属性？”

---

配置

所有配置均通过传递给 MCP 服务进程的环境变量完成。

工具发现

变量	默认值	描述
SYMFONY_MCP_DYNAMIC_TOOLS	true	启用动态工具发现。设为 true 时，tools/list 只返回 5 个元工具，而非全部 1,677 个。设为 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	设为 false 可跳过 Symfony 项目验证（适用于测试）。
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	设置为 false 可禁用 stdio 传输（仅运行 HTTP 时很有用）。
SYMFONY_MCP_TOOL_TIMEOUT_MS	30000	每个工具的执行超时时间，以毫秒为单位。

示例：禁用动态工具的 Claude Code

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

示例：将 token 预算提高到 80 000 tokens

{
  "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 — Framework、security、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	项目概要和统计数据

---

贡献

欢迎通过 github.com/shakaran/symfony-agent-mcp 提交问题和拉取请求。

提交 PR 前，请先阅读 DEVELOPMENT.md；关于负责任的信息披露政策，请阅读 SECURITY.md。

---

项目标准

标准	状态
OpenSSF Baseline	Level 1、2 和 3
OpenSSF Best Practices	已通过
OpenSSF Scorecard	7.4 / 10
供应链	通过 CI 发布，包含 SLSA 来源证明和 SBOM
可复现构建	已在 CI 中验证，不同构建的字节完全一致
代码扫描	未解决的警报数为零
密钥扫描	未解决的警报数为零
测试	1,019 项 — src/utils/ 覆盖率为 100%，传输层为 99.5%
许可	MIT，每个源文件均包含 SPDX 标头
签署确认	开发者原创证明，已在 CI 中检查

威胁模型、保证论证和修复阈值请参阅 SECURITY.md， 计划内容请参阅 ROADMAP.md。

许可证

MIT © Ángel Guzmán Maeso