BFI MCP

BFI-MCP：克劳德·米CP为BFI南岸电影

高性能模型上下文协议（MCP）服务器，用于通过智能过滤和搜索访问BFI南岸电影放映数据。内置 Types/Node.js 使用官方MCP SDK并针对 Alpic 云部署。

特性

✅ 139部BFI电影 -完整的元数据、描述和筛选 ✅ 智能过滤 -按类别、位置、导演、日期范围筛选 ✅ 全文检索 -在标题、导演、描述中搜索 ✅ 完整详细信息 -放映、评级、演员阵容、运行时间、格式 ✅ Express.js HTTP服务器 -流式HTTP MCP传输 ✅ Types/Node.js -类型安全的现代JavaScript后端 ✅ Alpic准备就绪 -零配置自动部署

快速入门：部署到Alpic

看 ALPIC_SETUP.md 获取完整的部署说明。

1分钟设置

1. 首选https://alpic.ai
2. 使用GitHub登录
3. 点击“新建项目”
4. 选择 OlivierAlter/BFI-MCP
5. 点击“创建”
6. Alpic自动检测和部署
7. 获取您的公共端点

就是这样！您的MCP已上线。

局部测试

再进行

npm install

构建TypeScript

npm run build

在本地运行HTTP服务器

npm start

服务器在上运行 http://127.0.0.1:3000/mcp （POST端点）

使用MCP检查员进行测试

npm run inspector

或者直接使用npx：

npx @modelcontextprotocol/inspector

选择 流式HTTP → Enter http://127.0.0.1:3000/mcp

发展模式

对于开发过程中的热重新加载：

npm run dev

监视TypeScript文件并在更改时重新启动。

配置Claude代码

要在本地使用Claude Code：

{
  "mcpServers": {
    "bfi": {
      "url": "http://127.0.0.1:3000/mcp",
      "transport": "http"
    }
  }
}

注： 保持 npm start 在使用Claude Code时运行。

使用已部署的MCP

在Alpic上部署后，与Claude Code集成：

{
  "mcpServers": {
    "bfi": {
      "url": "https://mcp-server-XXXXXXX.alpic.live",
      "transport": "http"
    }
  }
}

或与MCP Inspector一起使用：

npx @modelcontextprotocol/inspector

选择 流式HTTP → 输入您的Alpic端点

______________________________________________________________________

脚本

可用的npm命令：

npm run build        # Compile TypeScript to JavaScript
npm start           # Start production server on port 3000
npm run dev         # Start development server with hot-reload
npm run inspector   # Launch MCP Inspector for testing

工具

1. list-films -列出和过滤胶片

列出所有具有可选过滤功能的BFI胶片。

参数：

• category （可选）-按类别筛选
• location （可选）-按影院位置过滤
• director （可选）-按导演姓名筛选
• start_date （可选）-从日期（YYYY-MM-DD）开始筛选
• end_date （可选）-筛选截止日期（YYYY-MM-DD）
• limit （可选）-要返回的最大结果（默认值：50）

示例：

"Show me all Christmas films"
→ Uses: category="christmas_films"

"List films at BFI IMAX"
→ Uses: location="BFI IMAX"

"Show all James Cameron films"
→ Uses: category="james_cameron"

"Find screenings between October 20 and November 5"
→ Uses: start_date="2025-10-20", end_date="2025-11-05"

"Show melodrama films by Sirk"
→ Uses: category="melodrama", director="Sirk"

______________________________________________________________________

2. search-films -全文搜索

按标题、导演或描述搜索电影。

参数：

• query （必填）-搜索查询
• limit （可选）-最大结果（默认值：20）

示例：

"Find 'Terminator' films"
"Search for Hitchcock"
"Find films about love"
"Look for 'sci-fi'"

______________________________________________________________________

3. get-film-details -获取完整的电影信息

检索特定电影的完整细节，包括所有放映。

参数：

• title （必填）-确切的电影标题

退货：

• 电影元数据（导演、演员、放映时间、格式、评级）
• 完整描述
• 所有带有日期、时间和地点的放映

示例：

"Get details on The Terminator"
"Show me all info about Aliens"
"What time is Brief Encounter screening?"

______________________________________________________________________

可用过滤器

分类

• james_cameron -詹姆斯·卡梅隆回顾展
• christmas_films -假期节目
• richard_burton -理查德·伯顿回顾展
• melodrama -《太多：电影上的音乐剧》系列
• classics -大屏幕经典
• frederick_wiseman -弗雷德里克·怀斯曼纪录片
• in_person -活动和问答
• new_releases -新上映的戏剧作品
• re_releases -经典重新发布
• regular_programme -特别放映

位置

• NFT1, NFT2, NFT3, NFT4 -主要影院屏幕
• BFI IMAX -IMAX屏幕
• BFI REUBEN LIBRARY -图书馆活动
• BFI BLUE ROOM -讨论场所
• BFI BAR -酒吧/休息区
• BFI SOUTHBANK FOYER -门厅活动

______________________________________________________________________

用例

计划您的电影院之旅

"I want to watch films at BFI IMAX this month. What's available?"
→ list-films(location="BFI IMAX", start_date="2025-11-08", end_date="2025-11-30")

寻找特定董事

"Show me all Laura Mulvey films screening"
→ search-films(query="Laura Mulvey")

类别浏览

"What are the classic films screening?"
→ list-films(category="classics")

完整电影细节

"I want to know everything about Aliens"
→ get-film-details(title="Aliens (Extended Cut)")

______________________________________________________________________

数据结构

MCP从JSON文件中加载数据 data/ 目录：

data/
├── bfi_all_films.json           (Combined all films)
├── bfi_james_cameron.json       (Category-specific)
├── bfi_classics.json
├── bfi_christmas_films.json
├── bfi_melodrama.json
├── bfi_richard_burton.json
├── bfi_frederick_wiseman.json
├── bfi_new_releases.json
├── bfi_re_releases.json
└── bfi_regular_programme.json

加载时间：仅启动（1秒以内） 数据新鲜度：手动-从复制新的JSON文件 ../output/ 如果可用

______________________________________________________________________

更新胶片数据

当新的BFI指南发布时：

1. 生成新的JSON文件：

   cd ..
   ./monthly_update.sh ~/Downloads/BFI_[Month]_[Year].pdf

1. 将更新的文件复制到MCP：

   cp ../output/*.json data/

1. 重新启动Claude Code以重新加载数据

______________________________________________________________________

错误处理

• 未找到影片：返回错误消息
• 无效的日期格式：忽略无效日期
• 空搜索：返回错误
• 数据加载失败：服务器在启动时报告错误

______________________________________________________________________

演出

• 加载时间：\<1秒（启动时）
• 列出电影：\<10ms
• 搜索：\<50ms
• 获取详细信息：\<1ms
• 记忆：~5-10 MB

______________________________________________________________________

建筑

项目结构

src/
├── index.ts          Express HTTP server with /mcp endpoint
├── server.ts         MCP server with 3 tools (Zod schemas)
├── dataLoader.ts     Film data loading and filtering
├── config.ts         Configuration (PORT, paths)
└── data/             JSON data files
    └── bfi_*.json    Film data by category

dist/                 Compiled JavaScript (generated by tsc)
├── index.js
├── server.js
├── dataLoader.js
└── config.js

技术栈

• 运行时：Node.js 20+
• 语言：TypeScript 5.x
• 框架：Express.js 5.x
• MCP-SDK：@modelcontextprotocol/sdk
• 架构验证：佐德
• 构建：TypeScript编译器（tsc）

关键文件

• src/index.ts：快速应用程序设置，/mcp端点处理程序
• src/server.ts：MCP服务器配置和工具定义
• src/dataLoader.ts：胶片数据加载、过滤和搜索
• package.json：依赖关系和npm脚本
• Tsconflict.儿子：TypeScript编译器配置

______________________________________________________________________

发展

理解代码

MCP服务器使用官方SDK实现了3个工具：

// Tools are defined with Zod schemas for type safety
server.tool("list-films", description, schema, handler)
server.tool("search-films", description, schema, handler)
server.tool("get-film-details", description, schema, handler)

每个工具操作员：

1. 接收经过验证的参数（Zod确保类型安全）
2. 调用dataLoader函数
3. 返回带内容的格式化CallToolResult

本地测试工具

构建并启动服务器：

npm run build
npm start

使用MCP检查器进行测试：

npm run inspector

或直接测试：

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{...},"id":1}'

______________________________________________________________________

许可证

个人使用。BFI指南数据来自BFI南岸，经许可用于日历解析。

______________________________________________________________________

总结

开始：

npm install && npm run build && npm start

然后用以下方法进行测试：

npm run inspector