Ra MCP

🚀 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

高級用法

基本工作流程

1. 搜索關鍵詞：

uv run ra search "Stockholm"

2. 為感興趣的匹配項獲取完整上下文：

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

3. 包含周圍頁面以提供更多上下文：

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

4. 瀏覽特定文檔：

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

🔗 可用資源

每個結果提供以下資源的直接訪問：

🔧 技術細節

瑞典國家檔案館 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

📄 許可證

文檔中未提及相關信息。

🔧 故障排除

常見問題

1. 未找到結果：嘗試使用更寬泛的搜索詞或檢查拼寫。
2. 頁面未加載：某些頁面可能沒有可用的轉錄內容。
3. 網絡超時：工具包含重試邏輯，但網絡連接過慢可能會導致超時。

獲取幫助

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 管道。