AGHIST

afa-mcp

ベルン（CH）にある農業史アーカイブ（AfA）（Archives d'histoire rurale AHR / Archives of Rural History ARH）の AGHIST 検索ポータル向け MCP サーバーです。

AGHIST は、農業・食料・環境の歴史に関する検索ポータルです。AfA および国内外のパートナー機関が一般公開しているオンラインリソース（映像、写真、文書資料、目録データ、学術テキスト、ビデオエッセイなど）にアクセスできます。

AGHIST MCP サーバーは、Model Context Protocol（Streamable HTTP）を通じて全文検索と階層検索を提供するため、Claude、ChatGPT、Cursor、Perplexity などの MCP 対応クライアントから AfA の所蔵資料を直接検索できます。

ライブエンドポイント：https://mcp.histoirerurale.ch/mcp

ツール

コレクションごとの現在のヒット件数は list_hierarchy ツールで確認できます。このドキュメントでは、意図的に固定値を記載していません。

search — 汎用全文検索

AfA のすべての所蔵資料（人物、機関、農場、写真・映像コレクション、アーカイブ、デジタル版、出版物、メディア報道）を検索します。任意の階層 ID で絞り込むこともできます。

パラメーター	型	デフォルト	説明
query	str	*	Lucene クエリー文字列です。フレーズは "..."、AND／OR／NOT、ワイルドカードは * と ? を使用します。デフォルトの演算子は AND です。
language	de|fr|it|en	—	タイトル／ハイライトで優先する言語です（フィルターではなく、該当するものがない場合は別の言語にフォールバックします）。
sort	relevance|date|id	relevance	並べ替え方法です。
size	int (1–100)	20	1 ページあたりのヒット数です。
search_after	list	—	前回の応答の next_cursor から取得したカーソルです。
hierarchy	list[str]	—	絞り込みに使用する階層 ID です（OR で結合）。list_hierarchy から取得します。
include_aggregations	bool	false	階層集計を含めます。

戻り値（SearchResponse）：

フィールド	型	説明
total	int	ヒット総数です（size を超える場合も含みます）。
hits	list[SearchHit]	ヒットの一覧です（最大 size 件）。
next_cursor	list | null	次のリクエストの search_after に渡します。null の場合、これ以上ヒットはありません。
aggregations	dict | null	階層バケットです。include_aggregations=true の場合のみ含まれます。

SearchHit のフィールド： id、title、abstract、text（ハイライトの抜粋）、meta、hierarchy（パス）、collection（ラベル）、date（ISO 形式、任意）、is_pdf、document_url（検索ポータルのディープリンク）、original_url（ソース URL）、sort（内部カーソル）。

search_entities — 人物／機関／農場

パラメーター	型	デフォルト	説明
query	str	*	Lucene クエリー文字列です。
entity_type	person|institution|farm|any	any	タイプのフィルターです。company は farm の非推奨エイリアスとして引き続き使用できます。
language	de|fr|it|en	—	優先する言語です。
sort	relevance|date|id	relevance	並べ替え方法です。
size	int (1–100)	20	1 ページあたりのヒット数です。
search_after	list	—	ページネーション用カーソルです。

戻り値： SearchResponse（search を参照）。hits は人物／機関／農場に限定されます。

search_audiovisual — 写真・映像コレクション

パラメーター	型	デフォルト	説明
query	str	*	Lucene クエリー文字列です。
media_type	photos|films	—	photos は写真のみ、films は映像のみを指定します。それ以外の場合は両方が対象です。
language	de|fr|it|en	—	優先する言語です。
sort	relevance|date|id	relevance	並べ替え方法です。
size	int (1–100)	20	1 ページあたりのヒット数です。
search_after	list	—	ページネーション用カーソルです。

戻り値： SearchResponse（search を参照）。hits は写真・映像コレクションに限定されます。

search_edition_hofstetter · search_edition_gillabert_randin · search_edition_bobbett

3つのデジタル版（Mina Hofstetter、Augusta Gillabert-Randin、Elizabeth Bobbett）のいずれかを対象とした全文検索です。

パラメーター	型	デフォルト	説明
query	str	*	Lucene クエリー文字列。
language	de|fr|it|en	—	優先する言語。
sort	relevance|date|id	relevance	並べ替え順。
size	int (1–100)	20	1ページあたりの検索結果数。
search_after	list	—	ページネーションカーソル。

戻り値： SearchResponse（searchを参照）— hitsは該当する版に限定されます。

fetch_document — 全文を含む単一ドキュメントの取得

パラメーター	型	デフォルト	説明
id	str	必須	ドキュメントID。例：AfA_Personen_001_DB9920またはAfA_Edition_003_BobbettE_1933_01。
language	de|fr|it|en	—	優先する言語。

戻り値： 全文を含まない、ドキュメントのメタデータを含む単一のSearchHit。主なフィールド：

• メタデータ：id、title、abstract、meta、hierarchy（コレクションのパス）、collection（ラベル）、date（ISO形式、任意）、is_pdf。
• document_url — 検索ポータル（recherche2.histoirerurale.ch）にあるPDFまたはHTMLファイルへのリンク。
• original_url — ソースポータルへのディープリンク。つまり、スクレーパーがドキュメントを取得したウェブサイトへのリンクです（例：histoirerurale.ch — コレクションによって異なる場合があります）。

IDが見つからない場合はnullです。

list_hierarchy — ヒット数付きの階層バケット

パラメーター	型	デフォルト	説明
query	str	*	任意の全文検索クエリー。
size	int (1–10000)	200	階層エントリーの最大数。
language	de|fr|it|en	—	ラベルの言語。

戻り値（HierarchyResponse）：

フィールド	型	説明
entries	list[HierarchyEntry]	階層エントリー。

HierarchyEntryのフィールド： id（検索ツールのhierarchyパラメーターで使用する階層ID）、count（ヒット数）、label（利用可能な場合は、指定された言語での人が読みやすい名称）。

server_info — バージョンおよびエンドポイント情報

パラメーターはありません。

戻り値（dict）：

フィールド	型	説明
name	str	サーバー名（afa-mcp）。
version	str	Semver。
elasticsearch_url	str	ESバックエンドのアップストリームURL。
languages	list[str]	de、fr、it、en。
sort_orders	list[str]	sortで受け付ける値。
hierarchy_constants	dict	意味が分かる定数（例：PERSONS、EDITION_BOBBETT）から階層ID文字列への対応。

ローカルでの開発

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Streamable HTTP — Default auf 127.0.0.1:8766/mcp
python -m afa_mcp

# Stdio (für lokale CLI-Clients)
python -m afa_mcp --transport stdio

# Tests
pytest -q

# Live-Smoke-Test
python scripts/smoke_test.py

設定（環境変数）

.env.exampleを参照してください。主な項目：

変数	デフォルト	説明
AFA_ES_URL	https://agrargeschichte.pansoft.de:9210/*/_search	Elasticsearchエンドポイント
PUBLIC_BASE_URL	https://mcp.histoirerurale.ch	Discovery用のベースURL
MCP_STATELESS_HTTP	true	サーバー側のセッションを不要にします
MCP_JSON_RESPONSE	true	application/jsonのみを使用するクライアントを受け付けます
MCP_DNS_REBINDING_PROTECTION	true	Host／Originフィルター
CORS_ALLOW_ORIGINS	*	ブラウザーのOriginリスト
AFA_ACCESS_LOG	true	JSON-RPCアクセスログ（メソッド／ツールの統計情報）を有効にします
AFA_ACCESS_LOG_ARGS_MAX	200	ログ行内のargs表現の最大文字数
AFA_ACCESS_LOG_FILE	(stdout)	専用ログファイルの任意のパス

アクセスログ形式

各MCPメソッドは、ロガーafa_mcp.accessに1行を出力します。

2026-06-10 14:30:01,234 INFO afa_mcp.access — method=tools/call tool=search id=42 status=200 size=8543 ms=145 client=160.79.106.37 args={"query":"Bäuerin Emmental","size":3}

一般的な分析には、たとえばawk／grepを使用します。

# Top-10 Tools nach Häufigkeit
grep 'afa_mcp.access' ~/afa-mcp/server.log \
  | grep -oE 'tool=[a-z_]+' | sort | uniq -c | sort -rn | head

# Latenz-Quantile pro Tool
grep 'method=tools/call' ~/afa-mcp/server.log \
  | awk -F'tool=' '{print $2}' | awk '{print $1, $NF}' \
  | sort | awk '{a[$1]++; s[$1]+=$2} END {for (t in a) printf "%-30s n=%4d avg=%dms\n", t, a[t], s[t]/a[t]}'

本番環境（Debian）

sudo bash deploy/install.sh
sudo certbot --nginx -d mcp.histoirerurale.ch
sudo install -m 644 /opt/afa-mcp/deploy/nginx.conf \
    /etc/nginx/sites-available/mcp.histoirerurale.ch
sudo nginx -t && sudo systemctl reload nginx

このスクリプトでは、以下をインストールします。

• システムユーザー afa と /opt/afa-mcp ディレクトリ
• 依存関係を含む Python venv
• systemd ユニット afa-mcp.service（強化済み、ステートレス HTTP）
• OAuth／MCP／エージェントの Discovery、パスリダイレクト、llms.txt に対応した nginx vHost

アップデート用デプロイスクリプト

sudo tee /usr/local/sbin/deploy-afa-mcp > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
sudo -u afa git -C /opt/afa-mcp pull --ff-only
install -m 644 /opt/afa-mcp/deploy/nginx.conf \
    /etc/nginx/sites-available/mcp.histoirerurale.ch
nginx -t && systemctl reload nginx
systemctl restart afa-mcp
systemctl status --no-pager afa-mcp | head -5
EOF
sudo chmod +x /usr/local/sbin/deploy-afa-mcp

実行方法：sudo deploy-afa-mcp。

本番環境（Plesk、root 権限なし）

現在の mcp.histoirerurale.ch のインストール環境のように、root 権限も systemd も利用できない場合、サーバーはユーザー空間で動作し、Plesk の Scheduled Task（Cron、毎分）から起動します。

# einmalig:
mkdir -p ~/afa-mcp && cd ~/afa-mcp
git clone https://github.com/Archiv-fur-Agrargeschichte/AfA-MCP-Server.git .
virtualenv .venv
.venv/bin/pip install -e .
install -m 755 deploy/plesk/start.sh ~/afa-mcp/start.sh

Plesk → ドメイン → Scheduled Tasks → 新しいタスク ~/afa-mcp/start.sh を毎分実行するよう設定します。スクリプトの動作：

• 実行中の PID が存在する場合は、exit 0（何もせず終了）します。
• それ以外の場合は、環境変数を設定し、venv 内で nohup を使って python -m afa_mcp を起動し、PID を ~/afa-mcp/afa-mcp.pid に保存します。

mcp.histoirerurale.ch/httpdocs/.htaccess で Apache mod_proxy を設定します（リポジトリの Apache ドキュメントを参照）。Plesk が TLS と vHost のルーティングを提供します。

アップデート：git -C ~/afa-mcp pull --ff-only を実行した後、古いインスタンスを一度停止します。次の Cron 実行時に、新しいインスタンスが起動します。

統計ページ（/statistik、ライブ生成）

MCP サーバーは /statistik で利用統計を提供します。アクセスのたびにライブ生成されます。前日までのデータは JSON キャッシュ（~/afa-mcp/stats-cache.json）に保存されるため、ログから再集計するのは当日分だけです。Cron ジョブは不要です。

Basic Auth は環境変数で設定します（start.sh 内）。

export AFA_STATS_USER=admin
export AFA_STATS_PASS=DEIN_PASSWORT

両方の値が空の場合、/statistik は保護されずにアクセスできます（開発モード）。

Apache の設定：mcp.histoirerurale.ch/httpdocs/.htaccess に /statistik 用の mod_proxy ルールが必要です（テンプレートは deploy/plesk/mcp-htaccess.example にあります）。

RewriteRule ^statistik$       http://127.0.0.1:8766/statistik       [P,L]
RewriteRule ^statistik/(.*)$  http://127.0.0.1:8766/statistik/$1    [P,L]

Authorization ヘッダーは mod_proxy によって変更されずに転送されます。認証チェックは Python サーバーで行われます（環境変数との hmac.compare_digest）。ページには以下が表示されます。

• 今日 · ツール呼び出し数／セッション数（ログからライブで取得）
• 直近 7 日間と合計（前日までのデータはキャッシュから取得）
• 日ごとの概要と時間別スパークライン
• 上位ツール、AI クライアント（clientInfo.name から取得）
• 24 時間のアクティビティグラフ
• メソッドの内訳（技術的オーバーヘッド）

表示内容は集計データのみです。AFA_ACCESS_LOG_ARGS_MAX=0 が設定されている限り、ユーザーの検索クエリがログや統計に記録されることはありません。

フォールバック／オフラインレンダリング：deploy/plesk/statistik/generate_stats.py は、同じページを静的ファイルとして一度だけ生成します。古いキャッシュの初期化や、サーバーを実行せずにテストする場合に便利です。

Discovery エンドポイント（MCP ディレクトリ向け）

パス	内容
/.well-known/mcp.json	MCP サーバーマニフェスト
/.well-known/agent-card.json	A2A Agent Card
/.well-known/oauth-protected-resource	RFC 9728（認証なしであることを示します）
/llms.txt	LLM／クローラー向けのサイト説明

アーキテクチャ

src/afa_mcp/search.py には Elasticsearch クライアントと、Pydantic ベースのレスポンス解析が含まれています。src/afa_mcp/server.py では、FastMCP ツール、特化型検索ラッパー（エディション、エンティティ、音声・映像）、OAuth／Discovery ルートを備えた ASGI アプリを定義しています。src/afa_mcp/hierarchy.py では階層 ID を一元管理し、ツールコードやテストでマジック文字列を使わずに済むようにしています。

ランディングページ（deploy/）

ビルド手順不要の静的ページを https://mcp.histoirerurale.ch で提供します。

deploy/index.html              nur Markup
deploy/assets/css/style.css    Design-System der Hauptseite histoirerurale.ch/afa
deploy/assets/js/i18n.js       Übersetzungen (de, fr, it, en)
deploy/assets/js/app.js        Sprachwahl und Textersetzung
deploy/assets/img/logo-afa.png Logo der Hauptseite
deploy/assets/fonts/           Merriweather (Überschriften)

色、フォント、コンポーネントはメインサイトの Joomla テンプレート（Cassiopeia と user.css）を引き継いでいます。赤 #a00000、ホバー時 #870000、本文は Helvetica Neue 15px、見出しは赤色の Merriweather、コンテナー幅は 1170px です。

nginx は /assets/ を直接配信します（deploy/nginx.conf と deploy/nginx-http.conf 内の Location）。Plesk ではファイルを httpdocs に配置し、追加ルールなしで配信します。

Quellen

• Website: https://histoirerurale.ch
• Recherche-Frontend: https://www.recherche2.histoirerurale.ch
• Schwesterprojekt: https://github.com/entscheidsuche/entscheidsuche-mcp

Lizenz

MIT