ModelContextProtocol 内存服务器响应格式问题解析与解决方案

问题背景

在使用ModelContextProtocol(MCP)内存服务器时，开发者可能会遇到一个常见的响应格式验证问题。当通过Python客户端调用create_entities工具时，服务器返回的数据结构不符合客户端的预期格式，导致验证失败。

问题现象

具体表现为客户端期望接收到的响应格式应包含一个顶层的content字段，而实际内存服务器返回的数据直接包含了toolResult数组。这种格式不匹配会导致Pydantic验证错误，错误信息明确指出"content字段缺失"。

技术分析

从技术实现角度来看，这个问题源于服务器端和客户端对协议规范理解的不一致：

1. 协议规范要求：MCP协议规定工具调用响应应当包含content字段作为顶层结构，其中再包含实际的工具执行结果。

2. 实际实现差异：内存服务器直接返回了工具执行结果，没有按照协议要求进行封装。

3. 验证机制：Python客户端使用Pydantic进行严格的响应数据验证，这种格式不匹配会被立即捕获并抛出验证异常。

解决方案

针对这个问题，开发者可以采取以下几种解决方案：

1. 服务器端修复

最根本的解决方案是修正内存服务器的响应格式，使其符合协议规范。服务器应当在返回数据前，将工具执行结果封装在content字段中。

2. 客户端临时解决方案

如果暂时无法修改服务器实现，可以在客户端添加处理逻辑：

async def safe_call_tool(session, command, parameters):
    """安全调用MCP工具并处理验证错误"""
    try:
        result = await session.call_tool(command, parameters)
        return result
    except ValidationError as e:
        # 从验证错误中提取实际的工具结果
        raw_data = e.errors() if hasattr(e, 'errors') else None
        if raw_data and len(raw_data) > 0:
            tool_result = raw_data[0]['input']['toolResult']
            return {"toolResult": tool_result}
        raise

这种方法通过捕获验证异常并提取实际数据，实现了对不规范响应的兼容处理。

3. 协议适配层

在客户端和服务器之间增加一个协议适配层，负责统一响应格式。这种方法可以在不修改两端实现的情况下解决问题。

最佳实践建议

1. 协议一致性检查：在开发MCP相关工具时，应仔细核对协议规范，确保服务器和客户端对数据格式的理解一致。

2. 版本兼容性处理：考虑到不同版本服务器可能存在的实现差异，客户端应具备一定的容错能力。

3. 日志记录：在遇到格式不匹配问题时，应记录完整的请求和响应数据，便于问题排查。

总结

这个响应格式问题虽然看似简单，但反映了分布式系统中接口一致性的重要性。通过理解协议规范、分析实际实现差异，开发者可以选择最适合的解决方案。无论是通过服务器修复、客户端适配还是中间层处理，目标都是确保系统各组件能够顺畅通信。