Sammi Liao MCP

国际电影档案搜索MCP服务器

一种模型上下文协议（MCP）服务器，使用Qdrant向量数据库和OpenAI嵌入提供语义电影搜索和推荐功能。该服务器使Claude Desktop等人工智能助手能够按情节主题搜索电影，查找主题相似的电影，并按年份、国家和流派等元数据进行过滤。

特性

• 语义电影搜索：使用向量嵌入按情节主题和故事元素查找电影
• 主题建议：根据情节内容发现与参考电影类似的电影
• 元数据筛选：按发布年份、国家和类型筛选结果
• 查询优化：使用OpenAI API进行自动查询细化，以获得更好的搜索结果
• 详细电影信息：检索完整的电影详细信息，包括演员和角色信息
• 区域搜索：支持按地区（如“东亚”、“西方国家”）搜索电影，并自动进行国家扩展

概述

电影搜索MCP服务器提供了用于发现和探索电影的工具，使用：

• 向量搜索：基于OpenAI嵌入的Qdrant语义搜索(text-embedding-3-small)
• MCP工具：AI助手可以调用的可执行函数
• 类型安全：用于结构化数据验证的Pydantic模式
• 基于Docker：用于一致环境的容器化部署

快速开始

先决条件

主机上需要：

• 码头工人:
• 制造：通常预装在macOS/Linux上。Windows用户：通过安装 巧克力 或使用WSL
• Node.js：MCP检验员测试所需（可选）

- 从以下位置安装 （LTS版本） - 或者使用包管理器： brew install node （macOS）， apt install nodejs npm （Ubuntu）

Docker容器内部：

• 紫外线：Python包管理（自动安装）

步骤1：设置环境变量

创建 .env 项目根目录中的文件：

# Create .env file
cp .env.example .env

编辑 .env 并添加您的API密钥：

# Required for vector embeddings and query optimization
OPENAI_API_KEY=your-openai-api-key-here

# Optional: Custom data directory path
# DATA_DIR=/path/to/your/data

从以下位置获取您的OpenAI API密钥：https://platform.openai.com/api-keys

步骤2：构建和启动服务

# Build the Docker image
make build-only

# Start Qdrant service (required for vector search)
make run-services

步骤3：加载电影数据库

重要：电影搜索功能需要加载完整的CMU电影数据集。

# Load movie data into Qdrant
make load-movie-db

此命令从以下位置加载电影数据集 data/movies/ 输入Qdrant矢量数据库。数据集包括：

• 语义搜索的绘图摘要
• 电影元数据（标题、年份、运行时间、国家、流派）
• 角色和演员信息

数据源：电影数据集来自 CMU电影摘要语料库，包含从维基百科提取的42306个电影情节摘要，以及来自Freebase的对齐元数据。

步骤4：运行MCP服务器

# Run the movie MCP server
make run-movie-server

服务器将启动并准备接受来自MCP客户端的连接。

连接到克劳德桌面

服务器运行后，您可以将其连接到Claude Desktop，以便在对话中直接使用电影搜索工具。

启动MCP服务器

# Start Qdrant and the MCP container in detached mode
make start-mcp-server

这将启动Qdrant和MCP服务器容器。服务器将准备好接受来自Claude Desktop的连接。

配置Claude桌面

1. 找到Claude Desktop配置文件：

   # macOS
   ~/Library/Application Support/Claude/claude_desktop_config.json

   # Windows
   %APPDATA%\Claude\claude_desktop_config.json

1. 添加MCP服务器配置：

   {
     "mcpServers": {
       "movie-search": {
         "command": "docker",
         "args": [
           "exec", "-i",
           "$(docker ps --filter 'name=2025-autumn-mcp' --format '{{.ID}}' | head -n 1)",
           "bash", "-c",
           "cd /project && PYTHONPATH=/project/src uv run python -m mcp_server.movie_server"
         ]
       }
     }
   }

1. 重新启动克劳德桌面 加载新配置。

使用MCP检查员（替代测试）

对于没有Claude Desktop的测试：

# Terminal 1: Start server
make run-interactive
uv run python -m mcp_server.movie_server

# Terminal 2: Run Inspector on HOST (not in container)
npx @modelcontextprotocol/inspector
# Choose: STDIO transport, command: ./run_mcp_server.sh

可用的MCP工具

1. search_movies_unified_tool

具有可选年份和国家筛选功能的统一语义搜索。使用OpenAI API自动优化查询。

参数：

• query （str）：自由文本查询（例如，“反乌托邦社会”）
• top_k （int，默认值：5）：要返回的结果数
• start_year （int，可选）：包含开始年份过滤器
• end_year （int，可选）：包含年终过滤器
• countries （list\[str\]|str，可选）：要筛选的国家名称或地区

例子：

search_movies_unified_tool(
    query="dystopian future with surveillance",
    top_k=5,
    start_year=2000,
    countries=["United States", "United Kingdom"]
)

2. get_movie_info_tool

获取特定电影的详细信息，包括完整演员阵容。

参数：

• movie_title （str）：电影的标题

例子：

get_movie_info_tool(movie_title="The Matrix")

3. thematic_recommendations_by_title_tool

使用存储的向量查找主题与参考电影相似的电影。

参数：

• reference_title （str）：参考电影的标题
• top_k （int，默认值：5）：建议数

例子：

thematic_recommendations_by_title_tool(
    reference_title="The Hunger Games",
    top_k=5
)

项目结构

.
├── data/
│   └── movies/              # Movie dataset files
│       ├── plot_summaries.txt
│       ├── movie.metadata.tsv
│       └── character.metadata.tsv
├── src/
│   └── mcp_server/
│       ├── __init__.py
│       ├── movie_server.py      # Main MCP server
│       ├── schemas.py           # Pydantic data models
│       ├── config/
│       │   └── settings.py      # Configuration settings
│       ├── tools/
│       │   ├── movie_search.py  # Movie search implementation
│       │   ├── country_normalizer.py
│       │   └── country_constants.py
│       ├── scripts/
│       │   ├── load_movie_db.py  # Load movies into Qdrant
│       │   └── clear_vector_db.py
│       └── utils.py             # Qdrant and embedding utilities
├── tests/
│   └── mcp_server/          # Tests for MCP tools
├── docs/
│   ├── qdrant-vector-search.md
│   ├── mcp-prompts.md
│   └── tools-vs-resources.md
├── docker-compose.yaml      # Docker services configuration
├── Dockerfile               # Docker image definition
├── Makefile                 # Build and run commands
├── pyproject.toml           # Python dependencies
├── .env.example             # Environment variables template
└── README.md

可用的生成命令

发展

使用VS代码/游标开发容器

1. 准备devcontainer：

   make devcontainer

1. 在VS代码/光标中：

- 命令面板（Cmd/Ctrl+Shift+P） - 选择“开发容器：在容器中重新打开”

运行测试

# Run all tests
make test

# Run specific test file
make run-interactive
uv run pytest tests/mcp_server/test_movie_search.py -v

代码的风格

我们使用 ruff 对于代码格式化和linting：

# Inside container
ruff check
ruff format

文档

• Qdrant矢量搜索：矢量搜索、嵌入和数据库管理的完整指南
• MCP提示：理解和实施MCP提示
• 工具与资源：MCP图元说明

技术细节

技术

• 快速MCP：MCP服务器框架
• Qdrant：用于语义搜索的矢量数据库
• OpenAI嵌入: text-embedding-3-small 模型（1536个维度）
• 骆驼索引：矢量存储集成
• 派丹蒂克：数据验证和模式
• 码头工人：集装箱化

建筑

1. 矢量存储器：电影情节摘要使用OpenAI嵌入并存储在Qdrant中
2. 语义搜索：用户查询被嵌入，并使用余弦相似度与存储的向量进行匹配
3. 查询优化：使用OpenAI API自动优化查询，以改进语义匹配
4. 元数据筛选：矢量搜索后，结果按年份、国家和类型过滤

许可证

BSD 3条款许可

版权所有2025，芝加哥大学数据科学研究所。

贡献

欢迎投稿！请随时提交拉取请求。

致谢

• 电影数据来自 CMU电影摘要语料库
• 建于 快速MCP 和 模型上下文协议