MCP服务器创建练习
学习按照Anthropic最佳实践构建模型上下文协议（MCP）服务器的综合练习。
🚀 没有克劳德的桌面版！
使用附带的Python MCP客户端和LangChain集成，所有练习都可以完全离线进行。 Claude for Desktop是可选的-您可以在没有任何外部服务的情况下在气隙环境中测试和使用所有MCP服务器。
概述
此存储库包含一系列渐进式练习，以帮助您掌握MCP服务器开发。每个练习都建立在前一个练习的基础上，引入新的概念和最佳实践。
什么是MCP？
模型上下文协议（MCP）是用于将AI应用程序连接到外部系统的开源标准。将MCP视为AI应用程序的USB-C端口，它提供了一种将AI应用程序连接到数据源、工具和工作流的标准化方式。
先决条件
- Python 3.10或更高版本
- 基本了解Python和异步编程
- 熟悉AI/LLM概念
- 桌面版的Claude是可选的 -请改用附带的Python客户端
快速入门（无需克劳德）
# 1. Clone the repository
git clone https://github.com/MrYtsejam1/McpServersExc.git
cd McpServersExc
# 2. Install dependencies
pip install -r requirements-offline.txt
# 3. Test the calculator server
python3 clients/mcp_client_cli.py --exercise 01 --action list-tools
python3 clients/mcp_client_cli.py --exercise 01 --action call-tool --name add --args '{"a": 15, "b": 27}'对于气隙环境： 看 docs/airgapped.md 了解完整的离线安装和使用说明。
设置
标准安装
# Clone the repository
git clone https://github.com/MrYtsejam1/McpServersExc.git
cd McpServersExc
# Install dependencies
pip install -r requirements-offline.txt可选：安装uv（Python包管理器）
macOS/Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh窗户：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"锻炼结构
此练习分为渐进级别：
级别1：基本工具服务器
通过使用基本工具构建一个简单的计算器服务器来学习基础知识。
- 地点：
exercises/01-basic-tools/ - 概念：工具定义、FastMCP基础、STDIO传输
第二级：具有外部API的高级工具
构建一个与外部API集成的天气服务器。
- 地点：
exercises/02-weather-server/ - 概念：异步操作、API集成、错误处理
第三级：资源
创建一个公开类文件资源的服务器。
- 地点：
exercises/03-resources/ - 概念：资源定义、内容类型、动态资源
第四级：提示
实施预先编写的提示模板。
- 地点：
exercises/04-prompts/ - 概念：提示模板、参数、用例
第5级：完整服务器
构建一个结合所有概念的综合服务器。
- 地点：
exercises/05-complete-server/ - 概念：集成、最佳实践、生产模式
最佳实践
日志记录
- 永不 使用
print()在基于STDIO的服务器中，它会破坏JSON-RPC消息 - 始终使用写入stderr的日志库
- 基于HTTP的服务器可以使用标准输出
工具命名
- 遵循以下格式：
verb_noun（例如。，get_weather,create_document) - 使用带下划线的小写字母
- 描述性和具体性
错误处理
- 始终优雅地处理API故障
- 返回有意义的错误消息
- 使用适当的异步/等待模式
类型安全
- 对所有函数使用Python类型提示
- 利用FastMCP的自动模式生成
- 文档字符串中的文档参数
安全
- 切勿暴露敏感凭据
- 验证所有输入
- 使用环境变量进行配置
测试您的服务器
使用Python MCP客户端（建议用于气隙环境）
附带的Python客户端完全脱机工作，没有任何外部依赖关系：
# List available tools
python3 clients/mcp_client_cli.py --exercise 01 --action list-tools
# Call a tool
python3 clients/mcp_client_cli.py --exercise 01 --action call-tool --name add --args '{"a": 5, "b": 3}'
# List resources
python3 clients/mcp_client_cli.py --exercise 03 --action list-resources
# Read a resource
python3 clients/mcp_client_cli.py --exercise 03 --action read-resource --uri "docs://getting-started"
# Test offline mode (for weather server)
python3 clients/mcp_client_cli.py --exercise 02 --action call-tool --name get_alerts --args '{"state": "CA"}' --offline使用LangChain集成
将MCP服务器与本地LLM集成（例如qwen3-coder-480b）：
# Manual tool invocation (no LLM required)
python3 clients/langchain/examples/agent_no_llm.py
# With local LLM
python3 clients/langchain/examples/agent_local_llm.py \
--model custom \
--api-url http://your-inference-server:8000/v1 \
--model-name qwen3-coder-480b看 客户端/语言链/示例/README.md 了解更多详情。
替代方案：使用MCP检查器（需要npm）
MCP Inspector是一个基于浏览器的开发工具：
npx @modelcontextprotocol/inspector uv --directory /path/to/exercise run server.py替代方案：使用Claude作为桌面（可选）
- 从以下位置安装Claude for Desktophttps://claude.ai/download
- 在中配置服务器
~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或%APPDATA%\Claude\claude_desktop_config.json（Windows）
配置示例：
{
"mcpServers": {
"my-server": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/exercise",
"run",
"server.py"
]
}
}
}- 重新启动桌面版的Claude
- 查找工具图标以验证您的服务器是否已连接
入门指南
从练习1开始：
cd exercises/01-basic-tools
cat README.md按照每个练习的README中的说明继续学习。
资源
故障排除
服务器未出现在Claude for Desktop中
- 验证配置中的绝对路径
- 检查一下
uv在您的PATH（运行which uv或where uv) - 重新启动桌面版的Claude
- 检查克劳德的日志是否有错误
导入错误
- 确保你使用的是Python 3.10+
- 验证虚拟环境是否已激活
- 跑
uv sync安装依赖项
STDIO通信错误
- 移除所有
print()声明 - 使用日志记录到stderr
- 检查代码中的语法错误
贡献
发现问题或想改进练习？欢迎拉取请求！
许可证
麻省理工学院许可证-您可以自由地将其用于学习和教学。