Gallica/BnF的Node.js MCP服务器
一个高质量的TypeScript/Node.js MCP（模型上下文协议）服务器，用于访问法国国家图书馆（BnF）的Gallica数字图书馆。此服务器忠实地再现了 Python MCP服务器 并扩展了IIIF图像、OCR文本和项目元数据的附加功能。
特性
核心搜索工具（8个工具-匹配Python）
- 搜索_标题 -使用精确匹配选项按标题搜索文档
- 搜索_作者 -使用精确匹配选项按作者搜索文档
- 搜索\_ \_主题 -使用精确匹配选项按主题搜索文档
- 搜索_日期 -按日期（YYYY、YYYY-MM或YYYY-MM-DD）搜索文档
- search_by_document_type -按文档类型搜索（专题、期刊、图像等）
- 高级搜索 -用于复杂搜索的自定义CQL查询语法
- 自然语言搜索 -跨所有字段的自然语言搜索
- 顺序报告 -通过源代码管理生成多步顺序报告
扩展工具（4个新工具）
- get_item_details -通过ARK标识符获取项目的完整元数据
- 获取项目页面 -使用IIIF URL枚举文档的页面
- get_page_image -为特定页面生成IIIF图像URL
- get_page_text -检索OCR/文本内容（ALTO，纯文本）
安装
先决条件
- Node.js 18.0或更高版本
- npm或纱线
步骤
- 克隆或下载此存储库
- 安装依赖项：
cd node-mcp-bnf
npm install- 构建项目：
npm run build用法
本地开发
选项1:HTTP服务器（建议用于开发）
在本地HTTP端口上运行服务器进行测试：
npm run dev:http这将启动服务器 http://localhost:3000 （或中指定的端口 PORT 环境变量）。
服务器将：
- 在指定端口上监听
- 通过HTTP/SSE接受MCP请求
- 将所有活动记录到控制台
您可以通过将MCP客户端连接到 http://localhost:3000/message.
选项2:STDIO模式（适用于MCP客户端）
服务器可以通过STDIO在本地与Claude Desktop或Cursor MCP一起使用。
在STDIO模式下运行：
npm run devClaude桌面配置
添加到您的Claude Desktop配置文件（通常 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"gallica-bnf": {
"command": "node",
"args": ["/path/to/node-mcp-bnf/dist/index.js"],
"cwd": "/path/to/node-mcp-bnf"
}
}
}光标MCP配置
添加到光标MCP设置中：
{
"mcpServers": {
"gallica-bnf": {
"command": "node",
"args": ["/path/to/node-mcp-bnf/dist/index.js"]
}
}
}开发脚本
npm run dev-在STDIO模式下运行（适用于Cursor/Claude Desktop等MCP客户端）npm run dev:http-在本地端口上运行HTTP服务器（默认值：3000）npm start-运行已编译的STDIO版本npm run start:http-运行编译的HTTP服务器版本
HTTP服务器的环境变量：
PORT-监听端口（默认值：3000）LOG_LEVEL-日志记录级别（错误、警告、信息、调试）
在Vercel上部署
先决条件
- Vercel帐户
- 已安装Vercel CLI(
npm i -g vercel)
步骤
- 创建
vercel.json在项目根目录中：
{
"functions": {
"src/httpServer.ts": {
"runtime": "nodejs18.x"
}
},
"routes": [
{
"src": "/(.*)",
"dest": "src/httpServer.ts"
}
]
}- 在Vercel仪表板中设置环境变量：
- GALLICA_BASE_URL （可选，默认值： https://gallica.bnf.fr) - GALLICA_SRU_URL （可选，默认值： https://gallica.bnf.fr/SRU) - LOG_LEVEL （可选，默认值： info) - MCP_ICON_URL （可选，图标的绝对URL-默认为 /icon.svg 相对于服务器URL）
- 部署：
vercel deploy- 配置Cursor/Claude Desktop以使用HTTP端点：
{
"mcpServers": {
"gallica-bnf": {
"url": "https://your-vercel-app.vercel.app"
}
}
}API文档
搜索工具
搜索_标题
按标题搜索文档。
参数：
title（string，必填）：要搜索的标题exact_match（boolean，可选）：如果为true，则搜索确切的标题max_results（数字，可选，默认值：10）：最大结果（1-50）start_record（数字，可选，默认值：1）：分页的起始记录
例子：
{
"title": "Les Misérables",
"exact_match": false,
"max_results": 10
}搜索_作者
按作者搜索文档。
参数：
author（string，必填）：作者姓名exact_match（boolean，可选）：如果为true，则搜索确切的作者姓名max_results（数字，可选，默认值：10）start_record（数字，可选，默认值：1）
搜索\_ \_主题
按主题/关键字搜索文档。
参数：
subject（string，必填）：要搜索的主题exact_match（布尔值，可选）max_results（数字，可选，默认值：10）start_record（数字，可选，默认值：1）
搜索_日期
按发布日期搜索文档。
参数：
date（字符串，必填）：日期格式为YYYY、YYYY-MM或YYYY-MM-DDmax_results（数字，可选，默认值：10）start_record（数字，可选，默认值：1）
例子：
{
"date": "1862",
"max_results": 20
}search_by_document_type
按类型搜索文档。
参数：
doc_type（字符串，必填）：文档类型（专著、期刊、图像、手稿、地图、音乐等）max_results（数字，可选，默认值：10）start_record（数字，可选，默认值：1）
高级搜索
使用自定义CQL查询执行高级搜索。
参数：
query（string，必填）：CQL查询字符串max_results（数字，可选，默认值：10）start_record（数字，可选，默认值：1）
例子：
{
"query": "dc.creator all \"Victor Hugo\" and dc.type all \"monographie\""
}自然语言搜索
跨所有字段的自然语言搜索。
参数：
query（字符串，必填）：自然语言搜索查询max_results（数字，可选，默认值：10）start_record（数字，可选，默认值：1）
扩展工具
get_item_details
获取项目的完整元数据。
参数：
ark（字符串，必填）：ARK标识符（例如，“ARK:/12148/bpt6k123456”或“bpt6k123456）
退货：
- 书目数据（标题、创建者、日期等）
- 可用格式（iiif、图像、文本、alto）
- IIIF清单URL
- 高卢URL
获取项目页面
枚举文档的页面。
参数：
ark（字符串，必填）：ARK标识符page（数字，可选）：获取特定页码page_size（数字，可选）：获取前N页page_range（数组，可选）：获取范围\[start，end\]内的页面
退货：
- 页面信息数组，包含：
- 页码 - 标签 - IIIF图像URL - 文本可用性标志 - 缩略图URL
get_page_image
获取特定页面的IIIF图像URL。
参数：
ark（字符串，必填）：ARK标识符page（数字，必填）：页码size（字符串，可选）：图像大小（例如，“满”、“200”、“500500”）region（字符串，可选）：图像区域（例如，“完整”、“x、y、w、h”）
退货：
- IIIF图像URL
- 缩略图URL
get_page_text
检索页面的OCR/文本内容。
参数：
ark（字符串，必填）：ARK标识符page（数字，必填）：页码format（字符串，可选）：文本格式（“纯”、“alto”、“tei”）
退货：
- 文本内容（如果不可用，则为空）
- 可用性标志
顺序报告工具
顺序报告
以循序渐进的方式生成研究报告。
工作流程：
- 初始化：
{
"topic": "Impressionnisme en France",
"page_count": 4,
"source_count": 10,
"include_graphics": true
}- 搜索来源：
{
"search_sources": true
}- 创建参考书目：
{
"section_number": 1,
"total_sections": 8,
"title": "Bibliography",
"content": "...",
"is_bibliography": true,
"sources_used": [1, 2, 3],
"next_section_needed": true
}- 按顺序编写部分：
{
"section_number": 2,
"total_sections": 8,
"title": "Introduction",
"content": "...",
"sources_used": [1, 2],
"next_section_needed": true
}- 完整报告：
{
"section_number": 8,
"total_sections": 8,
"title": "Conclusion",
"content": "...",
"sources_used": [5, 6],
"next_section_needed": false
}配置
环境变量
GALLICA_BASE_URL-Gallica API的基本URL（默认值：https://gallica.bnf.fr)GALLICA_SRU_URL-SRU搜索端点（默认值：https://gallica.bnf.fr/SRU)LOG_LEVEL-日志记录级别：error,warn,info,debug（默认值：info)HTTP_TIMEOUT-HTTP请求超时（毫秒）（默认值：30000）HTTP_RETRIES-最大重试次数（默认值：3）DEFAULT_MAX_RECORDS-默认最大搜索结果数（默认值：10）DEFAULT_START_RECORD-分页的默认起始记录（默认值：1）
发展
项目结构
node-mcp-bnf/
├── src/
│ ├── index.ts # STDIO entry point
│ ├── httpServer.ts # HTTP entry point
│ ├── mcpServer.ts # MCP server setup
│ ├── config.ts # Configuration
│ ├── logging.ts # Logging utility
│ ├── tools/ # MCP tools
│ └── gallica/ # Gallica API clients
├── docs/ # Documentation
├── tests/ # Unit tests
└── package.json建筑
npm run build测试
npm test发展模式
npm run dev文档
- Python架构分析 -对原始Python服务器的分析
- 加利卡API说明 -API详细文件
- -该服务器的架构和设计
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交拉取请求。
致谢
- 基于Python MCP服务器 危机
- 使用 模型上下文协议 软件开发工具包
- 为 Gallica数字图书馆 法国国家图书馆