MCP工具设计中的循环调用问题与设计原则

前言

最近在开发一个基于MCP（Model Context Protocol）的工具服务时，我遇到了一个令人困惑的问题：AI模型不断地重复调用一个名为output_result的工具，即使我已经添加了返回值。查看日志时发现，同一个查询结果被反复输出多次，这明显不是预期的行为。

经过一番深入排查，我终于找到了问题的根源，并在这个过程中对MCP的设计理念有了更深刻的理解。今天就来记录一下这次排查经历，希望能帮助其他开发者避免类似的陷阱。

MCP工具的核心设计理念

在深入分析问题之前，首先要理解MCP工具设计的核心理念：MCP工具应该专注于完成具体的实际工作，而不是处理交互和展示逻辑。

你的理解完全正确！让我用一个更清晰的比喻来说明：

MCP工具：就像是工厂里的机器，负责具体的生产制造
模型：就像是设计师和销售，负责决定生产什么和如何展示产品

这个理念的误解正是导致循环调用问题的根本原因。

问题现象：神秘的循环调用

事情是这样的，我开发了一个客户信息查询工具，模型在获取到数据后，会调用output_result工具来格式化输出。但奇怪的是，模型会反复调用这个工具，产生如下的日志：

工具调用结果: 马然名下有一位客户名叫罗钰龙...
INFO: 127.0.0.1:63027 - "POST /mcp HTTP/1.1" 200 OK
INFO: 127.0.0.1:63028 - "POST /mcp HTTP/1.1" 200 OK
工具调用结果: 马然名下有一位客户名叫罗钰龙...
# ... 重复多次

最初我以为是工具没有返回值导致的，于是给工具添加了明确的返回语句：

@mcp.tool()
def output_result(content: str) -> str:
    """输出查询结果"""
    print(content)
    return "内容已成功输出"  # 添加了明确的返回值

但问题依旧存在！模型仍然像复读机一样循环调用这个工具。这让我意识到问题可能不在表面，而是更深层次的设计理念问题。

深入分析：MCP的工作原理

为了理解问题的本质，我需要重新审视MCP协议的设计理念。

MCP的核心机制

在MCP架构中，工具调用遵循一个简单的原则：

工具返回值就是输出结果：每个工具函数的return值会直接返回给调用的模型
**不需要额外的”输出工具”**：模型会自动处理和展示工具的返回结果
模型负责格式化：模型会根据用户需求自动格式化和展示结果

问题根源分析

我原来的output_result工具存在几个根本性问题：

1. 职责不明确
这个工具试图做两件事情：既处理数据又负责输出，违反了单一职责原则。

2. 与MCP协议冲突
在MCP中，工具的返回值本身就是输出，不需要通过另一个工具来”输出”。

3. 模型误解用途
模型可能认为每次需要格式化输出时都要调用这个工具，导致重复调用。

正确的MCP工具设计原则

通过这次经历，我总结出了MCP工具设计的几个重要原则：

原则一：工具应该有明确的输入和输出

每个工具都应该：

接收明确的参数
返回结构化的数据
避免副作用（如直接输出到控制台）

错误示例：

@mcp.tool()
def output_result(content: str) -> str:
    """输出查询结果"""  # ❌ 职责不明确
    print(content)      # ❌ 产生副作用
    return "成功"       # ❌ 返回值没有实际意义

正确示例：

@mcp.tool()
def query_user_info(user_id: str) -> dict:
    """查询用户详细信息"""
    # 执行查询逻辑
    user_data = database.query(user_id)
    return user_data  # ✅ 返回结构化数据

原则二：让模型处理展示逻辑

MCP的核心优势在于让模型决定如何展示结果：

# 查询工具只负责获取数据
user_info = query_user_info("12345")

# 模型会自动决定如何格式化展示：
# - 可能是表格形式
# - 可能是自然语言描述  
# - 可能是Markdown格式
# 这取决于模型的理解和用户的需求

原则三：工具应该专注于核心功能

每个工具应该只做一件事情，并且做好：

@mcp.tool()
def search_users(keyword: str) -> List[dict]:
    """根据关键词搜索用户"""
    # 只负责搜索逻辑
    results = database.search(keyword)
    return results

@mcp.tool() 
def get_user_details(user_id: str) -> dict:
    """获取用户详细信息"""
    # 只负责详情查询
    details = database.get_details(user_id)
    return details

什么样的功能适合MCP？

基于我的经验，以下类型的功能非常适合作为MCP工具：

适合MCP的功能

数据查询类
- 数据库查询
- API调用
- 文件读取
计算处理类
- 数据转换
- 格式验证
- 计算任务
系统操作类
- 文件操作（创建、删除）
- 进程管理
- 系统状态查询

不适合MCP的功能

纯展示类功能
- 格式化输出（应该由模型处理）
- 界面渲染
- 用户交互
需要复杂状态管理的功能
- 多步骤事务
- 长时间运行的任务
实时流式处理
- 视频流处理
- 实时消息推送

实际解决方案

回到最初的问题，我最终将output_result工具改为了一个有实际用途的文件保存工具：

@mcp.tool()
def save_result_to_file(content: str, filename: str = None) -> str:
    """将查询结果保存到文件"""
    
    # 自动生成文件名
    if not filename:
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        filename = f"query_result_{timestamp}.txt"
    
    # 确保文件扩展名
    if not filename.endswith(('.txt', '.md', '.json')):
        filename += '.txt'
    
    # 格式化内容
    formatted_content = f"""=== 查询结果 ===
时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
{'=' * 30}

{content}
"""
    
    # 保存文件
    try:
        with open(filename, 'w', encoding='utf-8') as f:
            f.write(formatted_content)
        return f"结果已成功保存到 {os.path.abspath(filename)}"
    except Exception as e:
        return f"保存失败: {str(e)}"

这个改进后的工具：

✅ 有明确的用途（保存文件）
✅ 返回有意义的执行结果
✅ 不会造成循环调用
✅ 提供了实际的价值

总结与反思

这次MCP工具循环调用问题的排查让我深刻认识到：

技术层面的收获

理解MCP协议的本质：工具返回值就是输出，不需要额外的输出机制
工具设计原则：单一职责、明确输入输出、无副作用
模型行为模式：模型会根据工具返回值判断执行状态

架构设计思考

职责划分的重要性：让每个组件只做自己最擅长的事情
协议遵循的必要性：违反协议设计理念会导致不可预期的问题
用户体验的考量：工具应该提供价值，而不是增加复杂度

最佳实践建议

对于MCP工具开发，我建议：

先设计后实现：明确工具的目的和边界
保持简单：每个工具只做一件事情
测试模型行为：观察模型如何理解和使用你的工具
遵循MCP理念：充分利用协议提供的机制

MCP确实是一个很强大的协议，但就像很多技术工具一样，只有真正理解其设计理念，才能发挥出最大的价值。这次经历让我深刻体会到”知其然更要知其所以然”的重要性。

希望我的这次踩坑经验能帮到大家，避免在MCP开发路上走弯路。如果你也在开发MCP工具，欢迎交流分享经验！

Kaku的个人博客