Model Context Protocol Python SDK开发实战：从入门到精通
项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk 什么是Model Context Protocol？
Model Context Protocol（MCP）是一个革命性的协议，它允许应用程序以标准化、安全的方式为大型语言模型（LLM）提供上下文信息。想象一下，MCP就像是为AI系统构建的"API网关"，它将提供上下文的职责与实际的LLM交互分离，使得AI应用能够更加灵活、可靠地访问外部数据和服务。
通过MCP Python SDK，开发者可以轻松构建两种核心组件：
- MCP服务器：暴露资源、提示词和工具给AI系统
- MCP客户端：连接到任何MCP服务器并获取所需信息
快速搭建你的第一个MCP服务器
环境准备与安装
首先确保你的Python环境已就绪，然后通过以下命令安装MCP SDK：
pip install "mcp[cli]"
或者，如果你使用uv来管理Python项目：
uv add "mcp[cli]"
创建基础服务器
让我们从最简单的例子开始，创建一个包含基本功能的MCP服务器：
from mcp.server.fastmcp import FastMCP
# 创建MCP服务器实例
mcp = FastMCP("Demo")
# 添加一个加法工具
@mcp.tool()
def sum(a: int, b: int) -> int:
"""计算两个数的和"""
return a + b
# 添加动态问候资源
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
"""获取个性化的问候信息"""
return f"你好，{name}！"
if __name__ == "__main__":
mcp.run()
这个简单的服务器提供了两个核心功能：
sum工具：执行数学计算get_greeting资源：根据用户名提供个性化问候
进阶功能扩展
当你掌握了基础后，可以为服务器添加更多实用功能：
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("增强版演示")
@mcp.tool()
def calculate_compound_interest(
principal: float,
rate: float,
years: int
) -> float:
"""计算复利"""
return principal * (1 + rate/100) ** years
@mcp.resource("weather://{city}")
def get_weather_info(city: str) -> str:
"""获取城市天气信息"""
# 这里可以集成真实的天气API
return f"{city}的天气：晴朗，温度25°C"
@mcp.prompt()
def create_analysis_report(
data: str,
format_type: str = "markdown"
) -> str:
"""生成数据分析报告"""
return f"基于以下数据的分析报告：\n\n{data}"
MCP核心概念深入解析
资源（Resources）系统
资源是MCP中向AI模型提供数据的主要方式。它们类似于REST API中的GET端点，主要用于提供信息而不产生副作用：
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("资源示例")
@mcp.resource("file://documents/{name}")
def read_document(name: str) -> str:
"""按名称读取文档"""
# 实际应用中这里会从文件系统读取
return f"{name}的文档内容"
工具（Tools）机制
工具让AI模型能够通过你的服务器执行操作。与资源不同，工具可以进行计算并产生副作用：
@mcp.tool()
def analyze_text(text: str, language: str = "中文") -> dict:
"""分析文本内容"""
return {
"length": len(text),
"language": language,
"word_count": len(text.split())
}
上下文（Context）管理
MCP的Context对象是功能强大的组件，它提供了对MCP能力的访问，包括日志记录、进度报告和用户交互：
from mcp.server.fastmcp import Context, FastMCP
@mcp.tool()
async def process_task(
task_name: str,
ctx: Context,
steps: int = 5
) -> str:
"""执行带有进度更新的任务"""
await ctx.info(f"开始执行：{task_name}")
for i in range(steps):
progress = (i + 1) / steps
await ctx.report_progress(
progress=progress,
message=f"步骤 {i + 1}/{steps}"
)
await ctx.debug(f"完成步骤 {i + 1}")
return f"任务'{task_name}'已完成"
实际应用场景与最佳实践
数据库查询服务
创建一个允许AI查询数据库的MCP服务器：
import sqlite3
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("数据库服务")
@mcp.tool()
def query_database(query: str) -> str:
"""执行SQL查询并返回结果"""
conn = sqlite3.connect('example.db')
cursor = conn.cursor()
cursor.execute(query)
result = cursor.fetchall()
cursor.close()
conn.close()
return str(result)
文件系统操作
构建一个文件浏览器MCP服务器：
import os
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("文件管理器")
@mcp.resource("file://{path}")
def read_file(path: str) -> str:
"""读取指定路径的文件"""
if os.path.exists(path):
with open(path, 'r', encoding='utf-8') as f:
return f.read()
return "文件不存在"
网络服务集成
将外部API集成到MCP服务器中：
import requests
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("网络服务")
@mcp.tool()
def fetch_webpage(url: str) -> str:
"""获取网页内容"""
response = requests.get(url)
return response.text
部署与运行策略
开发模式运行
在开发环境中启动服务器：
python server.py
集成到Claude Desktop
将你的MCP服务器添加到Claude Desktop：
claude mcp add --transport http my-server http://localhost:8000/mcp
使用MCP Inspector测试
启动MCP Inspector来测试你的服务器：
npx -y @modelcontextprotocol/inspector
在Inspector界面中，连接到 http://localhost:8000/mcp 即可开始测试。
常见问题与解决方案
服务器无法启动
问题：服务器启动时出现端口被占用错误。
解决方案：
mcp.run(port=8080) # 使用其他端口
工具调用失败
问题：AI模型无法正确调用工具。
解决方案：
- 确保工具参数类型注解清晰
- 提供详细的工具描述文档
- 使用Pydantic模型进行参数验证
性能优化建议
- 使用异步操作：对于IO密集型任务，使用async/await
- 实现缓存机制：减少重复计算
- 合理设置超时：避免长时间阻塞
进阶开发技巧
结构化输出支持
MCP支持丰富的结构化输出类型：
from pydantic import BaseModel
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("结构化输出示例")
class WeatherData(BaseModel):
"""天气信息结构"""
temperature: float
humidity: float
condition: str
@mcp.tool()
def get_detailed_weather(city: str) -> WeatherData:
"""获取详细的天气数据"""
return WeatherData(
temperature=22.5,
humidity=45.0,
condition="晴朗"
)
认证与安全
为需要访问受保护资源的工具添加认证：
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("安全服务")
@mcp.tool()
def get_protected_data(access_token: str) -> dict:
"""获取需要认证的数据"""
# 在这里实现令牌验证逻辑
return {"status": "授权成功", "data": "敏感信息"}
总结与展望
Model Context Protocol Python SDK为开发者提供了一个强大而灵活的工具集，用于构建与AI系统交互的服务。通过本指南，你应该已经掌握了：
- MCP服务器的基本构建方法
- 资源、工具和上下文的深入使用
- 实际应用场景的实现技巧
- 部署和运维的最佳实践
通过不断实践和探索，你将能够构建出更加复杂、功能更加强大的MCP服务，为AI应用提供丰富、可靠的上下文信息。
核心优势总结：
- 标准化接口，简化AI集成
- 丰富的功能支持，满足各种需求
- 完善的开发工具，提升开发效率
- 活跃的社区支持，持续优化改进
开始你的MCP开发之旅，为AI应用构建强大的上下文服务！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
