feat: add raw_response_enabled field to MCPServer

[Han-Ya-Jun]

描述

为 MCPServer 添加 raw_response_enabled 字段，支持直接返回 API 原始响应，不添加 request_id 等额外信息。

改动内容

Django (Dashboard)

• MCPServer 模型添加 raw_response_enabled 字段（默认 false）
• 添加数据库迁移文件
• 同步 API 和 Web API 的 serializers 支持 raw_response_enabled 参数
• API 文档更新

Go (mcp-proxy)

• MCPServer model 添加 RawResponseEnabled 字段
• MCPServerConfig 添加 RawResponseEnabled 配置
• MCPServer proxy 添加 rawResponseEnabled 状态及 getter/setter
• genToolHandler 支持 raw_response 模式：直接返回 API 响应，不包装 envelope
• AddMCPServerFromOpenAPISpec 和 UpdateMCPServerFromOpenApiSpec 传递 rawResponseEnabled
• 支持 raw_response_enabled 字段的热更新

关联

• Master 分支 PR: feat: add raw_response field to MCPServer #2643

[wklken]

PR #2645 Code Review 汇总报告

由 codex-internal (gpt-5.3-codex) + claude-internal 双模型 review，主 agent 汇总整理。

变更概述

本 PR 为 MCP Server 增加 raw_response_enabled 原始响应模式，允许用户选择是否在 mcp-proxy 响应中附加额外元数据（如 request_id、code 等 envelope 字段）。

变更范围：

• Dashboard 侧（4 个文件）：新增 raw_response_enabled 字段到创建/更新/同步序列化器、数据库模型及迁移文件，补充 v2 sync API 文档
• mcp-proxy 侧（6 个文件）：在配置结构体、数据库实体、MCPServer 运行时对象中新增字段，工具调用响应增加"原始响应"分支
• 其它：修复 BK_APIGW_RELEASE_VERSION 的 split 写法（maxsplit=1）

改动规模：12 个文件，183 增 / 28 删，总 diff 621 行。

---

问题列表

🔴 Blocking

[codex] raw_response_enabled 配置变更后不会实际生效（handler 捕获旧值）

• 位置：src/mcp-proxy/pkg/infra/proxy/proxy.go（genToolHandler(toolApiConfig, serverName, rawResponse)）；src/mcp-proxy/pkg/mcp/mcp.go（LoadMCPServer 中 SetRawResponseEnabled）
• 问题：genToolHandler 在注册时将 rawResponse 布尔值作为闭包捕获，运行中调用 SetRawResponseEnabled 改变标志位后，已注册的 tool handler 依旧按旧模式执行，导致"配置可写但行为不变"。
• 影响：此 PR 核心能力——运行中切换 raw 模式——在实际场景下完全失效。
• 建议：
  • 方案 A：handler 执行时动态读取 mcpServer.IsRawResponseEnabled()（传指针/引用而非 bool 快照）
  • 方案 B：检测到 raw_response_enabled 变化时，强制重建该 server 的所有 tool handler

---

🟠 Major

1. [codex] 资源版本变更时，raw_response_enabled 新值可能被旧值覆盖/忽略

• 位置：src/mcp-proxy/pkg/mcp/mcp.go（仅在"资源版本未变化"分支同步 raw flag）；src/mcp-proxy/pkg/infra/proxy/proxy.go（UpdateMCPServerFromOpenApiSpec 读取旧运行时值生成 handler）
• 问题：当 release 资源版本变化时，不执行 SetRawResponseEnabled(server.RawResponseEnabled)，但 UpdateMCPServerFromOpenApiSpec 又用旧值生成新 handler，导致 openapi reload 后 raw 配置仍保持旧行为。
• 建议：在更新路径中优先同步 SetRawResponseEnabled，或向 UpdateMCPServerFromOpenApiSpec 显式传入 DB 最新值，避免读取运行时旧状态。

2. [codex + claude] 测试覆盖严重不足

• 位置：src/mcp-proxy/pkg/mcp/mcp_test.go
• 问题（双方一致）：所有测试用例均使用 rawResponseEnabled: false，既无 true 场景测试，也无配置切换（false↔true）后行为验证，以及资源版本变更 + raw 配置同时变更的组合场景。
• 建议：至少补充：① raw_response_enabled=true 时响应中不包含 request_id/code 等 envelope 字段；② 配置切换后下一次请求行为立即生效。

3. [claude] 缺少配置变更的客户端会话兼容处理

• 位置：src/mcp-proxy/pkg/mcp/mcp.go:155-160
• 问题：raw_response_enabled 切换时，对已连接的客户端会话缺少通知或清理逻辑，可能导致长连接客户端行为异常。
• 建议：添加配置变更时的客户端通知机制或会话清理逻辑。

---

🟡 Minor

1. [claude] 代码注释重复

• 位置：src/mcp-proxy/pkg/mcp/mcp.go:161
• 存在重复注释"判断资源版本是否变化"，删除多余一处即可。

2. [claude] 函数参数/变量命名不一致

• 位置：src/mcp-proxy/pkg/infra/proxy/proxy.go:342
• genToolHandler 参数从 toolApiConfig 改为 toolConfig，但函数内部仍使用旧变量名，统一即可。

3. [claude] API 文档更新不完整

• 位置：src/dashboard/apigateway/apigateway/data/apidocs/zh/v2_sync_stage_mcp_servers.md
• 只更新了同步 API 文档，其他相关 API（如创建/更新 MCP Server 的 web API 文档）建议一并补充。

---

💬 Nit

1. [claude] 字段注释格式对齐

• 位置：src/mcp-proxy/pkg/entity/model/mcp.go:52
• ProtocolType 和 RawResponseEnabled 字段注释格式不对齐，统一排版。

2. [claude] 帮助文本描述一致性

• 统一各序列化器中 raw_response_enabled 字段的 help_text 描述措辞。

---

优点

• [共同认可] 字段接入链路完整：序列化器、模型、迁移、proxy 配置/实体/运行时均有对应修改，未出现遗漏层级。
• [共同认可] 非 JSON 响应在 tool reader 中有兜底处理（读取为字符串），raw 模式下不会因直接解析失败而崩溃。
• [共同认可] 代码分层清晰，新功能与现有架构集成良好，遵循项目分层设计原则。
• [codex] version.split("+", maxsplit=1) 的 fix 稳妥，避免不必要的多段分割。
• [claude] 同时支持 SSE 和 Streamable HTTP 两种协议类型的 raw 响应模式，覆盖全面。

---

综合建议

本 PR 在"字段接入"层面完整，但在"运行时语义一致性"上存在 Blocking 级缺陷：配置变更后 handler 仍捕获旧值，核心动态切换能力无法生效。建议：

1. 必须修复（合并前）：Blocking 问题——handler 动态读取 raw_response_enabled，不在注册时固化。
2. 强烈建议修复（合并前）：两个 Major 问题——资源版本变更路径同步 raw flag；补充最小测试用例覆盖 true 场景和切换场景。
3. 可后续跟进：Minor/Nit 级问题——注释重复、变量命名、文档补全等。

---

由 codex-internal (gpt-5.3-codex) + claude-internal 双模型 review，主 agent 汇总 | [from openclaw-internal]