当您使用官方的MCP Python SDK时,构建MCP服务器会变得简单得多。您无需手动编写复杂的JSON模式来定义工具,而是可以使用装饰器来定义它们,让SDK来处理繁重的工作。

在这个示例中,我们正在创建一个管理文档操作的MCP服务器。该服务器将拥有两个主要工具:一个用于读取文档内容,另一个用于更新文档内容。所有文档都以简单字典的形式存在于内存中,其中键是文档ID,值是内容字符串。
MCP Python SDK的优势
MCP项目提供了用于跨多种编程语言构建服务器和客户端的官方SDK。使用Python SDK具有以下几个优势:
- 以最少的样板代码创建MCP服务器
- 自动从Python函数签名生成JSON模式
- 通过装饰器简化工具定义
- 处理类型验证和错误处理

以下展示了使用SDK定义工具是多么简单。@mcp.tool装饰器与类型提示和字段描述相结合,会自动创建出Claude能够理解和使用的正确工具模式。
设置服务器
本课程使用MCP Python SDK的第1版。下面的导入在第2版中会失败,因为该版本重命名了FastMCP。如果您自行搭建项目,请保持SDK版本低于2:
uv add "mcp[cli]<2"使用pip时,相同的版本锁定方式是pip install "mcp[cli]<2"。
基本的服务器设置只需几行代码:
from mcp.server.fastmcp import FastMCP
from pydantic import Field
mcp = FastMCP("DocumentMCP", log_level="ERROR")
docs = {
"deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
"report.pdf": "The report details the state of a 20m condenser tower.",
"financials.docx": "These financials outline the project's budget and expenditures",
"outlook.pdf": "This document presents the projected future performance of the system",
"plan.md": "The plan outlines the steps for the project's implementation.",
"spec.txt": "These specifications define the technical requirements for the equipment"
}实现读取工具
第一个工具允许Claude通过提供文档ID来读取文档内容:
@mcp.tool(
name="read_doc_contents",
description="Read the contents of a document and return it as a string."
)
def read_document(
doc_id: str = Field(description="Id of the document to read")
):
if doc_id not in docs:
raise ValueError(f"Doc with id {doc_id} not found")
return docs[doc_id]该工具定义包括:
- 一个清楚描述该操作的名称
- 一段说明该工具功能的描述
- 带有字段描述的类型化参数
- 针对无效文档ID的错误处理
实现编辑工具
第二个工具对文档内容执行简单的查找和替换操作:
@mcp.tool(
name="edit_document",
description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
doc_id: str = Field(description="Id of the document that will be edited"),
old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
new_str: str = Field(description="The new text to insert in place of the old text.")
):
if doc_id not in docs:
raise ValueError(f"Doc with id {doc_id} not found")
docs[doc_id] = docs[doc_id].replace(old_str, new_str)该工具接受三个参数:文档ID、要查找的文本和替换文本。其实现为了简便,使用了Python内置的字符串replace()方法。
关键实现细节
在使用MCP SDK定义工具时,请牢记以下几个要点:
- 从pydantic导入
Field以添加参数描述 - 使用类型提示来指定参数类型
- 为边界情况加入错误处理
- 编写清晰、具有描述性的工具名称和描述
- MCP Python SDK会自动将您的函数签名转换为正确的JSON模式
与手动编写JSON模式相比,MCP Python SDK极大地降低了创建工具的复杂度。过去需要数十行模式定义才能完成的工作,现在只需几行带装饰器的Python函数即可实现。
@mcp.tool装饰器及其基于签名的模式生成功能来自MCP Python SDK。Claude Agent SDK提供了一个单独的@tool装饰器(在新标签页中打开)用于定义自定义工具,它要求显式传入input_schema参数,而不是在函数签名上使用pydantic的Field注解。在Python中,该模式是一个将参数名称映射到类型的字典,例如{"latitude": float},Agent SDK会为您将其转换为JSON Schema;或者当您需要枚举、范围、可选字段或嵌套对象时,也可以是一个完整的JSON Schema字典。当您在其他地方阅读工具代码时,请检查其导入的是哪个SDK,因为这两个装饰器很容易混淆。