使用说明

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网关必须提供：

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

必需的Apache配置

在Apache虚拟主机配置中：

<Directory /var/www/html/public>
    SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
    AllowOverride All
    Require all granted
</Directory>

启用所需模块：

a2enmod setenvif
service apache2 restart

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

故障排除

服务器未连接

检查容器是否正在运行：
```
docker-compose ps
```
查看克劳德桌面日志：菜单→ View → 切换开发者工具
验证中的令牌配置 claude_desktop_config.json

工具未出现

重新生成工具：

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

完全重新启动克劳德桌面
检查MCP服务器日志：
```
docker-compose logs -f mcp-server
```

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

验证令牌是否与API网关配置匹配
检查Apache是否 SetEnvIf Authorization 指令已启用

直接测试API网关：

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

HTTP 500错误

检查PHP错误日志：

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

验证OpenAPI规范是有效的JSON：

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

清除Symfony缓存：

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

Windows卷同步问题

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

清除MCP服务器中的缓存：

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

如果需要，重建容器：

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

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协议: 模型上下文协议文档
交响乐: Symfony文档
克劳德桌面版: Claude桌面文档