REST API升级为MCP：从协议转换到语义契约的架构演进

1. 为什么 REST API 封装成 MCP 不是“换壳”，而是架构级升级

最近在帮某高校实验室做一套跨平台图像处理系统的后端重构时，团队里一位资深后端工程师盯着我写的 MCP 封装层代码看了半天，最后问了一句：“这不就是把 /v1/segment 接口套了个 /mcp/execute？有啥区别？”——这个问题特别典型，也特别危险。它背后藏着一个普遍误解：把 REST API “包装”成 MCP，只是加个路由前缀、改个 JSON 字段名的体力活。实则不然。MCP（Model Context Protocol）不是新协议，而是一套面向大模型协同场景的语义契约体系。它解决的根本问题，是让模型能像人类工程师一样“理解上下文、预判输入、校验输出、主动反馈异常”，而不是被动接收 raw HTTP 请求、返回 raw JSON 响应。

举个最直观的例子：一个典型的 REST 图像分割接口，请求体可能是这样的：

{ "image_url": "https://xxx.jpg", "model_version": "v2.3", "threshold": 0.5 }

响应体则是：

{ "mask_base64": "iVBORw0KGgo...", "processing_time_ms": 1287, "error": null }

而一个工业级 MCP 封装后的同一能力，其请求体必须包含context、tool_use、schema三重结构：

{ "context": { "session_id": "sess_abc123", "user_intent": "extract foreground object for annotation", "previous_steps": ["uploaded image", "selected region of interest"] }, "tool_use": { "name": "image_segmentation", "parameters": { "image_url": "https://xxx.jpg", "model_version": "v2.3", "threshold": 0.5 } }, "schema": { "output_format": "mask_rle", "required_fields": ["mask_rle", "bounding_box"], "timeout_ms": 3000 } }

看到区别了吗？REST 关注“怎么传数据”，MCP 关注“为什么传、在什么背景下传、期望得到什么、失败了该怎么退”。这不是字段增减的问题，而是通信范式的迁移：从“机器对机器的字节搬运”，转向“模型对服务的意图协商”。

这也是为什么很多团队第一次封装 MCP 时踩的第一个坑，就是直接用 Express 或 FastAPI 的中间件做字段映射，结果上线后模型调用频繁超时、返回空结果却无错误码、上下文丢失导致多步任务断裂。因为 MCP 的核心不在“协议格式”，而在“契约语义”——它强制要求服务端具备上下文感知、意图解析、Schema 驱动验证、失败可恢复等能力。这些能力，REST 架构本身不提供，必须由封装层显式构建。

提示：如果你的现有 REST API 还没有明确的 OpenAPI 3.0 Schema 定义，或者你的 Swagger 文档里还写着“参数说明见内部 Wiki”，那请立刻停下封装 MCP 的动作。MCP 的schema字段不是可选装饰，而是运行时校验依据。没有精确到字段级的类型、范围、必填性定义，MCP 封装就是空中楼阁。

我见过三个不同团队在初期都犯过同一个错误：把context.session_id当作普通字符串透传，结果在高并发下 session 状态错乱，模型以为自己在连续对话，实际调用的是三个不同用户的上下文缓存。后来我们统一改用带时间戳+哈希前缀的 session ID 生成策略，并在封装层入口强制校验 session 生命周期，才彻底解决。这个细节，任何 REST 文档都不会告诉你，但它是 MCP 工业级落地的生死线。

2. MCP 封装层的四层责任模型：从协议转换到语义增强

把 REST API 封装成 MCP，绝不是写一个/mcp/execute路由然后转发请求那么简单。真正工业级的封装，必须承担起四层递进式责任。这四层，构成了 MCP 封装层的“责任模型”，每一层都不可跳过，且必须独立实现、可单独测试、可灰度开关。

2.1 第一层：协议桥接层（Protocol Bridging）

这是最基础、也最容易被低估的一层。它的唯一职责，是完成 HTTP 方法、路径、头信息、载荷格式的无损映射。但“无损”二字极为关键——不是简单地req.body→tool_use.parameters，而是要处理所有协议差异点：

• HTTP 方法语义对齐：REST 中GET /api/v1/status是查询，但在 MCP 中，所有操作都走POST /mcp/execute，因此必须将GET类型的 REST 接口，在桥接层自动转为tool_use.parameters中的method: "GET"字段，并确保下游服务能识别该语义。
• Header 到 Context 的注入：REST 常用Authorization: Bearer xxx、X-Request-ID: abc，这些不能丢弃。桥接层需提取并注入到 MCP 的context对象中，例如：

  "context": { "auth_token_hash": "sha256(abc123...)", "request_id": "abc", "client_ip": "192.168.1.100" }

• 错误码标准化：REST 可能返回400 Bad Request、401 Unauthorized、429 Too Many Requests，而 MCP 要求所有错误统一通过error字段返回，且必须包含code（如"INVALID_INPUT"）、message（用户可读）、details（调试用 JSON）。桥接层必须建立完整的 HTTP 状态码 → MCP 错误码映射表，并附带上下文还原逻辑。

这一层的代码量可能只占整个封装层的 15%，但它决定了整个 MCP 服务的“协议合规性”。我们曾在一个项目中因漏处理304 Not Modified的响应，导致模型缓存机制失效，反复拉取相同资源。补上后，API 调用频次下降了 37%。

2.2 第二层：上下文治理层（Context Orchestration）

这是 MCP 区别于 REST 的核心分水岭。REST 是无状态的，而 MCP 的context是有生命周期、有作用域、可被模型主动查询和修改的。封装层必须成为上下文的“管家”，而非“邮差”。

关键能力包括：

• Session 生命周期管理：context.session_id不是字符串标签，而是一个可被持久化的会话实体。封装层需对接 Redis 或本地 LRU Cache，实现：

  • 自动过期（默认 15 分钟，可由context.ttl_ms覆盖）
  • 并发安全读写（使用 Redis 的SET key value EX seconds NX原子操作）
  • 跨请求状态合并（当模型在一步中发起多个tool_use，需保证它们共享同一context快照）

• 意图解析与上下文补全：context.user_intent往往是自然语言短语（如“帮我裁掉图片边缘的黑边”），封装层需内置轻量 NLP 模块（我们用 spaCy + 规则模板），将其结构化为intent_type: "crop"、target_area: "border"、confidence: 0.82，并注入到tool_use.parameters中，供下游服务决策。

• 上下文审计日志：每一次context的读取、更新、过期，都必须记录审计日志，包含session_id、timestamp、operation（read/update/expire）、diff_json。这是后续排查“模型为何突然改变行为”的唯一依据。

注意：上下文治理层必须与业务逻辑完全解耦。我们曾把 session 缓存逻辑写进某个图像处理服务的 DAO 层，结果该服务升级时意外清空了所有 session，导致线上 200+ 个正在进行的标注任务中断。后来我们强制规定：所有上下文操作，只能通过独立的ContextServiceSDK 调用，且该 SDK 必须提供熔断和降级能力（如降级为无状态模式，仅保留session_id透传）。

2.3 第三层：Schema 驱动验证层（Schema-Driven Validation）

MCP 的schema字段，是服务端的“宪法”。它声明了本次调用的契约边界：输出格式、必填字段、超时阈值、重试策略。封装层必须在此层执行运行时强制校验，而非仅做文档描述。

验证流程严格分为三步：

1. 输入 Schema 校验：检查tool_use.parameters是否符合schema.input_schema（若定义）。我们采用 AJV 库，但做了关键增强：支持$ref远程引用（指向公司内部 OpenAPI Registry），并缓存 schema 解析结果（避免每次请求都 HTTP GET）。

2. 输出 Schema 校验：下游 REST 服务返回原始响应后，封装层必须用schema.output_schema对其进行反向校验。若mask_base64字段缺失，或processing_time_ms超过schema.timeout_ms * 1.2，则立即构造 MCP 格式错误响应，不向上游返回原始 REST 错误。

3. 契约一致性审计：每次部署新版本 MCP 封装层前，必须运行schema-compat-checker工具，比对新旧schema的兼容性。规则包括：新增字段必须 optional，删除字段必须 deprecated 两个版本，类型变更必须是协变（如 string → string | null）。违反则 CI 直接失败。

这个层看似繁琐，却是工业级稳定性的基石。某次我们升级 OCR 服务，下游返回的confidence_score从 float 变成了 string，若无此层校验，MCP 封装层会原样透传，导致上游模型解析失败、整个 pipeline 卡死。而有了 Schema 验证，它在 200ms 内就捕获并返回了清晰的SCHEMA_MISMATCH错误，运维同学 3 分钟内就定位到问题。

2.4 第四层：语义增强层（Semantic Enrichment）

这是让 MCP 封装从“能用”走向“好用”的关键。它不改变功能，但极大提升模型调用体验和成功率。典型增强包括：

• 智能重试与降级：当 REST 服务返回503 Service Unavailable，封装层不直接上报，而是根据context.retry_strategy（如{"max_attempts": 3, "backoff_ms": [100, 300, 900]}）自动重试；若仍失败，则触发降级：调用一个轻量版fallback_segmentation服务（返回粗略 mask），并标记is_fallback: true。

• 输出格式动态适配：schema.output_format可能是"mask_rle"、"mask_png_base64"或"mask_geojson"。封装层需内置格式转换器，将下游统一返回的 PNG 字节数组，按需编码为 RLE 字符串或 GeoJSON 多边形坐标。

• 可观测性注入：在最终 MCP 响应的context中，自动注入observability字段：

  "observability": { "upstream_latency_ms": 1287, "downstream_latency_ms": 842, "cache_hit": true, "fallback_used": false, "trace_id": "trc-xyz789" }

  这些字段不参与业务逻辑，但为 SRE 团队提供了黄金监控指标。

这四层不是理论模型，而是我们在线上环境跑了一年多的实战沉淀。每一层都有独立的单元测试覆盖率报告（要求 ≥92%），且可以独立启停。比如在压测时，我们会关闭语义增强层，只保留桥接和验证，以隔离性能瓶颈。

3. 工业级封装的七项硬性约束：从设计到上线的不可妥协项

很多团队在 MCP 封装初期，会把精力集中在“如何让第一个请求跑通”上，而忽略了一些工业级系统必须满足的硬性约束。这些约束不是锦上添花，而是决定服务能否在生产环境存活的底线。以下是我们在多个项目中总结出的七项不可妥协项，每一条都源于真实故障。

3.1 约束一：零信任输入校验（Zero-Trust Input Validation）

MCP 的tool_use.parameters来自模型，而模型可能被对抗样本攻击、提示词注入或训练数据偏差影响，产生恶意或畸形输入。封装层绝不能假设输入是可信的。

必须实施三级校验：

• 语法层：JSON 结构合法、字段名符合白名单（如禁止__proto__、constructor等原型污染关键词）、字符串长度限制（如image_url≤ 2048 字符）。
• 语义层：image_url必须是 HTTPS 协议、域名在白名单内（如*.cdn.example.com）、不包含file://或data:协议；threshold必须是 0.0–1.0 之间的浮点数。
• 业务层：调用频率限制（基于context.user_id+tool_use.name的滑动窗口计数）、单次请求最大资源消耗预估（如image_url指向的图片尺寸 > 10MB 则拒绝）。

我们曾遭遇一次攻击：模型被诱导生成tool_use.parameters，其中image_url指向一个内网地址http://10.0.0.1:8080/internal/config.json。若无语义层校验，封装层会直接转发，造成内网信息泄露。加入域名白名单后，该请求在 12ms 内被拦截，返回FORBIDDEN_URL_SCHEME错误。

3.2 约束二：确定性输出（Deterministic Output）

MCP 服务必须保证：相同输入（含完整 context）、相同环境、相同版本下，输出必须完全一致。这是模型进行推理链路缓存、结果复用的前提。

这意味着：

• 禁止在响应中嵌入当前时间戳（created_at字段）、随机 UUID（除非明确用于 trace）、或任何非确定性计算结果（如Math.random()）。
• 所有下游服务调用必须是幂等的，或封装层自身实现幂等（如对POST /segment加idempotency_key头）。
• 缓存策略必须基于完整请求哈希（包括context和tool_use），而非仅tool_use.parameters。

某次我们上线新版本，因在context.observability中加入了process_start_time_ms，导致模型缓存失效，QPS 暴涨 300%。后来我们约定：所有非业务字段，必须放在observability下，且该对象本身不参与缓存键计算。

3.3 约束三：亚秒级首字节响应（Sub-Second TTFB）

MCP 调用是模型推理链路的一环，延迟敏感。封装层自身的处理时间（TTFB）必须控制在 300ms 内，否则会拖慢整个模型响应。

优化手段包括：

• 异步非阻塞 I/O：所有下游 HTTP 调用必须用fetch（Node.js）或aiohttp（Python），禁用同步http.request。
• 连接池复用：为每个下游 REST 服务配置独立连接池（min=5, max=50），避免每次新建 TCP 连接。
• 本地缓存热点 Schema：AJV 编译后的 validator 实例常驻内存，避免重复编译。

我们用autocannon压测发现，未启用连接池时，TTFB P95 达 840ms；启用后降至 187ms。这个数字，是模型能否流畅对话的生命线。

3.4 约束四：全链路 TraceID 透传（End-to-End TraceID Propagation）

MCP 封装层是模型与后端服务的“中间人”，必须成为可观测性的枢纽，而非黑洞。

要求：

• 入口处，若context.trace_id存在，则继承；若不存在，则生成mcp-trace-{uuid}。
• 向下游 REST 服务转发时，必须注入X-MCP-Trace-ID: {trace_id}和X-MCP-Parent-Span-ID: {span_id}头。
• 所有日志（access log、error log、audit log）必须包含trace_id字段，便于 Kibana 聚合。

没有这个，当模型报错“segmentation failed”，你根本无法快速定位是封装层解析错了，还是下游服务 OOM 了，还是网络超时了。我们曾因此花了 6 小时排查一个本该 5 分钟解决的问题。

3.5 约束五：熔断与降级能力（Circuit Breaker & Fallback）

下游 REST 服务不可能永远健康。封装层必须内置熔断器（如 Opossum），当错误率超过阈值（如 5 分钟内 50% 请求失败），自动打开熔断器，后续请求直接走降级逻辑，而非排队等待。

降级策略必须分级：

• L1 降级：返回缓存结果（需context.cache_policy允许）。
• L2 降级：调用轻量替代服务（如用 OpenCV 替代深度学习模型做简单裁剪）。
• L3 降级：返回结构化错误，包含suggestion字段（如"Try reducing image resolution or using a different model version"）。

某次下游 GPU 集群故障，熔断器在 47 秒后自动开启，L2 降级服务接管，整体可用性维持在 99.2%，用户无感知。若无此机制，服务将直接雪崩。

3.6 约束六：OpenAPI 3.0 双向同步（Bidirectional OpenAPI Sync）

MCP 封装层的接口，必须有机器可读的 OpenAPI 3.0 定义，且该定义必须与底层 REST API 的 OpenAPI 定义双向同步。

• 正向同步：REST API 的 OpenAPI 更新（如新增字段），CI 流程必须自动生成对应的 MCPschema片段，并更新封装层代码。
• 反向同步：MCP 封装层新增的context字段、schema约束，也必须反向生成 OpenAPI 的x-mcp-context、x-mcp-schema扩展，并推送到公司 API Registry。

我们用一个 Python 脚本实现了此同步，它解析 REST 的openapi.yaml，根据预设规则映射为 MCP 的tool_use参数，并注入schema描述。这保证了前端模型 SDK、Postman 测试、Swagger UI 文档全部一致，避免“文档说的和代码做的不一样”。

3.7 约束七：灰度发布与 AB 测试支持（Canary Release & A/B Testing）

MCP 封装层的任何变更（尤其是上下文治理逻辑、Schema 验证规则），都可能影响模型行为。因此，必须支持按context.user_id、context.model_name、tool_use.name等维度进行灰度发布。

实现方式：

• 封装层启动时加载feature_flags.json，定义各功能开关及灰度比例。
• 每次请求，根据context计算feature_flag_key（如mcp_context_enhancement_v2:user_abc），再通过一致性哈希决定是否启用新逻辑。
• 所有 AB 测试组的响应，必须打上ab_test_group: "control"或"treatment"标签，供数据分析。

我们曾用此机制灰度上线新的意图解析模块。先对 1% 的user_intent包含 “crop” 的请求启用，观察错误率、TTFB、模型后续步骤成功率，确认无劣化后，再逐步扩大到 100%。没有这个，一次上线就可能导致模型整个工作流崩溃。

这七项约束，是我们写在 MCP 封装层 README 顶部的“宪法条款”。任何 PR，只要违反其中一条，CI 就会直接拒绝合并。它们不是理想，而是血泪教训换来的生存法则。

4. 从零搭建 MCP 封装层：一个可直接复用的工程骨架

光讲原理和约束不够，你还需要一个能立刻上手、经受过生产考验的工程骨架。下面是一个我们正在某跨平台系统中使用的、最小可行但工业级完备的 MCP 封装层结构。它用 Node.js（Express）实现，但核心思想适用于任何语言栈。

4.1 项目结构：清晰分层，职责分明

mcp-wrapper/ ├── src/ │ ├── core/ # 核心契约与类型定义 │ │ ├── mcp-types.ts # MCPContext, MCPToolUse, MCPSchema 等 TS 接口 │ │ └── errors.ts # MCPError 类，统一错误构造 │ ├── protocol/ # 协议桥接层 │ │ ├── bridge.ts # 主桥接逻辑：REST ↔ MCP 映射 │ │ └── http-client.ts # 带连接池、熔断、TraceID 注入的 HTTP 客户端 │ ├── context/ # 上下文治理层 │ │ ├── session-store.ts # Redis Session 存储实现 │ │ ├── intent-parser.ts # 用户意图轻量解析器 │ │ └── audit-logger.ts # 上下文审计日志 │ ├── schema/ # Schema 验证层 │ │ ├── validator.ts # AJV 驱动的输入/输出校验器 │ │ └── compat-checker.ts # Schema 兼容性检查工具 │ ├── semantic/ # 语义增强层 │ │ ├── fallback-manager.ts # 降级策略管理器 │ │ └── format-converter.ts # 输出格式动态转换器 │ ├── config/ # 配置中心 │ │ └── index.ts # 环境变量、Feature Flag 加载 │ └── app.ts # Express 主应用：路由、中间件、启动 ├── scripts/ │ └── sync-openapi.ts # 双向 OpenAPI 同步脚本 ├── test/ │ ├── unit/ # 各层单元测试（Jest） │ └── integration/ # 端到端集成测试（Supertest） ├── openapi/ # 生成的 MCP OpenAPI 3.0 定义 └── .env.example

这个结构的关键在于：每一层都是一个独立的、可测试、可替换的模块。protocol.bridge不依赖context.session-store，它只接受一个ContextService接口。这样，你可以轻松把 Redis Session 替换为内存 LRU，或把 AJV 校验器替换为 Zod，而无需改动桥接逻辑。

4.2 核心路由实现：/mcp/execute的完整代码

这是整个封装层的心脏。以下代码（已脱敏）展示了如何将四层责任模型落地为可运行的 Express 路由。它不是一个 demo，而是我们线上环境的真实简化版。

// src/app.ts import express from 'express'; import { MCPToolUse, MCPContext, MCPSchema } from './core/mcp-types'; import { Bridge } from './protocol/bridge'; import { ContextService } from './context/session-store'; import { SchemaValidator } from './schema/validator'; import { SemanticEnhancer } from './semantic/fallback-manager'; const app = express(); app.use(express.json({ limit: '10mb' })); // 1. 全局中间件：TraceID 注入与日志 app.use((req, res, next) => { const traceId = req.headers['x-mcp-trace-id'] as string || `mcp-trace-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`; res.setHeader('X-MCP-Trace-ID', traceId); // 记录 access log，含 traceId console.log(`[ACCESS] ${req.method} ${req.url} | trace=${traceId}`); next(); }); // 2. 核心 MCP 路由 app.post('/mcp/execute', async (req, res) => { const startTime = Date.now(); const traceId = res.getHeader('X-MCP-Trace-ID') as string; try { // Step 1: 协议桥接 —— 解析 MCP 请求，映射为内部结构 const { toolUse, context, schema } = Bridge.parseRequest(req.body); // Step 2: 上下文治理 —— 加载/创建 session，解析意图 const contextService = new ContextService(); const session = await contextService.getOrCreate(context.session_id, context.ttl_ms || 900000); // 意图解析，注入到 toolUse.parameters const enhancedParameters = await IntentParser.enhance(toolUse.parameters, context.user_intent); toolUse.parameters = enhancedParameters; // Step 3: Schema 验证 —— 校验输入 await SchemaValidator.validateInput(toolUse.parameters, schema.input_schema); // Step 4: 调用下游 REST 服务（带 TraceID、熔断、连接池） const downstreamResponse = await HttpClient.post( `https://rest-api.example.com${toolUse.path}`, toolUse.parameters, { headers: { 'X-MCP-Trace-ID': traceId, 'X-Request-ID': context.request_id || traceId } } ); // Step 5: Schema 验证 —— 校验输出 await SchemaValidator.validateOutput(downstreamResponse, schema.output_schema); // Step 6: 语义增强 —— 格式转换、降级兜底、可观测性注入 const enhancedResponse = await SemanticEnhancer.enhance({ raw: downstreamResponse, schema, context, traceId, upstreamLatency: Date.now() - startTime }); // Step 7: 构造标准 MCP 响应 const mcpResponse = { context: { ...context, observability: enhancedResponse.observability }, result: enhancedResponse.payload, error: null }; res.status(200).json(mcpResponse); } catch (error) { // 统一错误处理：转换为标准 MCPError const mcpError = MCPError.fromUnknown(error, traceId); res.status(200).json({ context: { trace_id: traceId }, result: null, error: mcpError }); } }); export default app;

这段代码的价值，不在于它有多炫技，而在于它显式暴露了每一层的责任：Bridge.parseRequest、ContextService.getOrCreate、SchemaValidator.validateInput……每一个函数调用，都对应着前文所述的四层模型中的一个环节。你可以清晰地看到控制流如何在各层间传递，以及错误如何被统一捕获和转换。

4.3 关键配置文件：.env与feature_flags.json

工业级封装离不开精细化配置。以下是两个核心配置文件的范例。

.env文件（环境变量）：

# 服务基础 PORT=3000 NODE_ENV=production # 上下文存储 REDIS_HOST=redis.internal REDIS_PORT=6379 REDIS_PASSWORD=secret SESSION_TTL_MS=900000 # 下游服务 UPSTREAM_REST_API=https://rest-api.example.com UPSTREAM_TIMEOUT_MS=5000 # 熔断器 CIRCUIT_BREAKER_FAILURE_THRESHOLD=0.5 CIRCUIT_BREAKER_RESET_TIMEOUT_MS=60000 # OpenAPI 同步 OPENAPI_REGISTRY_URL=https://api-registry.internal/openapi

feature_flags.json文件（特性开关）：

{ "context_enhancement_v2": { "enabled": true, "canary_percentage": 5, "target_keys": ["context.user_intent", "context.previous_steps"] }, "schema_validation_strict": { "enabled": true, "mode": "strict" }, "fallback_enabled": { "enabled": true, "strategies": { "image_segmentation": "lightweight_opencv", "text_ocr": "rule_based_fallback" } } }

这些配置不是写死在代码里的魔法数字，而是可动态调整、可灰度、可审计的系统参数。它们让 MCP 封装层真正具备了工业级的韧性与可控性。

4.4 本地开发与测试：一分钟启动调试环境

为了让团队成员能快速上手，我们提供了一套开箱即用的本地开发脚本：

# 1. 启动本地 Redis（用于 Session） docker run -d --name mcp-redis -p 6379:6379 redis:7-alpine # 2. 启动 Mock REST API（模拟下游服务） npm run mock-rest-api # 启动一个返回固定 JSON 的 Express 服务 # 3. 启动 MCP 封装层 npm run dev # 使用 ts-node-dev，热重载 # 4. 发送测试请求 curl -X POST http://localhost:3000/mcp/execute \ -H "Content-Type: application/json" \ -d '{ "context": {"session_id": "test-123", "user_intent": "crop image"}, "tool_use": {"name": "image_crop", "path": "/v1/crop", "parameters": {"url": "https://example.com/test.jpg"}}, "schema": {"output_format": "jpeg_base64", "timeout_ms": 3000} }'

这个流程，从零到第一个成功 MCP 响应，耗时不到 60 秒。它消除了“环境搭建难”的障碍，让开发者能立刻聚焦于逻辑本身。

5. 真实排障手册：五个高频问题的完整排查链路

再完美的设计，也会在生产环境中遇到意料之外的问题。以下是我们在过去一年中，处理频率最高的五个 MCP 封装层问题。这里不直接给答案，而是呈现完整的、可复现的排查链路——从现象、到假设、到验证、到根因、到修复，让你下次遇到类似问题时，能自己走完这个闭环。

5.1 问题一：模型调用成功率骤降 40%，但封装层 200 率 99.9%

现象：
监控显示，过去 2 小时内，模型对image_segmentation工具的调用成功率从 98% 降至 58%。但封装层的 HTTP 200 率仍是 99.9%，下游 REST 服务的错误率也低于 0.1%。所有日志看起来都“正常”。

排查链路：

1. 第一步：确认问题范围
   查看mcp_wrapper_error_count{code="SCHEMA_MISMATCH"}指标，发现该指标在过去 2 小时激增 2000%。问题不在 HTTP 层，而在 Schema 层。

2. 第二步：抓取失败请求样本
   从日志中提取一个SCHEMA_MISMATCH错误的完整请求和响应。发现错误详情为：
   Field 'mask_rle' is required but missing in output. Expected type: string.
   但下游 REST 服务返回的 JSON 中，确实有mask_rle字段。

3. 第三步：比对 Schema 定义
   检查当前生效的schema.output_schema，发现其定义为：

   { "type": "object", "properties": { "mask_rle": { "type": "string" } }, "required": ["mask_rle"] }

   看起来没问题。

4. 第四步：检查下游响应原始字节
   在HttpClient中临时添加日志，打印downstreamResponse的原始 Buffer。发现返回的 JSON 中，mask_rle字段值是一个空字符串""，而非null或缺失。AJV 默认将空字符串视为有效string。

5. 第五步：深挖 AJV 配置
   查阅 AJV 文档，发现其allowEmptyString选项默认为true。但我们的业务要求mask_rle必须是非空字符串。根因找到了：Schema 定义缺少minLength: 1约束。

修复方案：
更新schema.output_schema，为mask_rle字段添加minLength: 1，并同步到 OpenAPI Registry。同时，在SchemaValidator初始化时，强制设置ajvOptions = { allowEmptyString: false }，作为全局兜底。

教训：Schema 验证不能只看“字段存在”，更要校验“值的有效性”。required只管字段，minLength、pattern、exclusiveMinimum等才是业务语义的守护者。

5.2 问题二：部分用户 session 状态混乱，模型认为在连续对话，实际调用的是其他用户的数据

现象：
A 用户在第 3 步调用image_resize，B 用户在第 1 步调用image_crop，但 A 用户的响应中包含了 B 用户上传的图片 URL。context.session_id字段在日志中显示正确，但session数据错乱。

排查链路：

1. 第一步：检查 Session 存储实现
   查看ContextService.getOrCreate代码，发现其使用redis.set(key, value, 'EX', ttl)，但未使用NX（Not eXists）选项。这意味着，如果两个请求几乎同时到达，都判断key不存在，都会执行set，后执行的会覆盖前执行的。

2. 第二步：复现竞态条件
   用artillery发送 100 个并发请求