MCP Symfony Prototype

MCP Symfony原型

企业级MCP服务器，根据OpenAPI规范自动生成工具，并通过 标准 和 HTTP流媒体 运输。专为合作伙伴集成和快速演示而构建。

特性

• 🤖 自动生成刀具：零手工工作-由OpenAPI/Swagger生成的工具
• ✅ 类型安全：完整的PHP 8.2+类型提示和验证
• 🔐 生产安全：在合作伙伴支持下进行承载令牌身份验证
• 🚀 双重运输：stdio（开发）+HTTP/SSE（生产合作伙伴）
• 📊 专业CLI：具有验证功能的丰富控制台命令
• 🐳 Docker就绪：完全容器化的开发环境

服务

• mcp服务器 （mcp-symfony服务器）：带HTTP端点的mcp服务器（端口8000）
• api网关 （mcp-api-gateway）：模拟api网关（端口8080）

快速开始

1.启动环境

docker-compose up -d

2.安装依赖项

# Install dependencies in MCP server
docker-compose exec mcp-server composer install

# Install dependencies in API Gateway
docker-compose exec api-gateway composer install

3.生成工具

# Generate MCP tools from OpenAPI specification
docker-compose exec mcp-server php bin/console mcp:generate-tools

输出：

✓ Generated: 3 tools
✗ Failed: 0 tools
⊘ Skipped: 0 tools

Tool Name                                Method  Path              Status
symfony-api-gateway:get_app_mockapi_listproducts     GET     /api/products     success
symfony-api-gateway:post_app_mockapi_createproduct   POST    /api/products     success
symfony-api-gateway:post_app_mockapi_createorder     POST    /api/orders       success

4.健康检查

# Test MCP HTTP endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Authorization: Bearer partner-secret-token-123" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

# Test API Gateway
curl http://localhost:8080/api/products \
  -H "Authorization: Bearer secret-123"

5.配置克劳德桌面

选项A:stdio（建议用于当地开发）

{
  "mcpServers": {
    "symfony-api-gateway": {
      "command": "docker",
      "args": [
        "exec", "-i",
        "-e", "API_GATEWAY_TOKEN=secret-123",
        "mcp-symfony-server",
        "php", "bin/console", "mcp:stdio"
      ]
    }
  }
}

注： API_GATEWAY_URL 默认为 http://api-gateway （Docker Compose网络）。只有在使用不同的API终结点时才指定它。

选项B:HTTP流式传输（适用于合作伙伴）

{
  "mcpServers": {
    "partner-api": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer partner-secret-token-123"
      }
    }
  }
}

6.在Claude Desktop中测试

• 重新启动克劳德桌面
• 寻找🔌 显示已连接服务器的图标
• 尝试：“列出所有产品”
• 尝试：“以99.99美元的价格创建一个名为‘演示小部件’的产品”

可用命令

工具管理

# Generate all tools from OpenAPI specification
docker-compose exec mcp-server php bin/console mcp:generate-tools

# Force regeneration (overwrites existing)
docker-compose exec mcp-server php bin/console mcp:generate-tools --force

# Dry run (show what would be generated)
docker-compose exec mcp-server php bin/console mcp:generate-tools --dry-run

# Use custom swagger URL
docker-compose exec mcp-server php bin/console mcp:generate-tools --swagger-url=http://other-api/swagger.json

验证与调试

# Validate swagger.json structure
docker-compose exec mcp-server php bin/console mcp:validate-swagger

# List all available tools
docker-compose exec mcp-server php bin/console mcp:list-tools

# JSON output for scripts
docker-compose exec mcp-server php bin/console mcp:list-tools --format=json

MCP 服务器

# Run stdio server (for Claude Desktop)
docker-compose exec mcp-server php bin/console mcp:stdio

# View logs
docker-compose logs -f mcp-server

开发工作流程

API端点更改时

# Step 1: Regenerate OpenAPI in the API Gateway
docker-compose exec api-gateway composer openapi

# Step 2: Regenerate MCP tools
docker-compose exec mcp-server php bin/console mcp:generate-tools --force

# Step 3: Restart Claude Desktop to see new tools

查看生成的工具

docker-compose exec mcp-server cat src/Mcp/Tool/Generated/ApiGatewayTools.php

检查日志

# Symfony application logs
docker-compose exec mcp-server tail -f var/log/dev.log

# Container logs
docker-compose logs -f mcp-server
docker-compose logs -f api-gateway

清除缓存

docker-compose exec mcp-server php bin/console cache:clear

可用工具（模拟API）

包含的模拟API提供：

• get_app_mockapi_listproducts -获取产品列表
• post_app_mockapi_createproduct -创建新产品（名称、价格）
• delete_app_mockapi_deleteproduct -按ID删除产品
• post_app_mockapi_createorder -创建新订单（productId、数量）

身份验证和令牌

默认令牌（原型）

• MCP合作伙伴令牌: partner-secret-token-123 （用于HTTP流式访问）
• API网关令牌: secret-123 （用于后端API调用）

⚠️ 在生产环境中替换这些令牌

令牌流

Claude Desktop (with MCP partner token)
    ↓
MCP Symfony Server (receives token, validates it)
    ↓ (uses API Gateway token)
Apache (passes Authorization header via SetEnvIf)
    ↓
API Gateway Controller (validates API token)
    ↓
Response (JSON)

环境变量

通过docker-compose.yml配置或在运行时传递：

• API_GATEWAY_TOKEN：API身份验证的承载令牌（默认值： secret-123)
• API_GATEWAY_URL：API网关的基本URL（默认值： http://api-gateway)
• MCP_PARTNER_TOKEN：MCP HTTP端点身份验证的令牌（默认值： partner-secret-token-123)

多个环境

在中配置不同的环境 claude_desktop_config.json:

{
  "mcpServers": {
    "api-dev": {
      "command": "docker-compose",
      "args": [
        "exec", "-T",
        "-e", "API_GATEWAY_TOKEN=dev-token-here",
        "mcp-server",
        "php", "bin/console", "mcp:stdio"
      ]
    },
    "api-prod": {
      "command": "docker-compose",
      "args": [
        "exec", "-T",
        "-e", "API_GATEWAY_TOKEN=prod-token-here",
        "-e", "API_GATEWAY_URL=https://api.production.com",
        "mcp-server",
        "php", "bin/console", "mcp:stdio"
      ]
    }
  }
}

建筑

关键组件

• ApiGatewayClient：使用带有Bearer令牌注入的原生PHP cURL的HTTP客户端
• GenerateTools命令：根据OpenAPI规范生成MCP工具
• McpStdioCommand：具有工具自动加载功能的自定义stdio传输
• McpHttp控制器：用于合作伙伴集成的HTTP/Streamable端点
• ApiGatewayTools：具有参数提取功能的自动生成MCP工具
• Apache配置：严重 SetEnvIf 传递授权标头的指令

项目结构

mcp-prototype-root/
├── docker-compose.yml              # Container orchestration
├── mcp-symfony-server/             # MCP server application
│   ├── bin/
│   │   ├── console                 # Symfony console
│   │   └── mcp-entrypoint.sh       # Docker entrypoint
│   ├── config/
│   │   └── packages/mcp.yaml       # MCP configuration
│   ├── src/
│   │   ├── Command/
│   │   │   ├── GenerateToolsCommand.php
│   │   │   ├── McpStdioCommand.php
│   │   │   ├── ListToolsCommand.php
│   │   │   └── ValidateSwaggerCommand.php
│   │   ├── Controller/
│   │   │   └── McpHttpController.php
│   │   ├── Mcp/
│   │   │   ├── Generator/
│   │   │   │   └── SwaggerToolGenerator.php
│   │   │   └── Tool/Generated/
│   │   └── Service/
│   │       └── ApiGatewayClient.php
│   └── Dockerfile
└── mock-api-gateway/               # Mock API for testing
    ├── src/Controller/
    │   └── MockApiController.php
    ├── public/.htaccess
    └── Dockerfile

API网关要求

您的API网关必须提供：

1. OpenAPI/Swagger文档：可在 /api/doc.json
2. 承载令牌身份验证：验证 Authorization: Bearer 头球
3. Apache配置：必须将Authorization标头传递给PHP

必需的Apache配置

在Apache虚拟主机配置中：

    SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
    AllowOverride All
    Require all granted

启用所需模块：

a2enmod setenvif
service apache2 restart

严重： 没有 SetEnvIf默认情况下，Apache会剥离Authorization标头，导致身份验证失败。

故障排除

服务器未连接

1. 检查容器是否正在运行：

   docker-compose ps

1. 查看克劳德桌面日志：菜单→ View → 切换开发者工具

1. 验证中的令牌配置 claude_desktop_config.json

工具未出现

1. 重新生成工具：

   docker-compose exec mcp-server php bin/console mcp:generate-tools --force

1. 完全重新启动克劳德桌面

1. 检查MCP服务器日志：

   docker-compose logs -f mcp-server

身份验证错误（“无效令牌”）

1. 验证令牌是否与API网关配置匹配

1. 检查Apache是否 SetEnvIf Authorization 指令已启用

1. 直接测试API网关：

   curl http://localhost:8080/api/products \
     -H "Authorization: Bearer secret-123"

HTTP 500错误

1. 检查PHP错误日志：

   docker-compose exec mcp-server cat var/log/dev.log

1. 验证OpenAPI规范是有效的JSON：

   curl http://localhost:8080/api/doc.json | jq

1. 清除Symfony缓存：

   docker-compose exec mcp-server php bin/console cache:clear

Windows卷同步问题

Windows上的Docker卷同步可能会延迟。如果未显示更改：

1. 清除MCP服务器中的缓存：

   docker-compose exec mcp-server php bin/console cache:clear

1. 如果需要，重建容器：

   docker-compose down
   docker-compose up -d --build

1. API更改后重新生成OpenAPI和工具

技术栈

• 交响乐7.4.3：PHP框架
• PHP 8.2：编程语言
• Apache 2.4：具有mod_rewrite和mod_setenvif的Web服务器
• Docker编写3.8：容器编排
• Nelmio API 文档包 4.38：OpenAPI/Swagger文档
• MCP-SDK：模型上下文协议实现
• 本地cURL：API请求的HTTP客户端

附加文档

• MCP检查员指南
• 合作伙伴集成
• 技术指南

原型通知

这个项目是 最小生产级原型 仅用于演示和合作伙伴集成目的。

主要限制：

• 无自动化测试（仅原型）
• 基于文件的持久性（不用于生产）
• 硬编码默认令牌（用于生产）
• 无速率限制或高级安全功能

对于生产部署，请参阅《技术指南》，了解建议的改进，包括数据库集成、全面测试和增强的安全措施。

许可证

演示和合作伙伴支持的原型。根据需要适应您的用例。

支持

关于以下问题：

• MCP协议: 模型上下文协议文档
• 交响乐: Symfony文档
• 克劳德桌面版: Claude桌面文档