我的模型上下文协议（MCP）服务器的第一个版本虽然能运行，但实际上毫无用处。当我在检查器中手动调用每个工具时，它们都能返回正确的数据；但当我让克劳德（Claude）使用它时，我发现该模型约有三分之一的时间会执行错误的操作。它会去搜索一个它已经拥有确切列名的值，逐行分页浏览数据，或者为一个列名为“学生姓名”的工作表虚构出一个名为“姓名”的列。
这些都不是我代码中的错误。处理程序本身没有问题。问题出在我为这些处理程序编写的所有描述性内容上：工具名称、描述、参数文档以及错误信息字符串。模型只能看到这些信息。它永远看不到你的具体实现，因此它的推理依据并非你的实现代码。
模型上下文协议（MCP）是克劳德（Claude）和光标（Cursor）等人工智能客户端与外部数据进行通信的标准方式。MCP 服务器会公布一个固定的工具列表，客户端只能调用该列表中包含的工具。我开发了 PasteSheet，它将谷歌表格（Google Sheet）发布为只读的 MCP 服务器，因此我的整个交互界面仅包含针对电子表格的三个工具。事实证明，这足以以许多具有启发性的方式出错。
在展示代码之前先说明一点：我的服务器是用 PHP 编写的，而不是 Python。下文所述的经验教训属于协议层面，而非语言层面；我之所以用 Python 展示，是因为官方软件开发工具包（SDK）是大多数人在构建此类服务时的首选。这里展示的所有内容都是我曾实际部署的真实决策的翻译版本。
环境配置
只需安装一次软件开发工具包（SDK），工具界面就是普通的带类型提示的函数。
uv add "mcp[cli]" # 或者：pip install "mcp[cli]"
from typing import Annotated, Literal
from mcp.server import MCPServer
from mcp.types import ToolAnnotations
from pydantic import Field
mcp = MCPServer("Sheet")
if __name__ == "__main__":
mcp.run(transport="streamable-http", port=3001)
你无需编写任何 JSON 模式（JSON Schema）。类型提示本身就是模式，这在意识到模型阅读的是你的文字描述而非你的类型定义之前，感觉还是很不错的。
为模型提供一种低成本了解你数据的方式
我犯的第一个错误是假设模型知道电子表格的结构。事实并非如此，因此模型只能猜测，而猜测的列名意味着返回空结果，随后模型会报告“没有匹配的行”。这是最糟糕的失败
免责声明：本文内容来自互联网，该文观点不代表本站观点。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容，请到页面底部单击反馈，一经查实，本站将立刻删除。
