Ra MCP

🚀 ra - mcp (WIP)

このプロジェクトは、スウェーデン国立公文書館（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 - 各ヒットの前後に含めるページ数（デフォルト: 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

🔧 技術詳細

RiksarkivetのAPIとデータソース

このツールは、複数のRiksarkivet APIと統合されており、歴史文書への包括的なアクセスを提供します。

現在の統合

• Search API - 転写された資料を対象とする全文検索の主要エンドポイント（[ドキュメント](https://github.com/Riksarkivet/dataplattform/wiki/Search - API)）
• IIIF Collections - IIIF標準を介したデジタル化された文書コレクションへのアクセス（ドキュメント）
• ALTO XML - 正確な位置情報を持つ構造化されたテキスト転写
• IIIF Images - ズームとクロップが可能な高解像度の文書画像
• Bildvisning - 検索ハイライト付きのインタラクティブな文書ビューア
• [OAI - PMH](https://oai - pmh.riksarkivet.se/OAI) - 公文書館のレコードと参照情報のメタデータ収集（[ドキュメント](https://github.com/Riksarkivet/dataplattform/wiki/OAI - PMH)）

追加リソース

Riksarkivet Data Platform Wiki は、追加のMCP統合を構築するための包括的なドキュメントを提供しています。

実験的な機能

• Förvaltningshistorik - セマンティック検索インターフェイス（評価中）
• AI - Riksarkivet HTRflow - 手書きテキスト認識パイプライン（PyPIパッケージ）

📦 インストール

MCPサーバーを実行する

# 依存関係をインストール
uv sync && uv pip install -e .

# メインのMCPサーバーを実行（stdio）
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を使用してビルドおよび公開する

このプロジェクトは、コンテナ化されたビルドとDockerレジストリへの公開にDaggerを使用しています。事前にビルドされたイメージは [Docker Hub](https://hub.docker.com/r/riksarkivet/ra - mcp) で利用できます。

前提条件

• Dagger CLI がインストールされていること
• Dockerレジストリの資格情報（公開する場合）

利用可能なコマンド

ローカルでビルドする:

dagger call build

テストを実行する:

dagger call test

Dockerレジストリにビルドして公開する:

# 環境変数を設定
export DOCKER_USERNAME="your - username"
export DOCKER_PASSWORD="your - 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パイプラインを提供しています。

📄 出力機能

🔍 検索結果

検索を実行すると、結果は以下のように表示されます。

• 文書のグルーピング：関連するページがコンテキストを考慮してグループ化されます。
• 機関と日付：公文書館の所在地と文書の日付が表示されます。
• ページ番号：検索用語が含まれる特定のページ番号が表示されます。
• ハイライト付きのスニペット：キーワードが強調表示されたプレビューテキストが表示されます。
• 閲覧コマンド：より深く探索するための実行可能なコマンドが表示されます。

出力例:

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

Browse commands:
  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 - Page 42 ═══
Title: Stockholms stads tänkeböcker
Date: 1545 - 03 - 15 | Institution: 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...

Links:
📄 ALTO XML: https://sok.riksarkivet.se/dokument/alto/SE_RA_12345_042.xml
🖼️  Image: https://lbiiif.riksarkivet.se/arkiv/SE_RA_12345_042.jpg
🔍 Bildvisning: https://sok.riksarkivet.se/bildvisning/SE_RA_12345#042

🔗 利用可能なリソース

各結果には、以下のリソースへの直接アクセスが提供されます。

🛠️ トラブルシューティング

一般的な問題

1. 結果が見つからない場合：より広範な検索用語を試したり、スペルを確認してください。
2. ページが読み込まれない場合：一部のページには転写が利用できない場合があります。
3. ネットワークタイムアウトの場合：ツールにはリトライロジックが含まれていますが、非常に低速な接続ではタイムアウトする可能性があります。

ヘルプを得るには

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

📜 現在の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("your keywords") → PIDを見つける
    2. get_collection_info(pid) → 何が利用可能かを確認する
    3. get_manifest_info(manifest_id) → 特定の画像バッチを探索する
    4. get_manifest_image(manifest_id, image_index) → 特定の画像をダウンロードする
    例のPID: LmOmKigRrH6xqG3GjpvwY3