IIIF-MCP服务器

Name: IIIF-MCP服务器
Author: trevormunoz

作者：trevormunoz2 星标更新：2025-07-09

安装使用来源：spider==github.com

项目介绍

IIIF MCP 服务器

这是一个提供对 IIIF（国际图像互操作框架）文档访问的模型上下文协议（MCP）服务器。该服务器使AI助手能够检索、缓存并搜索 IIIF API 规范，包括图像 API、展示 API、搜索 API 和认证 API 文档。

功能

📚 文档检索：从 iiif.io 获取并缓存 IIIF API 文档。
🔍 智能搜索：通过关键词匹配在缓存的文档中进行搜索。
💾 智能缓存：基于 SQLite 的缓存，可配置的 TTL（默认24小时）。
✅ 内容验证：验证检索到的内容是否包含 IIIF 特定模式。
📊 健康监控：基本的操作状态健康检查。

安装

# 克隆仓库
git clone <repository-url>
cd iiif-mcp

# 安装依赖
npm install

# 构建项目
npm run build

使用

启动服务器

# 开发模式
npm run dev

# 生产模式
npm start

可用工具

1. `get_api_docs` - 检索 IIIF 文档

获取特定 IIIF API 的文档。

{
  "name": "get_api_docs",
  "arguments": {
    "api": "image",
    "version": "3.0",
    "section": "parameters",
    "forceRefresh": false
  }
}

参数：

api（必需）：API 类型（image，presentation，search，auth）
version（可选）：API 版本（默认：3.0）
section（可选）：按标题过滤到特定部分
forceRefresh（可选）：强制从源刷新（默认：false）

2. `search_docs` - 搜索文档

在缓存的 IIIF 文档中进行搜索。

{
  "name": "search_docs", 
  "arguments": {
    "query": "image parameters",
    "apis": ["image", "presentation"],
    "maxResults": 5
  }
}

参数：

query（必需）：要查找的搜索词
apis（可选）：特定的 API 要搜索（默认：所有常见 API）
maxResults（可选）：返回的最大结果数（默认：1_0）

3. `health_check` - 服务器健康状态

检查服务器的操作状态和数据库连接性。

{
  "name": "health_check",
  "arguments": {}
}

4. `ping` - 测试连接

测试服务器连接性和响应性。

{
  "name": "ping",
  "arguments": {
    "includeTimestamp": true
  }
}

配置

使用环境变量配置服务器：

# 缓存目录（默认：./cache）
export IIIF_CACHE_DIR=/path/to/cache

# HTTP 请求超时时间（毫秒，默认：5000）
export IIIF_HTTP_TIMEOUT=10000

# 日志级别（默认：info）
export IIIF_LOG_LEVEL=debug

架构

核心组件

MCP 服务器：处理工具请求和响应
HTTP 客户端：具有重试逻辑的从 iiif.io 获取内容
内容缓存：基于 SQLite 的缓存，TTL 管理
解析器：从 HTML 文档中提取和结构化内容
验证器：确保检索到的内容是有效的 IIIF 文档
监控器：操作状态的健康检查

文件结构

src/
├── server.ts              # MCP 服务器设置和工具路由
├── config.ts              # 配置管理
├── http.ts                 # 具有重试逻辑的 HTTP 客户端
├── cache.ts                # SQLite 内容缓存
├── parser.ts               # HTML 解析和文本提取
├── validation.ts           # 内容验证和错误处理
├── monitoring.ts           # 健康监控
└── tools/
    ├── ping.ts            # Ping 工具实现
    ├── get-docs.ts        # 文档检索工具
    └── search.ts          # 搜索功能

开发

运行测试

# 运行所有测试
npm test

# 在监视模式下运行测试
npm run test:watch

# 运行特定测试文件
npm test -- config.test.ts

类型检查

# 检查 TypeScript 类型
npm run typecheck

代码检查

# 运行 ESLint
npm run lint

API 覆盖范围

该服务器提供了对这些 IIIF API 文档的访问：

图像 API 3.0：用于图像交付的 Web 服务
展示 API 3.0：结构化的元数据格式
搜索 API 1.0：资源内的内容搜索
认证 API 1.0：访问控制模式

许可证

该项目采用 MIT 许可证 - 查看 LICENSE 文件以获取详细信息。