AI导哈

电影列表与推荐服务器

Filmladder MCP Server 是一个提供阿姆斯特丹电影院电影列表和推荐的服务，通过爬取filmladder.nl网站数据实现。

  • by danielsteman
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 danielsteman/filmladder-mcp

使用说明

Filmladder MCP服务器

一种模型上下文协议（MCP）服务器，通过抓取数据为阿姆斯特丹电影院提供电影列表和推荐 filmladder.nl.

特性

  • 列出电影：获取阿姆斯特丹电影院播放的所有电影，可选择按日期筛选
  • 获取放映时间：查找特定电影的所有放映时间（使用模糊标题匹配）
  • 电影电影：列出在特定影院播放的所有电影
  • 建议：根据评级、首选放映时间、电影院和日期获取电影推荐

需求

  • Python 3.11或更高版本
  • 依赖管理诗

安装

  1. 克隆存储库：

    git clone <repository-url>
cd filmladder-mcp

  2. 使用Poetry安装依赖项：

    poetry install

  3. 安装预提交挂钩（可选但推荐）：

    poetry run pre-commit install

  4. 复制 .env.example 到 .env 并在需要时调整配置：

    cp .env.example .env

用法

运行MCP服务器

服务器使用stdio传输，可以直接运行：

poetry run python -m src.server

连接到Cursor IDE

要在Cursor中使用此MCP服务器：

  1. 项目特定配置 （推荐）：

    • 该项目包括 .cursor/mcp.json 包含服务器配置的文件
    • 打开此项目时，游标应自动检测到它

  2. 手动配置:

    • 打开光标设置（齿轮图标）
    • 首选 工具和集成 → MCP工具
    • 点击 添加自定义MCP 或编辑 mcp.json
    • 添加以下配置：
    {
  "mcpServers": {
    "filmladder-mcp": {
      "command": "poetry",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/path/to/filmladder-mcp"
    }
  }
}

    重要：替换 /path/to/filmladder-mcp 带有此项目目录的实际路径。

  3. 验证连接:

    • 保存后，光标应在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检查员:

  1. 安装MCP检查器（如果尚未安装）：

    npm install -g @modelcontextprotocol/inspector

  2. 运行检查器：

    npx @modelcontextprotocol/inspector

  3. 配置检查器以使用您的服务器：

    • 服务器命令： poetry run python -m src.server
    • 运输：stdio

  4. 检查员将提供一个交互式界面来测试所有工具。

手动测试

您还可以通过运行服务器并通过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框架将适当处理的异常而提出的。

许可证

[在此处添加您的许可证]

贡献

[在此处添加贡献指南]

相关 MCP