Filmladder MCP服务器
一种模型上下文协议（MCP）服务器，通过抓取数据为阿姆斯特丹电影院提供电影列表和推荐 filmladder.nl.
特性
- 列出电影：获取阿姆斯特丹电影院播放的所有电影，可选择按日期筛选
- 获取放映时间：查找特定电影的所有放映时间（使用模糊标题匹配）
- 电影电影：列出在特定影院播放的所有电影
- 建议：根据评级、首选放映时间、电影院和日期获取电影推荐
需求
- Python 3.11或更高版本
- 依赖管理诗
安装
- 克隆存储库：
git clone
cd filmladder-mcp- 使用Poetry安装依赖项：
poetry install- 安装预提交挂钩（可选但推荐）：
poetry run pre-commit install- 复制
.env.example到.env并在需要时调整配置：
cp .env.example .env用法
运行MCP服务器
服务器使用stdio传输，可以直接运行：
poetry run python -m src.server连接到Cursor IDE
要在Cursor中使用此MCP服务器：
- 项目特定配置 （推荐）：
- 该项目包括 .cursor/mcp.json 包含服务器配置的文件 - 打开此项目时，游标应自动检测到它
- 手动配置:
- 打开光标设置（齿轮图标） - 首选 工具和集成 → MCP工具 - 点击 添加自定义MCP 或编辑 mcp.json - 添加以下配置：
{
"mcpServers": {
"filmladder-mcp": {
"command": "poetry",
"args": ["run", "python", "-m", "src.server"],
"cwd": "/path/to/filmladder-mcp"
}
}
}重要：替换 /path/to/filmladder-mcp 带有此项目目录的实际路径。
- 验证连接:
- 保存后，光标应在mcp工具部分显示“filmladder mcp” - 你可以问Cursor：“今天阿姆斯特丹有什么电影上映？”
在游标中使用MCP工具
连接后，您可以使用Cursor聊天中的工具：
- 列出电影“阿姆斯特丹正在上映哪些电影？”
- 获取演出时间“纽伦堡什么时候比赛？”
- 电影院电影“PathéTuschinski正在播放哪些电影？”
- 建议：“今晚给我推荐一部评分7.0以上的电影”
MCP工具
服务器公开了以下工具：
list_movies
列出阿姆斯特丹电影院播放的所有电影。
参数：
date（可选）：YYYY-MM-DD格式的日期过滤器
例子：
{
"date": "2025-01-15"
}get_showtimes
获取特定电影的所有放映时间（标题模糊匹配）。
参数：
movie_title（必填）：电影标题
例子：
{
"movie_title": "Nuremberg"
}list_cinema_movies
列出在特定影院播放的所有电影。
参数：
cinema_name（必填）：电影院名称
例子：
{
"cinema_name": "Pathé Tuschinski"
}recommend_movies
根据各种标准推荐电影。
参数：
min_rating（可选）：最小评级阈值（默认值：0.0）preferred_times（可选）：HH:MM格式的首选放映时间数组preferred_cinemas（可选）：首选影院名称数组date（可选）：YYYY-MM-DD格式的建议目标日期
例子：
{
"min_rating": 7.0,
"preferred_times": ["20:00", "21:00"],
"preferred_cinemas": ["Pathé Tuschinski", "EYE"],
"date": "2025-01-15"
}测试
单元测试
运行测试套件：
poetry run pytest tests/以详细输出运行：
poetry run pytest tests/ -v快速服务器测试
测试服务器是否正确初始化：
poetry run python test_server.py这将验证：
- 可以导入服务器
- 工具已正确注册
- 基本功能正常
MCP检验员测试
测试完整MCP服务器的推荐方法是使用 MCP检查员:
- 安装MCP检查器（如果尚未安装）：
npm install -g @modelcontextprotocol/inspector- 运行检查器：
npx @modelcontextprotocol/inspector- 配置检查器以使用您的服务器：
- 服务器命令： poetry run python -m src.server - 运输：stdio
- 检查员将提供一个交互式界面来测试所有工具。
手动测试
您还可以通过运行服务器并通过stdin发送JSON-RPC消息来手动测试服务器：
poetry run python -m src.server然后以JSON-RPC格式发送初始化和工具调用请求。
发展
代码质量
本项目使用：
- 颈毛 用于梳理和进口分拣
- 黑色 用于代码格式化
- 米皮 用于类型检查
- 预承诺 挂钩以确保代码质量
- pytest 用于测试
运行linting和格式化：
poetry run ruff check src/
poetry run black src/
poetry run mypy src/运行测试：
poetry run pytest tests/项目结构
filmladder-mcp/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── scraper.py # Web scraping logic
│ ├── models.py # Pydantic data models
│ ├── config.py # Pydantic-settings configuration
│ └── recommender.py # Recommendation logic
├── pyproject.toml # Poetry dependencies and project config
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── .cursorrules # Cursor IDE rules
├── README.md # This file
└── .env.example # Example environment variables类型注解
所有代码都必须使用类型注释。该项目遵循Python 3.11+类型提示约定：
- 使用
list[T]而不是List[T] - 使用
str | None而不是Optional[str] - 所有函数、方法和变量都必须类型化
Pydantic模型
所有数据结构都使用Pydantic BaseModel进行验证和序列化。配置用途 pydantic-settings 用于环境变量支持。
错误处理
服务器处理：
- 网络错误（HTTP超时、连接失败）
- 解析错误（HTML结构更改）
- 输入参数无效
错误是作为MCP框架将适当处理的异常而提出的。
许可证
\[在此处添加您的许可证\]
贡献
\[在此处添加贡献指南\]