convez.ai
MCP ServerBusca & PesquisaIntermediário
Archiv-fur-Agrargeschichte

AfA MCP Server

Archiv-fur-Agrargeschichte/AfA-MCP-Server

Busca em acervo histórico de história agrária via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-Server

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
25%
Último commit
há 3 meses
Versão
—
Issues abertas
2
Contribuidores
1

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

ToolBeschreibung
searchVolltext-Suche, optional mit hierarchy-Filter
search_entitiesPersonen / Institutionen / Betriebe (Parameter entity_type)
search_audiovisualFoto- und Film-Bestände (optional photos / films)
search_edition_hofstetterEdition Mina Hofstetter (67 Dokumente)
search_edition_gillabert_randinEdition Augusta Gillabert-Randin (132 Dokumente)
search_edition_bobbettEdition Elizabeth Bobbett (271 Dokumente)
fetch_documentEinzelnes Dokument inkl. Volltext anhand der ID
list_hierarchyHierarchie-Buckets mit Trefferzahlen
server_infoVersions- und Endpunkt-Information

Hierarchie-IDs

IDSammlungDoks
AfA_PersonenPersonen15 824
AfA_OrganisationenInstitutionen1 206
AfA_BetriebeBetriebe1
AfA_ArchivArchivbestände212
AfA_FotoFilmAudio-/visuelle Quellen3 197
AfA_FotoFilm_001— Fotos1 960
AfA_FotoFilm_002— Filme1 237
AfA_Edition_001Edition Mina Hofstetter67
AfA_Edition_002Edition Augusta Gillabert-Randin132
AfA_Edition_003Edition Elizabeth Bobbett271
AfA_PublikationenPublikationen178
AfA_BerichteMedienberichte72
AfA_WeitereWeitere Quellen36

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:

VariableDefaultBedeutung
AFA_ES_URLhttps://agrargeschichte.pansoft.de:9210/*/_searchElasticsearch-Endpoint
PUBLIC_BASE_URLhttps://mcp.histoirerurale.chBasis-URL für Discovery
MCP_STATELESS_HTTPtrueKeine Server-seitige Session-Pflicht
MCP_JSON_RESPONSEtrueAkzeptiert Clients mit nur application/json
MCP_DNS_REBINDING_PROTECTIONtrueHost/Origin-Filter
CORS_ALLOW_ORIGINS*Browser-Origin-Liste
AFA_ACCESS_LOGtrueJSON-RPC Access-Log (Methoden-/Tool-Statistik) aktiv
AFA_ACCESS_LOG_ARGS_MAX200Max. 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_mcp im venv via nohup starten, PID in ~/afa-mcp/afa-mcp.pid ablegen.

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)

PfadInhalt
/.well-known/mcp.jsonMCP-Server-Manifest
/.well-known/agent-card.jsonA2A Agent Card
/.well-known/oauth-protected-resourceRFC 9728 (signalisiert: keine Auth)
/llms.txtLLM-/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

Lizenz

MIT

Ver o original no GitHub

Bom para

Relacionados