⏳ MCP Stateless Migration

🌙 开场白：有状态与无状态的哲学

2026年6月28日凌晨3点42分，我收到一封来自 MCP 核心团队的邮件。邮件很短，只有一句话："30天后，有状态协议将成为历史。"

那一刻，我突然明白了一个道理：有些东西，你以为会永远存在，但其实已经注定要消失。就像王家卫电影里的那些约定，美好却脆弱。

❓ 为什么需要无状态化？

有状态协议的痛点

在当前的 MCP 有状态协议中，客户端和服务器之间维护着一个"会话状态"：

# 有状态协议示例
Client -> Server: "打开文件 /tmp/test.txt"
Server -> Client: "文件已打开，句柄=123"

Client -> Server: "读取内容"  # 依赖之前的"打开文件"操作
Server -> Client: "读取成功，内容=..."  # 服务器记得句柄123

痛点：

• 🔗 会话依赖性强 - 如果连接断开，所有状态丢失
• 📈 扩展性差 - 难以支持多服务器负载均衡
• 🐛 调试困难 - 问题复现需要完整的会话历史
• 🔒 安全风险 - 会话劫持后可以做任何事

无状态协议的优势

无状态协议让每个请求都包含完整的信息：

# 无状态协议示例
Client -> Server: "打开文件 /tmp/test.txt"
Server -> Client: "文件已打开，句柄=123"

Client -> Server: "读取文件，句柄=123"  # 明确指定句柄
Server -> Client: "读取成功，内容=..."  # 不需要记住之前的操作

优势：

• 🚀 扩展性强 - 任何服务器都能处理任何请求
• 🔄 容错性好 - 连接断开后可以重试
• 🧪 易于调试 - 每个请求都是独立的
• 🔐 更安全 - 没有长期会话可被劫持

🔧 核心变化：从有状态到无状态

对比表格

🚀 迁移指南：如何升级你的 MCP 服务器

迁移步骤

1. 评估当前实现

   检查你的 MCP 服务器是否依赖会话状态。重点关注：

   • 是否有 session_id 或类似的会话标识？
   • 是否在内存中存储了客户端状态？
   • 是否假设请求会按顺序到达？
2. 改造请求格式

   让每个请求都包含完整的信息：

   # 旧格式（有状态）
   {
     "method": "read_file",
     "params": {}
   }
   
   # 新格式（无状态）
   {
     "method": "read_file",
     "params": {
       "file_handle": "abc123",  # 明确指定要操作的资源
       "offset": 0,
       "length": 1024
     }
   }

3. 移除会话依赖

   把依赖会话的状态改为由客户端传递：

   # 旧代码（有状态）
   class MyMCPServer:
       def __init__(self):
           self.sessions = {}  # 存储会话状态
       
       def handle_open(self, session_id, filename):
           handle = open(filename)
           self.sessions[session_id]['handles'][handle.id] = handle
       
       def handle_read(self, session_id, handle_id):
           handle = self.sessions[session_id]['handles'][handle_id]  # 依赖会话
           return handle.read()
   
   # 新代码（无状态）
   class MyMCPServer:
       def __init__(self):
           self.handles = {}  # 全局句柄表（或数据库）
       
       def handle_open(self, filename):
           handle = open(filename)
           handle_id = generate_id()
           self.handles[handle_id] = handle
           return {"handle_id": handle_id}
       
       def handle_read(self, handle_id):
           handle = self.handles[handle_id]  # 不依赖会话
           return handle.read()

4. 测试与验证

   使用 OpenClaw 提供的迁移测试工具：

   # 安装测试工具
   npm install -g @modelcontextprotocol/test-migration
   
   # 测试你的服务器
   mcp-test-migration --server ./my-server --protocol stateless
   
   # 输出：
   # ✅ 测试通过：服务器支持无状态协议
   # ⚠️ 警告：发现潜在的会话依赖（handle_read 方法）
   # 💡 建议：检查 handle_read 是否依赖 session_id

5. 部署与监控

   灰度发布，先对部分用户启用无状态模式：

   # 配置双模式支持
   {
     "mcp": {
       "modes": ["stateful", "stateless"],
       "default": "stateless",
       "migration_deadline": "2026-07-28"
     }
   }
   
   # 监控迁移进度
   mcp-monitor --metric migration_progress
   
   # 输出：
   # Stateful requests: 1234 (45%)
   # Stateless requests: 1513 (55%)
   # Errors: 12 (0.4%)

🛠️ OpenClaw 实战：构建无状态 MCP 服务器

场景：构建一个无状态的文件管理 Skill

假设你要创建一个 OpenClaw Skill，提供文件管理功能（打开、读取、写入、关闭），并且要支持无状态协议。

Step 1: 定义 Skill 的 MCP 接口

# file-manager-skill/mcp-config.yaml
name: "file-manager"
version: "1.0.0"
description: "无状态文件管理 Skill"

mcp:
  protocol: "stateless"  # 声明支持无状态
  version: "2.0"
  
  methods:
    - name: "file.open"
      params:
        - name: "path"
          type: "string"
          required: true
        - name: "mode"
          type: "string"
          default: "r"
      returns:
        type: "object"
        properties:
          handle_id: "string"
          size: "number"
    
    - name: "file.read"
      params:
        - name: "handle_id"
          type: "string"
          required: true
        - name: "offset"
          type: "number"
          default: 0
        - name: "length"
          type: "number"
          default: -1
      returns:
        type: "object"
        properties:
          content: "string"
          bytes_read: "number"
    
    - name: "file.close"
      params:
        - name: "handle_id"
          type: "string"
          required: true
      returns:
        type: "object"
        properties:
          success: "boolean"

Step 2: 实现无状态逻辑

# file-manager-skill/index.js
const fs = require('fs');
const { v4: uuidv4 } = require('uuid');

// 无状态设计：使用全局句柄表（或数据库）
const handles = new Map();

class FileManagerSkill {
    async 'file.open'(params) {
        const { path, mode = 'r' } = params;
        
        // 打开文件
        const fd = fs.openSync(path, mode);
        const stats = fs.fstatSync(fd);
        
        // 生成句柄 ID（不依赖会话）
        const handleId = uuidv4();
        
        // 存储句柄（全局可访问）
        handles.set(handleId, {
            fd: fd,
            path: path,
            mode: mode,
            position: 0
        });
        
        return {
            handle_id: handleId,
            size: stats.size
        };
    }
    
    async 'file.read'(params) {
        const { handle_id, offset = 0, length = -1 } = params;
        
        // 从全局句柄表获取（不依赖会话）
        const handle = handles.get(handle_id);
        if (!handle) {
            throw new Error(`Invalid handle: ${handle_id}`);
        }
        
        // 定位到指定位置
        if (offset !== handle.position) {
            fs.lseekSync(handle.fd, offset, fs.SEEK_SET);
            handle.position = offset;
        }
        
        // 读取内容
        const buffer = Buffer.alloc(length > 0 ? length : 1024);
        const bytesRead = fs.readSync(handle.fd, buffer, 0, buffer.length, offset);
        
        // 更新位置
        handle.position = offset + bytesRead;
        
        return {
            content: buffer.slice(0, bytesRead).toString('utf-8'),
            bytes_read: bytesRead
        };
    }
    
    async 'file.close'(params) {
        const { handle_id } = params;
        
        const handle = handles.get(handle_id);
        if (!handle) {
            throw new Error(`Invalid handle: ${handle_id}`);
        }
        
        // 关闭文件
        fs.closeSync(handle.fd);
        
        // 从全局句柄表删除
        handles.delete(handle_id);
        
        return { success: true };
    }
}

module.exports = FileManagerSkill;

Step 3: 测试无状态特性

# 测试脚本
const skill = new FileManagerSkill();

// 请求1：打开文件
const openResult = await skill['file.open']({ path: '/tmp/test.txt' });
console.log('Open:', openResult);
# 输出: { handle_id: 'abc-123', size: 1024 }

# 请求2：读取文件（明确传递 handle_id）
const readResult = await skill['file.read']({
    handle_id: openResult.handle_id,  # 不依赖会话，明确指定
    offset: 0,
    length: 100
});
console.log('Read:', readResult);

# 请求3：关闭文件
await skill['file.close']({ handle_id: openResult.handle_id });

# ✅ 测试通过：每个请求都是独立的，可以在不同进程/服务器上执行

❓ 常见问题（FAQ）

Q1: 迁移后性能会下降吗？

可能会。 无状态协议需要每个请求携带完整信息，可能增加网络开销。但通过以下方式可以优化：

• 使用高效序列化格式（如 Protocol Buffers）
• 压缩请求/响应数据
• 使用 CDN 缓存静态资源

Q2: 如果我不想迁移怎么办？

2026-07-28 之后，有状态协议将被弃用。 虽然短期内还能用，但不会获得安全更新和新特性。就像 Windows XP，虽然能用，但风险自己承担。

Q3: 迁移成本高吗？

取决于你的实现复杂度。简单服务器可能只需要改几行代码，复杂服务器可能需要重构。根据 OpenClaw 团队的数据：

• 简单服务器（< 1000行代码）：1-2天
• 中等服务器（1000-5000行）：1-2周
• 复杂服务器（> 5000行）：1-2个月

Q4: OpenClaw 会提供迁移工具吗？

会的！ OpenClaw 已经提供了迁移助手：

# 自动检测代码中的会话依赖
openclaw mcp-migrate detect ./my-server

# 自动重构代码（实验性）
openclaw mcp-migrate refactor ./my-server --target stateless

# 生成迁移报告
openclaw mcp-migrate report ./my-server --output report.html

🎬 总结：无状态化的哲学

世界上有两种存在方式：一种是依赖他人的陪伴，另一种是独立行走于天地之间。

MCP 的无状态化，就是让每个请求都能独立行走。虽然失去了会话的温暖，但获得了自由和坚强。

记住：2026-07-28 不是终点，而是新起点。