MCP Prototyping

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 验证实现类型安全的工具调用

使用方法：

1. 设置环境变量\

创建一个 .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

1. 配置Spotify开发者应用

- 访问 https://developer.spotify.com/dashboard - 创建一个应用程序或使用现有的 - 添加 http://127.0.0.1:8888/callback 重定向URI - 复制客户端ID和密钥到 .env

1. 安装依赖项

   cd mcp-mvp
   uv sync

1. 运行交互式客户端

   uv run python example-client-spotify/spotify_langchain_client_v2.py

1. 与智能体互动

- 关于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 框架。

使用方法：

1. 设置环境变量 （与上面的客户端相同）

1. 安装依赖项

   cd mcp-mvp
   uv sync

1. 使用MCP Inspector运行 （用于测试）

   cd example-server
   uv run mcp dev spotify_mcp.py

这会在（某个位置）打开一个网页界面 http://localhost:6274 用于交互式测试工具。

1. 独立运行 （用于生产）

   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文档

使用方法：

1. 导航到教程目录

   cd mcp-tutorial/python-sdk/examples/snippets/servers

1. 使用MCP Inspector运行示例

   uv run mcp dev .py

尝试的示例：

- lifespan_example.py - 资源生命周期管理 - basic_tool.py - 简单的工具创建 - basic_resource.py - 资源模式 - basic_prompt.py - 提示模板 - structured_output.py - 打字输出

1. 遵循教程中的README文件

- 见 mcp-tutorial/README.md 用于详细的分步指南 - 每个示例都对关键概念进行了解释 - 记录了常见模式和陷阱

预期输出：

• MCP Inspector 在浏览器中打开（http://localhost:6274)
• 工具/资源/提示的交互式测试界面
• 控制台日志显示服务器生命周期事件
• 详细的调试输出，用于理解MCP概念

学习路径：

1. 从……开始 lifespan_example.py 了解资源管理
2. 通过（某过程/阶段）取得进展 basic_tool.py， basic_resource.py， basic_prompt.py
3. 查阅带有注释的README文件以获取概念性解释
4. 尝试修改以加深理解

______________________________________________________________________

展示的关键概念

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 官方文档
• Spotify Web API 参考文档
• LangChain 文档
• FastMCP框架

______________________________________________________________________

贡献；助力

这是一个学习/原型仓库。请随意：

• 添加新的MCP服务器实现
• 增强现有示例，以实现更好的错误处理
• 记录额外的模式和用例
• 为错误或不明确的文档创建问题

______________________________________________________________________

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件