JinDaGe - ra-mcp MCP Details

article

README

🚀 ra - mcp (开发中)

ra - mcp 是一个用于搜索和浏览瑞典国家档案馆（Riksarkivet）转录历史文档的 MCP 服务器和命令行工具，能帮助用户快速定位并查看相关历史资料。

✨ 主要特性

全文搜索：可对数百万份转录的历史文档进行全文搜索。
完整页面转录：能从历史手稿中准确提取文本，提供完整的页面转录内容。
基于参考的文档浏览：可使用官方档案参考代码进行文档浏览。
上下文搜索高亮：快速识别相关内容，提高搜索效率。
高分辨率图像访问：通过 IIIF 访问原始文档扫描件的高分辨率图像。

🚀 快速开始

快速设置

# 搜索任意内容
uv run ra search "Stockholm"

💻 使用示例

基础用法

1. 搜索关键词

查找包含特定单词或短语的文档：

# 基本搜索
uv run ra search "Stockholm"

# 搜索并显示完整页面转录
uv run ra search "trolldom" --context --max-pages 5

# 搜索并显示周围页面以提供上下文
uv run ra search "trolldom" --context --context-padding 1 --max-pages 3

# 搜索时不进行文档分组
uv run ra search "vasa" --context --no-grouping --max-pages 3

选项说明：

--max N：最大搜索结果数（默认：50）
--max-display N：最大显示结果数（默认：20）
--context：显示完整页面转录
--max-pages N：加载上下文的最大页面数（默认：10）
--context-padding N：为上下文在每个匹配项前后包含 N 页（默认：0）
--no-grouping：按页面单独显示，而非按文档分组显示

2. 浏览特定文档

找到感兴趣的文档后，可直接浏览：

# 查看单页
uv run ra browse "SE/RA/123" --page 5

# 查看页面范围
uv run ra browse "SE/RA/123" --pages "1 - 10"

# 查看特定页面并高亮搜索词
uv run ra browse "SE/RA/123" --page "5,7,9" --search-term "Stockholm"

选项说明：

--page 或 --pages：页码（例如："5"、"1 - 10"、"5,7,9"）
--search-term：在文本中高亮显示该词
--max-display N：最大显示页面数（默认：20）

3. 带完整上下文搜索

使用 --context 标志可显示完整页面转录，而非仅显示片段：

# 搜索并显示完整页面转录
uv run ra search "Stockholm" --context --max-pages 5

# 包含周围页面以提供更多上下文
uv run ra search "trolldom" --context --context-padding 2

# 按页面单独显示，而非按文档分组显示
uv run ra search "vasa" --context --no-grouping

高级用法

基本工作流程

搜索关键词：

uv run ra search "Stockholm"

为感兴趣的匹配项获取完整上下文：

uv run ra search "Stockholm" --context --max-pages 3

包含周围页面以提供更多上下文：

uv run ra search "Stockholm" --context --context-padding 1 --max-pages 3

浏览特定文档：

uv run ra browse "SE/RA/123456" --page "10 - 15" --search-term "Stockholm"

复杂操作示例

# 带上下文和周围页面的全面搜索
uv run ra search "trolldom" --context --context-padding 2 --max-pages 8

# 有针对性的文档浏览
uv run ra browse "SE/RA/760264" --pages "1,5,10 - 12" --search-term "trolldom"

# 大量搜索并选择性显示
uv run ra search "trolldom" --max 100 --max-display 30

📚 详细文档

输出特性

🔍 搜索结果

运行搜索时，结果将呈现以下信息：

文档分组：将相关页面分组显示，便于查看上下文。
机构与日期：显示档案位置和文档日期。
页码：显示包含搜索词的特定页面。
高亮片段：预览文本中突出显示关键词。
浏览命令：提供可直接运行的命令，用于深入探索。

示例输出：

文档: SE/RA/12345 - Stockholms stads tänkeböcker (1520 - 1550)
机构: Stockholms stadsarkiv | 日期: 1545
├─ 第 42 页: "...angående **Stockholm** rådstuga och dess underhåll..."
├─ 第 98 页: "...borgmästaren i **Stockholm** beslutade att..."
└─ 第 156 页: "...handlare från **Stockholm** begärde tillstånd..."

浏览命令:
  uv run ra browse "SE/RA/12345" --page 42 --search-term "Stockholm"
  uv run ra browse "SE/RA/12345" --pages "42,98,156" --search-term "Stockholm"

📄 完整页面显示

使用 --context 标志可获得完整的页面转录，具有以下特点：

全文转录：从 ALTO XML 中获取完整的页面内容。
关键词高亮：搜索词以黄色高亮显示。
丰富元数据：显示文档标题、日期和档案层次结构。
直接访问链接：提供图像、XML 和交互式查看器的快速链接。
上下文指示：使用 --context-padding 时，清晰标记周围页面。

示例输出：

═══ SE/RA/12345 - 第 42 页 ═══
标题: Stockholms stads tänkeböcker
日期: 1545 - 03 - 15 | 机构: Stockholms stadsarkiv

Anno domini 1545 den 15 martii blef föredraget angående 🟡Stockholm🟡
rådstuga och dess underhåll. Borgmästaren förklarade att byggnaden
behöfde reparationer och att medel måste anskaffas för detta ändamål.
Flera borgare från 🟡Stockholm🟡 stad deltog i diskussionen om hur
kostnaderna skulle fördelas...

链接:
📄 ALTO XML: https://sok.riksarkivet.se/dokument/alto/SE_RA_12345_042.xml
🖼️  图像: https://lbiiif.riksarkivet.se/arkiv/SE_RA_12345_042.jpg
🔍 图像查看: https://sok.riksarkivet.se/bildvisning/SE_RA_12345#042

🔗 可用资源

每个结果提供以下资源的直接访问： | 属性 | 详情 | |------|------| | ALTO XML | 具有精确定位的结构化转录数据，用于文本分析和数据提取。 | | IIIF 图像 | 支持缩放/裁剪的高分辨率文档扫描件，用于视觉检查和引用。 | | Bildvisning | 带有搜索高亮的交互式网页查看器，用于在线浏览和共享。 | | 集合 | 文档系列的 IIIF 元数据，用于了解文档上下文。 |

🔧 技术细节

瑞典国家档案馆 API 与数据源

该工具集成了多个瑞典国家档案馆 API，以全面访问历史文档：

当前集成

搜索 API：对转录材料进行全文搜索的主要端点（文档）。
IIIF 集合：通过 IIIF 标准访问数字化文档集合（文档）。
ALTO XML：具有精确定位数据的结构化文本转录。
IIIF 图像：具有缩放和裁剪功能的高分辨率文档图像。
Bildvisning：带有搜索高亮的交互式文档查看器。
[OAI - PMH](https://oai - pmh.riksarkivet.se/OAI)：用于档案记录和参考的元数据采集（[文档](https://github.com/Riksarkivet/dataplattform/wiki/OAI - PMH)）。

额外资源

瑞典国家档案馆数据平台维基为构建额外的 MCP 集成提供了全面的文档。

实验性功能

Förvaltningshistorik：语义搜索界面（正在评估中）。
AI - 瑞典国家档案馆 HTRflow：手写文本识别管道（PyPI 包）。

当前 MCP 服务器实现

此服务器通过多个 API 提供对瑞典国家档案馆（Riksarkivet）的访问：
    基于搜索的工作流程（从此处开始）：
    - search_records：按关键词搜索内容（例如，"coffee"、"medical records"）
    - get_collection_info：探索集合中可用的内容
    - get_all_manifests_from_pid：从集合中获取所有图像批次
    - get_manifest_info：获取特定图像批次的详细信息
    - get_manifest_image：从批次中下载特定图像
    - get_all_images_from_pid：从集合中下载所有图像
    URL 构建工具：
    - build_image_url：使用自定义参数构建 IIIF 图像 URL
    - get_image_urls_from_manifest：从图像批次中获取所有 URL
    - get_image_urls_from_pid：从集合中获取所有 URL
    典型工作流程：
    1. search_records("你的关键词") → 查找 PID
    2. get_collection_info(pid) → 查看可用内容
    3. get_manifest_info(manifest_id) → 探索特定图像批次
    4. get_manifest_image(manifest_id, image_index) → 下载特定图像
    示例 PID: LmOmKigRrH6xqG3GjpvwY3

📄 许可证

文档中未提及相关信息。

🔧 故障排除

常见问题

未找到结果：尝试使用更宽泛的搜索词或检查拼写。
页面未加载：某些页面可能没有可用的转录内容。
网络超时：工具包含重试逻辑，但网络连接过慢可能会导致超时。

获取帮助

uv run ra --help
uv run ra search --help
uv run ra browse --help
uv run ra serve --help

MCP 服务器开发

运行 MCP 服务器

# 安装依赖
uv sync && uv pip install -e .

# 运行主 MCP 服务器（标准输入输出）
cd src/ra_mcp && python server.py

# 在端口 8000 上使用 SSE/HTTP 传输运行
cd src/ra_mcp && python server.py --http

使用 MCP 检查器进行测试

使用 MCP 检查器对 MCP 服务器进行测试和调试：

# 交互式测试服务器
npx @modelcontextprotocol/inspector uv run python src/ra_mcp/server.py

MCP 检查器提供了一个 Web 界面，用于在开发期间测试服务器工具、资源和提示。

使用 Dagger 进行构建和发布

该项目使用 Dagger 进行容器化构建并发布到 Docker 注册表。预构建的镜像可在 [Docker Hub](https://hub.docker.com/r/riksarkivet/ra - mcp) 上获取。

前提条件

安装 Dagger CLI。
拥有 Docker 注册表凭证（用于发布）。

可用命令

本地构建：

dagger call build

运行测试：

dagger call test

构建并发布到 Docker 注册表：

# 设置环境变量
export DOCKER_USERNAME="你的用户名"
export DOCKER_PASSWORD="你的密码"

# 构建并发布
dagger call publish \
  --docker - username=env:DOCKER_USERNAME \
  --docker - password=env:DOCKER_PASSWORD \
  --image - repository="riksarkivet/ra - mcp" \
  --tag="latest" \
  --source=.

可用的 Dagger 函数

build：使用 Dockerfile 创建生产就绪的容器镜像。
test：使用 pytest 运行测试套件并进行覆盖率报告。
publish：构建并将容器镜像发布到注册表，并进行身份验证。
build - local：使用自定义环境变量和注册表设置进行构建。

Dagger 配置位于 .dagger/main.go，为项目提供了完整的 CI/CD 管道。

ra-mcp