MCP原型库
目的
这个仓库展示了如何创建和使用 模型上下文协议（MCP） 实现展示了服务器端和客户端两种架构。它提供了以下方面的实际示例：
- 构建暴露工具和功能的MCP服务器
- 创建与大型语言模型（OpenAI/Anthropic）集成的MCP客户端，以访问MCP服务器
- 通过注释示例和教程理解MCP协议
______________________________________________________________________
先决条件
- Python 3.10或更高版本
uv包管理器（安装指南)- 拥有API凭证的Spotify开发者帐户
- Anthropic API密钥（用于Claude）和/或OpenAI API密钥
______________________________________________________________________
仓库结构
该存储库包含三个主要组件：
1. example-client-spotify/ - MCP客户端实现
这是什么：\ 一个交互式的MCP客户端，可与Anthropic Claude（或OpenAI）集成，以与Spotify MCP服务器进行交互。展示内容包括：
- 从MCP服务器自动发现工具
- LangChain代理与对话记忆的集成
- 多轮对话，保持上下文连贯性
- 使用 Pydantic 验证实现类型安全的工具调用
使用方法：
- 设置环境变量\
创建一个 .env 根目录中的文件：
# Spotify API Credentials
SPOTIPY_CLIENT_ID=your_spotify_client_id
SPOTIPY_CLIENT_SECRET=your_spotify_client_secret
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
# LLM API Key
ANTHROPIC_API_KEY=your_anthropic_api_key
# Or use OpenAI:
# OPENAI_API_KEY=your_openai_api_key
# Optional: Your Spotify email for personalization
EMAIL_SPOTIFY=your_email@example.com- 配置Spotify开发者应用
- 访问 https://developer.spotify.com/dashboard - 创建一个应用程序或使用现有的 - 添加 http://127.0.0.1:8888/callback 重定向URI - 复制客户端ID和密钥到 .env
- 安装依赖项
cd mcp-mvp
uv sync- 运行交互式客户端
uv run python example-client-spotify/spotify_langchain_client_v2.py- 与智能体互动
- 关于Spotify的自然语言查询类型 - 代理能在消息之间记住上下文 - 类型 quit， exit，或 q 结束
预期输出：
- 交互式终端聊天界面
- 实时调用Spotify API（搜索、创建播放列表等）
- 结果显示在终端上
- 在您的Spotify账户中反映的变化（创建的播放列表等）
示例交互：
🗣️ YOU: What are Taylor Swift's top tracks?
🤖 AGENT: [Lists Taylor Swift's popular songs with IDs]
🗣️ YOU: Create a playlist called "My Favorites" with those songs
🤖 AGENT: [Creates playlist and adds tracks]
✅ Playlist created in your Spotify account!______________________________________________________________________
2. example-server/spotify_mcp.py - 自定义MCP服务器
这是什么：\ 一个专为Spotify定制构建的MCP服务器，提供了以下工具：
- 搜索曲目、专辑、艺术家、播放列表
- 获取Spotify项目的详细信息
- 提取音频特征（节奏、音调、能量等）
- 获取个性化推荐
这展示了如何从头开始使用（某种工具或方法）构建一个MCP服务器 fastmcp 框架。
使用方法：
- 设置环境变量 （与上面的客户端相同）
- 安装依赖项
cd mcp-mvp
uv sync- 使用MCP Inspector运行 （用于测试）
cd example-server
uv run mcp dev spotify_mcp.py这会在（某个位置）打开一个网页界面 http://localhost:6274 用于交互式测试工具。
- 独立运行 （用于生产）
uv run python example-server/spotify_mcp.py预期输出：
- MCP Inspector 网页界面（开发模式）
- 服务器运行并等待标准输入（在独立模式下）
- 工具调用结果打印到终端
- 通过标准输入输出交换的JSON-RPC消息
可用工具：
search_tracks- 在Spotify上搜索歌曲get_artist_info- 获取艺术家详情、人气、流派、热门曲目get_audio_features- 获取一首曲目的节奏、调性、能量和舞曲性get_recommendations- 根据种子曲目获取相似曲目
______________________________________________________________________
3. mcp-tutorial/ - 带注释的MCP示例
这是什么：\ 一个从官方Model Context Protocol仓库（https://github.com/modelcontextprotocol/python-sdk）克隆并增强的版本，额外包含：
- 详细的日志记录和调试输出
- 详细的文档字符串，解释每个概念
- 带注释的代码示例
- 自定义README文档
使用方法：
- 导航到教程目录
cd mcp-tutorial/python-sdk/examples/snippets/servers- 使用MCP Inspector运行示例
uv run mcp dev .py尝试的示例：
- lifespan_example.py - 资源生命周期管理 - basic_tool.py - 简单的工具创建 - basic_resource.py - 资源模式 - basic_prompt.py - 提示模板 - structured_output.py - 打字输出
- 遵循教程中的README文件
- 见 mcp-tutorial/README.md 用于详细的分步指南 - 每个示例都对关键概念进行了解释 - 记录了常见模式和陷阱
预期输出：
- MCP Inspector 在浏览器中打开（
http://localhost:6274) - 工具/资源/提示的交互式测试界面
- 控制台日志显示服务器生命周期事件
- 详细的调试输出，用于理解MCP概念
学习路径：
- 从……开始
lifespan_example.py了解资源管理 - 通过（某过程/阶段）取得进展
basic_tool.py，basic_resource.py，basic_prompt.py - 查阅带有注释的README文件以获取概念性解释
- 尝试修改以加深理解
______________________________________________________________________
展示的关键概念
MCP建筑事务所
- 服务器通过stdio/HTTP暴露工具、资源和提示
- 客户发现并调用服务器功能
- 协议标准化的JSON-RPC通信
工具发现
- 客户来电
list_tools()发现可用功能 - 不进行硬编码 - 工具在运行时发现
- 基于模式的验证确保类型安全
对话记忆
- LangGraph's
MemorySaver实现上下文持久化 - 代理会记住对话中的先前消息
- 多轮交互参考之前的上下文
类型安全
- Pydantic 模型验证所有输入/输出
- 枚举提供了编译时工具选择的安全性
- 模式定义可防止运行时错误
______________________________________________________________________
故障排除
OAuth 认证问题
- 确保Spotify仪表板中的重定向URI完全匹配
.env - 使用
http://127.0.0.1:8888/callback(不是localhost) - 当浏览器提示时，完成OAuth流程
端口已被占用
- 终止现有进程：
lsof -i :8888然后 `kill
`
- 或者在两者中更改端口
.env以及Spotify仪表板
虚拟环境警告
- 这些是无害的——
uv自动使用正确的虚拟环境（venv） - 要抑制：不要设置
VIRTUAL_ENV环境变量
导入错误
- 确保
uv sync成功完成 - 重启 VS Code/IDE 以刷新语言服务器
- 使用
uv run所有Python命令的前缀
______________________________________________________________________
额外资源
______________________________________________________________________
贡献；助力
这是一个学习/原型仓库。请随意：
- 添加新的MCP服务器实现
- 增强现有示例，以实现更好的错误处理
- 记录额外的模式和用例
- 为错误或不明确的文档创建问题
______________________________________________________________________
许可证
MIT 许可证 - 详情请参阅 LICENSE 文件