AfA MCP Server
Archiv-fur-Agrargeschichte/AfA-MCP-Server
Busca em acervo histórico de história agrária via MCP
Ver no GitHubServidor MCP que fornece acesso a 22 mil documentos do Archiv für Agrargeschichte (história agrária rural) através de busca por texto completo e pesquisa hierárquica. Integra-se com clientes MCP como Claude, ChatGPT e Cursor para consultar acervos históricos, édições especiais, fotos e filmes via protocolo HTTP streamable.
Instalação
npx convez-ai Archiv-fur-Agrargeschichte/AfA-MCP-Server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pesquisa acadêmica em história agrária e rural
- Busca de documentos históricos, fotos e filmes de arquivo
- Integração com IA para análise de textos históricos
- Consulta de pessoas, instituições e fazendas históricas
Veredito

Servidor MCP bem estruturado para domínio especializado (história agrária). Oferece múltiplos endpoints de busca (texto, entidades, audiovisual, edições) com logging detalhado e configuração clara. Útil para pesquisadores e instituições de arquivo, mas escopo limitado a base de dados específica.
README
A tradução para o português deste README ainda está na fila.
afa-mcp
MCP-Server für das Archiv für Agrargeschichte (AfA / Archives d'histoire rurale / Archives of Rural History). Stellt Volltext-Suche und Hierarchie-Recherche über das Model Context Protocol (Streamable HTTP) bereit, sodass MCP-fähige Clients wie Claude, ChatGPT, Cursor oder Perplexity direkt in den AfA-Beständen suchen können.
Live-Endpunkt: https://mcp.histoirerurale.ch/mcp
Werkzeuge
| Tool | Beschreibung |
|---|---|
search | Volltext-Suche, optional mit hierarchy-Filter |
search_entities | Personen / Institutionen / Betriebe (Parameter entity_type) |
search_audiovisual | Foto- und Film-Bestände (optional photos / films) |
search_edition_hofstetter | Edition Mina Hofstetter (67 Dokumente) |
search_edition_gillabert_randin | Edition Augusta Gillabert-Randin (132 Dokumente) |
search_edition_bobbett | Edition Elizabeth Bobbett (271 Dokumente) |
fetch_document | Einzelnes Dokument inkl. Volltext anhand der ID |
list_hierarchy | Hierarchie-Buckets mit Trefferzahlen |
server_info | Versions- und Endpunkt-Information |
Hierarchie-IDs
| ID | Sammlung | Doks |
|---|---|---|
AfA_Personen | Personen | 15 824 |
AfA_Organisationen | Institutionen | 1 206 |
AfA_Betriebe | Betriebe | 1 |
AfA_Archiv | Archivbestände | 212 |
AfA_FotoFilm | Audio-/visuelle Quellen | 3 197 |
AfA_FotoFilm_001 | — Fotos | 1 960 |
AfA_FotoFilm_002 | — Filme | 1 237 |
AfA_Edition_001 | Edition Mina Hofstetter | 67 |
AfA_Edition_002 | Edition Augusta Gillabert-Randin | 132 |
AfA_Edition_003 | Edition Elizabeth Bobbett | 271 |
AfA_Publikationen | Publikationen | 178 |
AfA_Berichte | Medienberichte | 72 |
AfA_Weitere | Weitere Quellen | 36 |
Lokal entwickeln
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
Konfiguration (Env-Vars)
Siehe .env.example. Die wichtigsten:
| Variable | Default | Bedeutung |
|---|---|---|
AFA_ES_URL | https://agrargeschichte.pansoft.de:9210/*/_search | Elasticsearch-Endpoint |
PUBLIC_BASE_URL | https://mcp.histoirerurale.ch | Basis-URL für Discovery |
MCP_STATELESS_HTTP | true | Keine Server-seitige Session-Pflicht |
MCP_JSON_RESPONSE | true | Akzeptiert Clients mit nur application/json |
MCP_DNS_REBINDING_PROTECTION | true | Host/Origin-Filter |
CORS_ALLOW_ORIGINS | * | Browser-Origin-Liste |
AFA_ACCESS_LOG | true | JSON-RPC Access-Log (Methoden-/Tool-Statistik) aktiv |
AFA_ACCESS_LOG_ARGS_MAX | 200 | Max. Zeichen pro args-Repr in der Logzeile |
AFA_ACCESS_LOG_FILE | (stdout) | Optionaler Pfad für eine dedizierte Logdatei |
Access-Log-Format
Jede MCP-Methode erzeugt eine Zeile im Logger afa_mcp.access:
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}
Auswertung typisch via awk / grep, etwa:
# 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]}'
Produktion (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
Das Skript installiert:
- Systemnutzer
afa+/opt/afa-mcp-Verzeichnis - Python-venv mit den Abhängigkeiten
- systemd-Unit
afa-mcp.service(gehärtet, Stateless-HTTP) - nginx-vHost mit OAuth-/MCP-/Agent-Discovery, Pfad-Redirects, llms.txt
Deploy-Skript für Updates
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
Aufruf: sudo deploy-afa-mcp.
Produktion (Plesk, ohne root)
Falls — wie bei der aktuellen Installation auf mcp.histoirerurale.ch —
kein root und kein systemd zur Verfügung steht, läuft der Server im
Userspace, gestartet von einer Plesk Scheduled Task (Cron, alle Minute):
# 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 → Domain → Scheduled Tasks → neuer Task ~/afa-mcp/start.sh,
jede Minute. Skript-Verhalten:
- Existiert ein laufender PID → exit 0 (No-op).
- Sonst: env setzen,
python -m afa_mcpim venv vianohupstarten, PID in~/afa-mcp/afa-mcp.pidablegen.
Apache mod_proxy davorhängen via mcp.histoirerurale.ch/httpdocs/.htaccess
(siehe Apache-Doku des Repos), Plesk liefert TLS und das vHost-Routing.
Updates: git -C ~/afa-mcp pull --ff-only, anschließend einmal die alte
Instanz killen — der Cron startet die neue beim nächsten Tick neu.
Statistik-Seite (/statistik, Live-Generierung)
Der MCP-Server liefert unter /statistik selbst eine Nutzungsstatistik aus —
live bei jedem Aufruf generiert. Vortage werden in einem JSON-Cache
(~/afa-mcp/stats-cache.json) fixiert, damit nur der aktuelle Tag aus dem
Log neu aggregiert werden muss. Kein Cron-Job notwendig.
Basic Auth via Env-Variablen (in start.sh):
export AFA_STATS_USER=admin
export AFA_STATS_PASS=DEIN_PASSWORT
Sind beide leer, ist /statistik ungeschützt zugänglich (Dev-Modus).
Apache-Setup: mcp.histoirerurale.ch/httpdocs/.htaccess braucht eine
mod_proxy-Regel für /statistik (Vorlage in
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]
Der Authorization-Header wird per mod_proxy unverändert durchgereicht; die
Auth-Prüfung passiert im Python-Server (hmac.compare_digest gegen die
Env-Variablen). Die Seite zeigt:
- heute · Tool-Aufrufe / Sessions (live aus dem Log)
- letzte 7 Tage und gesamt (Vortage aus Cache)
- Tagesübersicht mit Stunden-Sparkline pro Tag
- Top-Tools, KI-Clients (aus
clientInfo.name) - 24-Stunden-Aktivitätsgrafik
- Methoden-Verteilung (technischer Overhead)
Inhalte sind reine Aggregate — solange AFA_ACCESS_LOG_ARGS_MAX=0 gesetzt
ist, gelangen keine Nutzer-Suchanfragen ins Log oder die Statistik.
Fallback / Offline-Rendering: deploy/plesk/statistik/generate_stats.py
schreibt dieselbe Seite einmalig als statische Datei — nützlich für ältere
Caches initialisieren oder Tests ohne laufenden Server.
Discovery-Endpunkte (für MCP-Verzeichnisse)
| Pfad | Inhalt |
|---|---|
/.well-known/mcp.json | MCP-Server-Manifest |
/.well-known/agent-card.json | A2A Agent Card |
/.well-known/oauth-protected-resource | RFC 9728 (signalisiert: keine Auth) |
/llms.txt | LLM-/Crawler-freundliche Site-Beschreibung |
Architektur
src/afa_mcp/search.py enthält den Elasticsearch-Client und Pydantic-basiertes
Antwort-Parsing. src/afa_mcp/server.py definiert die FastMCP-Tools, die
spezialisierten Such-Wrapper (Editionen, Entitäten, Audio-Visuell) und die
ASGI-App mit OAuth-/Discovery-Routen. src/afa_mcp/hierarchy.py zentralisiert
die Hierarchie-IDs, damit Tool-Code und Tests nicht mit Magic-Strings arbeiten
müssen.
Quellen
- Website: https://histoirerurale.ch
- Recherche-Frontend: https://www.recherche2.histoirerurale.ch
- Schwesterprojekt: https://github.com/entscheidsuche/entscheidsuche-mcp
Lizenz
MIT