星球大战API MCP研讨会
一个实践研讨会项目，演示如何使用FastMCP和星球大战API（SWAPI）构建模型上下文协议（MCP）服务器。
概述
此MCP服务器提供：
- 资源：访问《星球大战》API数据（人、行星、星舰、电影）
- 工具：用于存储和管理喜爱的《星球大战》物品的数据库操作
- 提示词：用于探索和比较《星球大战》数据的助手工作流程
项目结构
nl_mcp_workshop/
├── src/
│ ├── mcp_server.py # Main MCP server implementation
│ ├── swapi_client.py # Star Wars API client
│ └── database.py # Local database operations
├── data/
│ └── local_db.json # JSON database for favorites
├── config/
│ └── mcp_config.json # MCP server configuration
├── tests/
│ ├── conftest.py # Pytest fixtures
│ ├── test_database.py # Database unit tests
│ ├── test_swapi_client.py # SWAPI client unit tests
│ └── test_integration.py # Integration tests
├── requirements.txt # Python dependencies
├── environment.yml # Conda environment file
└── setup.py # Package setup安装说明
先决条件
- Python 3.12或更高版本
- pip或conda包管理器
选项1：使用虚拟环境（venv）
- 创建并激活虚拟环境：
python3 -m venv mcp_workshop
source mcp_workshop/bin/activate # On Windows: mcp_workshop\Scripts\activate- 安装依赖项：
pip install -r requirements.txt- 在开发模式下安装软件包：
pip install -e .选项2：使用Conda/Miniconda
- 从文件创建环境：
conda env create -f environment.yml- 激活环境：
conda activate mcp_workshop- 在开发模式下安装软件包：
pip install -e .运行MCP服务器
方法1：直接执行
cd src
python mcp_server.py方法2：从任何地方（之后 pip install -e .)
python src/mcp_server.py使用Claude Desktop进行配置
要将此MCP服务器与Claude Desktop一起使用，请将以下内容添加到您的Claude Desktop配置文件中：
macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"starwars-workshop": {
"command": "python",
"args": [
"/absolute/path/to/nl_mcp_workshop/src/mcp_server.py"
],
"env": {
"PYTHONPATH": "/absolute/path/to/nl_mcp_workshop"
}
}
}
}注： 替换 /absolute/path/to/nl_mcp_workshop 带有项目目录的实际路径。
特性
资源（只读API访问）
使用URI模式访问《星球大战》数据：
swapi://people/{person_id}-获取角色信息（ID1-83）swapi://planets/{planet_id}-获取行星信息（ID 1-60）swapi://starships/{starship_id}-获取星舰信息swapi://films/{film_id}-获取电影信息（ID 1-6）
工具（数据库操作）
管理您最喜欢的《星球大战》物品：
- add_favorite（项目类型、项目id、备注） -将项目保存到收藏夹
- list_favorites（项目类型） -列出所有收藏夹（可选筛选器）
- remove_favorite（项目类型，项目id） -从收藏夹中删除
- update_favorite_notes（item_type、item_id、notes） -更新笔记
- 搜索偏好（查询） -按关键字搜索收藏夹
提示（助手工作流）
常见任务的预配置工作流：
- explore_character（字符名） -全面的性格探索
- compareitems（item_type、id1、id2） -并排比较
运行测试
运行所有测试：
pytest -v运行特定的测试文件：
pytest tests/test_database.py -v
pytest tests/test_swapi_client.py -v
pytest tests/test_integration.py -v跑步覆盖：
pytest --cov=src --cov-report=html通过打开查看覆盖率报告 htmlcov/index.html 在您的浏览器中。
示例用法
连接到Claude后，您可以：
- 探索一个角色：
Tell me about Luke Skywalker using the Star Wars API- 保存收藏夹：
Add Luke Skywalker (person ID 1) to my favorites with a note about him being the main hero- 列出收藏夹：
Show me all my favorite Star Wars characters- 搜索您的笔记：
Search my favorites for entries about Jedi- 比较项目：
Compare planets Tatooine (ID 1) and Alderaan (ID 2)工作坊学习目标
该项目展示了：
- 使用FastMCP构建MCP服务器
- 实现用于外部API访问的资源
- 为有状态操作创建工具
- 定义复杂工作流的提示
- API错误处理和数据验证
- JSON本地数据持久化
- 综合测试策略（单元+集成）
API 参考
星球大战API（SWAPI）
- 基本URL:https://swapi.dev/api/
- 文档：https://swapi.dev/documentation
- 无需认证
- 价格限制：请尊重
故障排除
导入错误
如果你遇到 ModuleNotFoundError:
# Make sure you're in the project root
pip install -e .数据库问题
如果数据库损坏：
# Reset the database
echo '{"favorites": []}' > data/local_db.jsonAPI超时
如果SWAPI速度慢或不可用：
- 检查您的互联网连接
- API可能正在经历高负载
- 请稍等片刻，然后重试
贡献
这是一个工作坊项目！请随意：
- 添加新的端点（车辆、物种）
- 用更多功能增强数据库
- 为复杂的工作流创建其他提示
- 改进错误处理和日志记录
许可证
该项目作为MCP研讨会的一部分，用于教育目的。