电影MCP服务器

生产准备就绪 模型上下文协议（MCP）服务器 用于智能电影数据库管理，基于Clean Architecture原则构建，并针对人工智能辅助环境进行了优化。

🎉 由Golang MCP官方SDK v1.1.0提供技术支持 使用Anthropic和Google维护的官方MCP SDK构建，提供类型安全、自动模式生成和生产就绪可靠性。看 SDK迁移有关迁移的详细信息。

✅ 仅SDK实现 旧版自定义服务器已归档。此项目现在仅使用官方基于SDK的服务器 cmd/server-sdk/。参见服务器状态了解详情。

什么是电影MCP服务器？

Movies MCP Server是一个复杂的电影数据库管理系统，通过 模型上下文协议--专为与Claude等AI助手集成而设计。与传统的HTTP API不同，它通过stdin/stdout使用JSON-RPC来提供无缝、智能的电影和演员数据操作。

非常适合：

人工智能电影推荐系统
Claude桌面集成
智能电影分析与探索
职业研究总监
人工智能辅助的电影数据库管理

______________________________________________________________________

为什么选择电影MCP服务器？

MCP协议本机：使用官方Golang SDK专门为模型上下文协议构建
类型安全&现代：利用官方SDK进行编译时验证和自动模式生成
清洁建筑：领域驱动设计的关注点分离示例
智能功能：人工智能推荐、导演职业分析和相似性搜索
全面的演员管理：完整的演员数据库，包括电影协会和职业跟踪
生产准备就绪：健康检查、普罗米修斯指标、Grafana仪表板和全面监控
高级搜索：全文搜索、十年筛选、评分范围、类型匹配和相似性评分
图像支持：使用base64编码通过MCP资源存储和检索电影海报
BDD测试：全面覆盖Cucumber/Godog行为场景的测试
Docker优化：多阶段构建、无发行版映像、非根执行

______________________________________________________________________

关键绩效指标

吞吐量：>负载下50次操作/秒
并发：安全处理50多个并发请求
响应时间：典型操作\<100ms
测试覆盖率：BDD场景的综合单元和集成测试
编码效率通过SDK迁移，代码减少了26%（减少了约1200行）

______________________________________________________________________

MCP能力

23可用工具

电影管理（8个工具）

get_movie -按ID检索电影
add_movie -创建带有标题、导演、年份、评级、流派、海报的电影
update_movie -更新现有电影详细信息
delete_movie -按ID删除电影
list_top_movies -获取具有可配置限制的顶级电影
search_movies -多条件搜索（标题、导演、流派、年份范围、评级）
search_by_decade -查找特定年代（1990年代、2000年代等）的电影
search_by_rating_range -按分级边界过滤电影

演员管理（9个工具）

add_actor -用名字、出生年份、传记创建演员
get_actor -按ID检索演员
update_actor -更新演员信息
delete_actor -删除演员
link_actor_to_movie -与电影合作的演员
unlink_actor_from_movie -删除演员与电影的关联
get_movie_cast -让所有演员都出演一部电影
get_actor_movies -为演员获取所有电影
search_actors -通过出生年份过滤按姓名搜索演员

情报与分析（3个复合工具）

bulk_movie_import -导入多部带有错误跟踪的电影
movie_recommendation_engine -基于人工智能的推荐，带有偏好评分
director_career_analysis -职业轨迹与早期/中期/晚期分析

上下文管理（3个工具）

create_search_context -为大型结果集创建分页搜索上下文
get_context_page -从搜索上下文中检索特定页面
get_context_info -获取上下文元数据和页面信息

5内置提示

电影推荐 -根据偏好生成个性化推荐
电影分析 -分析主题、摄影和特征
导演摄影 -探索导演的作品和演变
genre_探索 -深入了解流派历史和有影响力的电影
电影_比较 -从多个维度比较两部电影

3 MCP资源

movies://database/all -JSON格式的完整电影数据库
movies://database/stats -数据库统计和分析
movies://posters/collection -所有电影海报（base64编码）
动态： movies://posters/{movie-id} -个人电影海报

______________________________________________________________________

建筑与技术

清洁架构实施

基于严格的关注点分离构建：

internal/
├── domain/          # Pure business logic (entities, value objects)
├── application/     # Use cases and orchestration
├── infrastructure/  # Database and external integrations
├── mcp/            # MCP SDK tools and handlers
└── composition/     # Dependency injection

优点：

框架独立性
可测试的业务逻辑
数据库无关（目前为PostgreSQL）
易于维护和扩展

技术栈

核心：

使用Go 1.24.4工具链执行Go 1.23.0+
Golang MCP官方SDK v1.1.0 -类型安全协议实现
PostgreSQL 17具有高级索引功能
基于JSON-RPC的模型上下文协议（MCP）

关键库：

github.com/modelcontextprotocol/go-sdk -官方MCP SDK
github.com/lib/pq -PostgreSQL驱动程序
github.com/cucumber/godog -BDD测试
github.com/testcontainers/testcontainers-go -集成测试
github.com/sirupsen/logrus -结构化日志记录
OpenTetry-分布式跟踪

数据库功能：

全文搜索（GIN索引）
基于数组的流派过滤
多对多演员电影关系
自动时间戳管理
图像存储（BYTEA列）

______________________________________________________________________

快速开始

先决条件

转到1.24.4或更高版本
Docker和Docker Compose（可选，用于数据库）
PostgreSQL 17（或使用基于Docker的设置）
Make（可选，便于命令）

安装

克隆存储库:

   git clone https://github.com/francknouama/movies-mcp-server.git
   cd movies-mcp-server

设置环境:

   cp .env.example .env
   # Edit .env with your database settings

启动数据库 （如果使用Docker）：

   make docker-up

初始化数据库:

   make db-setup      # Create database
   make db-migrate    # Run migrations
   make db-seed       # Load sample data

构建SDK服务器 （推荐）：

   go build -o movies-mcp-server-sdk ./cmd/server-sdk/

运行SDK服务器:

   # With environment variables
   export DB_HOST=localhost
   export DB_PORT=5432
   export DB_USER=movies_user
   export DB_PASSWORD=movies_password
   export DB_NAME=movies_mcp
   export DB_SSLMODE=disable

   ./movies-mcp-server-sdk

或者用旗帜：

   ./movies-mcp-server-sdk --version        # Show version
   ./movies-mcp-server-sdk --help           # Show help
   ./movies-mcp-server-sdk --skip-migrations # Skip DB migrations

Docker部署

开发（仅数据库）：

docker-compose -f docker-compose.dev.yml up

生产（带监控）：

docker-compose -f docker-compose.clean.yml up

包含的服务：

PostgreSQL 17（端口5432）
电影MCP服务器
格拉法纳（端口 3000）
pgAdmin（端口5050）
普罗米修斯（端口9090）

______________________________________________________________________

与Claude Desktop集成

将Claude Desktop配置为将Movies MCP Server与基于SDK的服务器一起使用：

配置文件位置：

操作系统	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
视窗	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

配置：

{
  "mcpServers": {
    "movies": {
      "command": "/absolute/path/to/movies-mcp-server-sdk",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "movies_user",
        "DB_PASSWORD": "movies_password",
        "DB_NAME": "movies_mcp",
        "DB_SSLMODE": "disable"
      }
    }
  }
}

重新启动克劳德桌面 以激活集成。

你能和克劳德做什么

“给我找20世纪90年代收视率超过8的惊悚电影”
增加一部新电影：克里斯托弗·诺兰执导的《盗梦空间》，2010年上映
“给我看看莱昂纳多·迪卡普里奥主演的所有电影”
“分析昆汀·塔伦蒂诺的职业生涯轨迹”
“推荐类似《教父》的电影”
“批量导入此电影列表”

______________________________________________________________________

SDK迁移

迁移完成！ 🎉

该项目已经 完全迁移 从自定义MCP协议实现到 官方Golang MCP SDK v1.1.0.

主要改进：

✅ 代码减少26% -消除了约1200行自定义协议层
✅ 类型安全处理程序 -使用Go类型进行编译时验证
✅ 自动模式生成 -没有手动JSON模式定义
✅ 简化测试 -测试代码减少37%，清晰度更好
✅ 官方支持 -由Anthropic和谷歌维护
✅ 业务逻辑无变化 -保持干净的建筑

迁移了什么：

23个MCP工具（所有计划工具）
基于SDK的主服务器(cmd/server-sdk/main.go)
综合单元测试
完整文档

文档：

SDK迁移比较 -前后代码示例
测试比较 -测试改进
迁移完成 -完整迁移摘要

✅ 服务器状态：仅SDK实现

活动服务器： cmd/server-sdk/ -基于SDK的官方实现

电影MCP服务器现在使用仅官方Golang MCP SDK v1.1.0，提供：

✅ Anthropic和谷歌维护的官方SDK
✅ 代码减少26%，类型安全性更好
✅ 自动模式生成
✅ 改进了可维护性和测试
✅ 生产就绪并经过全面测试

已存档的旧服务器： 已弃用的自定义服务器已存档到 legacy/ 目录。看 legacy/README.md 了解档案详情。

______________________________________________________________________

高级功能

智能推荐引擎

多因素评分算法：

类型匹配 （40%重量）
评分分数 （30%重量）
年份相关性 （20%重量）
人气提升 （10%重量）

返回带有匹配分数和推理的排名推荐。

董事职业分析

自动分析包括：

职业阶段检测（早期/中期/晚期）
每个阶段的平均评级
流派专业化追踪
职业轨迹（上升/下降/峰值/复苏）
著名作品（最佳和最差评分）

批量进口业务

使用以下工具一次导入多部电影：

每项错误跟踪
成功/失败统计
部分成功处理
详细的错误报告

高级搜索功能

全文搜索：使用PostgreSQL GIN索引的标题、导演、描述
十年解析：智能处理“1990s”、“90s”和“1990”格式
相似性评分：基于类型和评级的推荐
多标准过滤：结合标题、流派、年份范围、评级范围
分页支持：高效处理大型结果集

______________________________________________________________________

监测和可观察性

普罗米修斯指标

港口可用 9090 综合指标：

请求/响应时间
并行操作
数据库连接池统计信息
查询性能
内存和CPU利用率

Grafana仪表板

在港口进入Grafana 3000 用于：

实时性能监控
数据库健康可视化
自定义警报规则
系统资源跟踪

健康检查

内置健康检查功能：

可配置间隔（默认值：30秒）
数据库连接验证
优雅降级
状态报告

警报规则

针对以下对象的预配置警报：

错误率高
查询性能缓慢
数据库连接问题
内存/CPU阈值

配置： monitoring/alert_rules.yml

______________________________________________________________________

开发者指南

测试

运行所有测试：

make test                  # Unit tests
make test-integration      # Integration tests with testcontainers
make test-coverage         # Coverage report
make test-bdd              # BDD scenarios with Godog

BDD功能测试：

Gherkin的40+个行为场景
通过测试容器实现真正的PostgreSQL
MCP协议的合同测试
性能和负载测试

数据库迁移

make db-migrate            # Apply migrations
make db-migrate-down       # Rollback last migration
make db-migrate-reset      # Reset database
make db-create-migration   # Create new migration

代码质量

make fmt                   # Format code
make vet                   # Run go vet
make lint                  # Run golangci-lint

编译选项

# Build SDK server (recommended)
go build -o movies-mcp-server-sdk ./cmd/server-sdk/

# Build legacy custom server
make build

# Build all variants
make build-all

# Build Docker image
make docker-build

# Create release
make release               # Create release with goreleaser

环境变量

数据库：

DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE
DATABASE_URL -完整连接字符串（旧服务器）
DB_MAX_CONNECTIONS=100, DB_MAX_IDLE_CONNECTIONS=10

服务器：

PORT=8080, METRICS_PORT=9090
READ_TIMEOUT=30s, WRITE_TIMEOUT=30s
LOG_LEVEL （调试/信息/警告/错误）

安全：

JWT_SECRET, API_KEY
RATE_LIMIT=1000 （每分钟每IP）
TLS_ENABLED, TLS_CERT_FILE, TLS_KEY_FILE

监控：

PROMETHEUS_ENABLED=true
HEALTH_CHECK_INTERVAL=30s

看 .env.example 了解完整的配置选项。

______________________________________________________________________

文档

综合文档可在 /docs 目录：

入门指南：

指南：

用户指南 -功能演练
例子 -代码示例

架构：

架构概述 -清洁建筑详图
-Docker设置和配置
部署指导 -生产部署
图像支持 -通过MCP进行图像处理

SDK迁移：

SDK迁移比较 -前后代码示例
测试比较 -测试改进
迁移完成 -完整迁移摘要

参考：

API 参考 -完整的API文件
故障排除 -常见问题
常见问题解答 -常见问题解答

______________________________________________________________________

项目结构

movies-mcp-server/
├── cmd/
│   └── server-sdk/          # ✅ Official SDK-based server (ACTIVE)
├── internal/
│   ├── domain/              # Business logic (entities, value objects)
│   ├── application/         # Use cases and services
│   ├── infrastructure/      # Database and integrations
│   ├── mcp/                # ✅ MCP SDK tools and handlers (58 tests)
│   └── config/              # Configuration management
├── legacy/                  # 📦 Archived legacy server code
│   ├── cmd/server/          # Deprecated custom server
│   ├── internal/            # Deprecated handlers and schemas
│   └── tests/integration/   # Legacy integration tests
├── migrations/              # Database migrations
├── tests/
│   └── bdd/                # BDD feature files (tests SDK server)
├── docs/                    # Documentation
├── monitoring/              # Prometheus and Grafana configs
└── docker/                  # Docker configurations

______________________________________________________________________

贡献

我们欢迎捐款！请查看贡献指南用于：

行为准则
开发设置
拉取请求流程
编码标准
测试要求

______________________________________________________________________

支持与社区

发现bug了吗？ 报告问题
有问题吗？ 检查常见问题解答
需要帮助？ 看故障排除指南
想贡献吗？ 阅读开发指南

______________________________________________________________________

许可证

该项目根据MIT许可证获得许可。看许可证文件以获取详细信息。

______________________________________________________________________

致谢

特别感谢：

模型上下文协议对于MCP生态系统
Anthropic 用于Claude和MCP开发
谷歌用于共同维护官方Golang MCP SDK
PostgreSQL社区提供强大的数据库
去社区寻找优秀的工具和库
本项目的所有贡献者和用户

______________________________________________________________________

接下来是什么？

看实施_计划.md 路线图包括：

GraphQL集成
高级缓存策略
增强的推荐算法
多语言支持
实时通知

______________________________________________________________________

基于Clean Architecture原则和官方Golang MCP SDK构建，具有可维护性、可测试性和可扩展性。

Movies MCP Server

快速接入

详细介绍

电影MCP服务器

什么是电影MCP服务器？

为什么选择电影MCP服务器？

关键绩效指标

MCP能力

23可用工具

电影管理（8个工具）

演员管理（9个工具）

情报与分析（3个复合工具）

上下文管理（3个工具）

5内置提示

3 MCP资源

建筑与技术

清洁架构实施

技术栈

快速开始

先决条件

安装

Docker部署

与Claude Desktop集成

你能和克劳德做什么

SDK迁移

迁移完成！ 🎉

✅ 服务器状态：仅SDK实现

高级功能

智能推荐引擎

董事职业分析

批量进口业务

高级搜索功能

监测和可观察性

普罗米修斯指标

Grafana仪表板

健康检查

警报规则

开发者指南

测试

数据库迁移

代码质量

编译选项

环境变量

文档

项目结构

贡献

支持与社区

许可证

致谢

接下来是什么？

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP