返回作品集EN

MCP Server 协议调用与复现

查看已保存的协议调用、原始源码和可复现的冒烟检查。

用 Python 标准库实现 stdio 上的 initialize、tools/list 与 tools/call。任务规划返回固定模板。以下记录来自自建标准库客户端的实际调用。

已保存的协议调用

1. 握手与能力声明

协议版本 2024-11-05。game-agent-mcp v0.1.0 声明 tools 能力。

请求

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "portfolio-smoke-client",
      "version": "0.1.0"
    }
  }
}

返回

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "game-agent-mcp",
      "version": "0.1.0"
    }
  }
}
2. 发现两个工具

两个工具均声明 inputSchema,plan_game_task 声明必填的 game 与 task 字符串。

请求

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

返回

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "list_game_agent_scopes",
        "description": "列出本 MCP Server 支持的泛游戏 Agent 场景(游戏资讯/智能问答/桌面陪伴/任务执行),无参数。用于让 Agent 在初始化时了解可用能力边界。",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      },
      {
        "name": "plan_game_task",
        "description": "给定游戏名与任务,返回由 Agent 拆解的可执行子任务步骤(演示 Planning + Tool Use 概念)。",
        "inputSchema": {
          "type": "object",
          "properties": {
            "game": {
              "type": "string",
              "description": "游戏名称,如《原神》"
            },
            "task": {
              "type": "string",
              "description": "玩家希望完成的任务,如「查当前版本最强角色」"
            }
          },
          "required": [
            "game",
            "task"
          ]
        }
      }
    ]
  }
}
3. 调用任务规划

工具返回五步固定计划,覆盖澄清、上下文、拆解、工具调用和结果校验。

请求

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "plan_game_task",
    "arguments": {
      "game": "Demo Game",
      "task": "Check a task plan"
    }
  }
}

返回

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "为《Demo Game》的「Check a task plan」生成的 Agent 执行计划:\n1. 意图澄清:明确在《Demo Game》中「Check a task plan」的目标与完成判定\n2. 上下文检索:拉取游戏知识库 / 存档,确认前置条件与约束\n3. 子任务拆解:将目标拆成可顺序执行的原子步骤\n4. Tool Use:调用外部工具(查价 / 地图 / 组队 API)执行原子步骤\n5. 校验与回滚:每步结果校验,失败触发降级或人工确认"
      }
    ],
    "isError": false
  }
}
4. 调用场景清单

工具返回游戏资讯、问答、陪伴与任务执行四类场景。

请求

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_game_agent_scopes",
    "arguments": {}
  }
}

返回

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "支持的泛游戏 Agent 场景:\n- game_news(游戏资讯):聚合与推送新游评测、版本更新、活动资讯\n- qa(智能问答):基于游戏知识库的攻略与机制问答\n- companion(桌面陪伴):常驻桌面的轻互动陪伴角色\n- task_exec(任务执行):代玩家执行查价、组队、日常等可执行任务"
      }
    ],
    "isError": false
  }
}
5. 未知工具错误

未知工具 missing_tool 返回 isError = true。

请求

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "missing_tool",
    "arguments": {}
  }
}

返回

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "工具执行出错:'missing_tool'"
      }
    ],
    "isError": true
  }
}

复现检查

将以下文件分别保存到同一目录下的 src/ 与 tests/,再运行命令。

mcp_server.py · test_mcp_server.py

python3 tests/test_mcp_server.py

冒烟检查覆盖握手、工具发现和两个工具的成功调用。错误回包另行实跑记录。inputSchema 用于声明契约,当前实现还需补充严格参数校验、协议边界测试及具体客户端接入验证。

接入与排查

使用 python3 src/mcp_server.py 启动。stdio 客户端配置 Python 可执行文件与服务脚本的绝对路径。stdout 保留协议消息,诊断日志使用 stderr。先核对握手和工具列表,再检查具体调用。