Skip to main content
Glama
bbaw-dse-mcp

bbaw-dse-mcp

by telota

bbaw-dse-mcp

An MCP server for dialogical, exploratory access to digital scholarly editions.

DHd2026 Poster: Agenten im Dienst der Edition

Overview

Instead of complex search forms and navigation structures, this MCP server enables natural-language conversation with digital scholarly editions. An AI agent translates questions like "Who was important for Schleiermacher in 1810?" into structured database queries — and maintains conversational context across follow-up questions.

The current server composes edition backends and reusable external research services into a single MCP endpoint using FastMCP:

Service

Prefix

Backend

Content

schleiermacher digital

sd_

Public TEI + native search/register pages

Letters, diaries, lectures, chronology, glossary

Praktiken der Monarchie

mop_

Public TEI/HTML + GeoJSON/Zotero

Documents on Prussian monarchy and governance

Jean Paul Briefwechsel

jp_

HTTPS connector

Letters, Umfeldbriefe, topics, correspondence networks

edition humboldt digital

ehd_

Public TEI API v2.3 + native web modules

Letters, travel journals, thematic documents, research, chronology, registers

correspSearch

cs_

REST API

Cross-edition correspondence network search

Authority services

authority_

Lobid GND, GeoNames, Wikidata APIs

Reusable identifier and entity lookup

Related MCP server: WLO MCP Server

Available Tools

The composed server exposes these shared and edition-native tool surfaces:

Surface

Description

Shared

Cross-edition access, failure-isolated search, correspondence statistics, capabilities, and identity comparison

Schleiermacher Digital (sd_*)

Bounded advanced search, glossary, passages, diaries, chronology, thesaurus, and Bible references

Praktiken der Monarchie (mop_*)

Passages, research literature, biogrammes, adjutant journals, residential topography, court calendar, organigrams, thematic dossiers

Jean Paul Briefwechsel (jp_*)

Native full-text and letter-metadata filters, controlled topics, and curated correspondence networks

edition humboldt digital (ehd_*)

TEI catalogs, native search, correspondent/year filters, thematic documents, complete passages, chronology and place-event links

correspSearch (cs_*)

Cross-edition correspondence metadata, normalized relations, typed networks, and edition discovery

Authority services (authority_*)

GND, GeoNames, and Wikidata lookup

The full signatures and usage boundaries are documented in docs/TOOLS.md; the source-code-derived edition-module inventory is in docs/EDITION_MODULES.md.

Every successful sd_*, mop_*, jp_*, ehd_*, or cs_* response, including shared calls that resolve edition data, carries MCP _meta.provenance with consulted sources, configured backends, datasets, and UTC retrieval time. Humboldt preserves the actual release asserted in returned TEI/canonical resource URLs (for example v12); HTML searches without release evidence report release_status="unknown". The other connectors report data_release=null where no coherent source release exists. API/software versions are never substituted for data releases.

The capability tool, get_capabilities(check_health=False), reports SD, MoP, JP, Humboldt, correspSearch, Lobid GND, Wikidata, and GeoNames without exposing credential values. It declares datasets, modules, filters, releases/interface versions, licenses, and explicit source limitations. Its default is network-free; check_health=True runs isolated read-only probes for configured providers. A missing GeoNames username is visible as configured=false, available=false, and status="missing_credentials".

search_documents(...) and search_entities(...) return typed pages with results, offset continuation, per-source counts, failures and filter handling, rather than bare lists. Both accept strict_filters=False; strict mode rejects an affected source rather than silently ignoring unsupported filters. Document search defaults to include_commentary=None (no explicit commentary filter). Even when every selected backend fails, the structured failure envelope is returned. total_count is exact only when total_known=true; otherwise it is an explicit lower bound. results_omitted, extraction_complete, and text TextExtent.truncated describe different limits; previews carry executable complete-content routes. SD uses stable source order for repeatable pages. This is a clean response-contract cutover, not a compatibility shim; see shared contracts and signatures.

get_entity("sd:…" | "mop:…" | "jp:…" | "ehd:…", include_mentions=True) now reads the editions' public register pages without a database account. Edition-specific parsers preserve native metadata, digital text/commentary mentions, correspondence/authorship, print references and relationships where exposed. mentions.references is one stable, globally paginated row stream; mentions.sections retains the full section inventory on every page. total_count counts rendered rows, not distinct documents or corpus occurrences. Absent sections and unresolved native destinations remain explicit. Published inventories are authoritative within their declared source scope: corpus_complete=true means complete extraction, even when the returned window has more rows. Unavailable surfaces and actual extraction failures remain incomplete; published-reference counts are not historical corpus totals. Shared search, normalized relations and SD/MoP specialist tools now also use public sources, without a database account or hidden database fallback.

Public retrieval covers every register published in the four editions: SD's four classic registers plus glossary, Bible and aesthetics thesaurus; MoP's six classic registers plus bibliography; JP's person/place/two work registers plus topics and correspondence circles; Humboldt's person/place/ institution/plant/glossary/bibliography/sigle registers. Its drawings gallery has no published entity IDs and is paged by ehd_list_drawings. Native types and edition namespaces remain intact. Use public specialist discovery for SD's extra registers; the manifest separates searchable entity_types from entity_retrieval_types.

get_resource_relations(ref=...) exposes one common, evidence-backed relation model for Schleiermacher, MoP, Jean Paul, and Humboldt document resources, including the explicit Jean-Paul module refs jp:topic:<id> and jp:network:<id>. Its resource kinds and predicates are closed vocabularies, and every predicate validates the allowed subject and object kinds. Relations retain provider-scoped references and external identifiers; the server does not silently merge resources into a cross-edition sameAs identity. The older get_relations(...) remains available for its established edition-specific aggregate response shapes.

compare_resource_identities(...) performs that reconciliation explicitly. It normalizes GND, GeoNames, Wikidata, VIAF, and source URLs, retaining field-level evidence, conflicts, and partial failures. Only an exact authority identifier or explicitly equal source URI confirms same_as; equal labels produce an unconfirmed candidate and never merge records.

Schleiermacher correspondence relations are atomic sender-to-recipient edges backed by individual letters. MoP relation extraction reads the complete register-mention set and distinguishes explicit Hofkalendarium participants from mere mentions. The query-oriented correspSearch equivalent, cs_search_correspondence_relations(...), retains every sent/received action with all participants, places, and date assertions from each fetched record.

Breaking correspSearch response migration: cs_search_correspondences records now expose correspondence data only through letters[].actions[]. Select actions by type (sent or received) and read every participants, places and dates entry. The singular sender, receiver, send_place, receive_place and letter-level date* fields have been removed, without aliases or fallback synthesis. title is display text, not structured evidence. Tool names and inputs are unchanged; see the migration mapping.

correspSearch metadata searches may start from any supported substantive filter; the API defaults to ten records but accepts bounded page sizes up to 1,000. Normalized relation responses deliberately process one upstream page and expose further pages through upstream_continuations.

Jean Paul's native jp_search_documents_advanced and jp_filter_letters surfaces expose all three letter corpora with exact totals, stable offset continuation, concrete source collections, and original citation routes. The first adds full-text, lemma, sender/receiver, year, and counted-facet access; the second combines correspondence metadata including co-senders, co-recipients, topics, joint letters, and year bounds. Both fail explicitly on unexpected source markup. Shared JP work lookup also covers the separate werke-jp register and retains that collection in search and detail results.

Humboldt uses the conservative ehd namespace (edition humboldt digital). search_documents(..., editions=["ehd"]), get_document("ehd:H1055854"), search_entities(..., editions=["ehd"]), and get_entity("ehd:H0012069") use the same shared adapter/identity surface as the other editions. Native tools expose exact local TEI-catalog pages and the site's search/filter pages; ehd_get_document_passages reads complete blocks rather than truncating text. Use ehd_get_chronology_entry("H0005699") for first-party events and ehd_get_place_chronology("H0000531") for source-supplied geographic links. The API's 2.3 interface is distinct from edition v12 (8 June 2026) and GitHub/Zenodo dataset release identifiers. Entity retrieval primarily uses public HTML, supplemented by the unversioned ID API where needed because versioned register XML is defective upstream. Measures such as reaumur remain public-TEI-retrievable, with references explicitly not_exposed; production HTML publication has not been established. Plants use publisher-local selectors (ehd:plant:Abies), bibliography uses group-qualified Zotero keys (ehd:zotero-667230-R7AXEBAP), and ehd_list_drawings preserves image crops and source locators without inventing drawing IDs. Shared date-range/commentary search filters, aggregate networks, and inferred coordinate or topic graphs are not advertised. See docs/TOOLS.md for endpoint research, implementation choices, and exact native signatures.

MoP's public full-text search covers Druck, Adjutantenjournale and Hofkalendarium; semantic letter also includes the published letters in Druck. Private Korrespondenz/Instruktionen selectors and separate instruction classification are not established by the public search and are reported as unsupported, not guessed from titles or returned as false zeros. mop_get_document_passages provides division/page-filtered text blocks; shared get_document now returns complete public text or TEI. The current source-gap and acceptance records are in docs/DATA_SOURCE_GAPS.md and docs/MOP_ACCEPTANCE.md.

Installation

# Clone the repository
git clone https://github.com/telota/bbaw-dse-mcp.git
cd bbaw-dse-mcp

# Install with uv (recommended)
uv sync

Requires Python 3.11+.

Public document retrieval

get_document uses the editions' public TEI exports for sd:, mop:, jp:, and ehd: references, without database credentials. The internal HTTP receiver shares bounded downloads and connection handling; edition adapters retain their own identifiers, catalogs, parsing, and namespaces.

Authority normalization and TEI correspondence-action parsing are shared primitives, not parallel edition implementations. Original URI/XML evidence, multiple participants and uncertain dates are retained; edition adapters still choose their own metadata precedence and resolve their own local IDs. Distinct authority IDs are not silently collapsed, and VIAF/GeoNames are not substituted for GND.

MoP enables optional normal TELOTA Gatekeeper verification: wait for the issued challenge, submit it to /verify-request, retain the cookie, and retry once. No browser, forged token, database fallback, or alternate snapshot is used. Downloads exceeding 16 MiB fail explicitly; XML and document text are not silently truncated. Facsimile-only documents report availability rather than automatically generating OCR.

This public-only cutover also covers searches, registers, relations and specialists. Biograms retain family, offices, education and awards; journals retain dated sessions and explicit author/place identities; organigrams retain hierarchies and dated holders. Calendar search uses counted native pages plus local exact-day/text filtering. Catalog-declared calendar UUIDs use public HTML; their unavailable TEI view is an explicit publisher gap.

SD person networks use person-scoped native discovery and letter TEI. Native whole-corpus correspondent statistics require the publisher's bulk CMIF, currently unavailable (HTTP 504); this is an error, not an empty network. get_correspondence_statistics(editions=["sd", "jp", "ehd"]) provides an explicit correspSearch-backed alternative: live indexed-record counts, or sent/received counts and bounded partner rankings with ref="sd:S0003676" or person_gnd. Exact counts remain separate from incomplete partner analysis and corpus coverage. JP includes print-only An-Briefe metadata. MoP returns unsupported with null counts because no source association has been verified; native tools stay intact. AB topography uses the five publisher-linked GeoJSON datasets; literature uses the live public Zotero group, not a fabricated dated snapshot. Journal text queries hydrate only their native result window; person/place-only searches without text/date/monarch narrowing can require a bounded, cold-cache scan.

The obsolete private eXist clients, database/query tools, SD legacy parsers and exclusive database settings have been removed. Existing .env files must remove the old SD/AB database URLs, collection paths, usernames/passwords and SD_LOCAL keys. Use .env.example for the supported public configuration; the GeoNames account remains an external-service setting. No database compatibility aliases or hidden fallback are retained.

Configuration

Configuration uses environment variables (prefix EDITIONS_). Create a .env file:

# Schleiermacher Digital public research interfaces; no database account
EDITIONS_SD_PUBLIC_URL=https://schleiermacher-digital.de

# Praktiken der Monarchie public research interfaces; no database account
EDITIONS_AB_PUBLIC_URL=https://actaborussica.bbaw.de
EDITIONS_AB_GATEKEEPER_ENABLED=true

# correspSearch API (no auth required)
EDITIONS_CS_API_URL=https://correspsearch.net/api/v2.0
EDITIONS_CS_SPARQL_URL=https://lod.academy/correspsearch/data/main/sparql

# Required for the GeoNames lookup tools; capability discovery works without it
EDITIONS_GEONAMES_USERNAME=

Usage

Running the server

uv run bbaw-dse-mcp

The default transport remains stdio, including for Claude Desktop. The server now uses FastMCP 4.0.11+ and the official MCP Python SDK 2.3.0+, which natively implement the published MCP 2026-07-28 specification. Legacy clients still use their initialize handshake on the same server; modern clients do not initialize or create protocol sessions.

Streamable HTTP deployment

uv run bbaw-dse-mcp --transport http --host 127.0.0.1 --port 8000
# Equivalent transport spelling: --transport streamable-http

The endpoint is /mcp (--path overrides it). Host and Origin protection is enabled even when binding to a non-loopback address. Behind a TLS reverse proxy, explicitly allow the externally visible hostname:

uv run bbaw-dse-mcp --transport http --host 127.0.0.1 --port 8000 \
  --allowed-host editions.example.org

Repeat --allowed-host for additional trusted hostnames. --allowed-origin allows an explicit browser origin; it does not configure CORS. Preserve the original Host and Origin headers through the proxy, disable buffering for SSE responses, and configure authentication/access restrictions at your deployment boundary before exposing the endpoint publicly. The repository does not configure an OAuth authorization server or issue access tokens. Modern requests need no worker affinity; legacy stateful HTTP clients still need session affinity when using multiple workers.

The deprecated HTTP+SSE transport remains available for legacy integrations with --transport sse (default path /sse). New integrations should use Streamable HTTP; the modern transport has no standalone GET stream, session DELETE, or resumable SSE event IDs.

For ASGI embedding, preserve the FastMCP lifespan and the body-primary validation guard:

from bbaw_dse_mcp.main import app
from bbaw_dse_mcp.protocol import modern_http_middleware

http_app = app.http_app(
    path="/mcp",
    middleware=[modern_http_middleware("/mcp")],
    host_origin_protection=True,
    allowed_hosts=["editions.example.org"],
)
# Mount http_app with its lifespan, not just its routes.

Before release, run uv run python scripts/verify_all_tools.py against the local composition, or add --url https://your-host/mcp to verify a deployed endpoint. The release verification guide documents coverage, semantic checks, expected limitations, JSON reports and failure exit status. Scoped --tool runs are not full release approval.

Modern protocol and raw smoke requests

Every modern request includes params._meta with io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities (an empty object is valid). io.modelcontextprotocol/clientInfo is recommended but optional. Requests are independently negotiated and can call tools before discovery. server/discover advertises protocol versions, capabilities, instructions, and server identity; ordinary results include resultType: "complete". Cacheable discovery/list/resource results include ttlMs and cacheScope. Tool diagnostics use standard Python module logging (stderr on stdio), not the deprecated MCP logging capability. They do not require client logging opt-in or emit unsolicited protocol log notifications.

On HTTP, include Accept: application/json, text/event-stream, MCP-Protocol-Version, and Mcp-Method on every request. tools/call, prompts/get, and resources/read additionally require Mcp-Name matching the body name or URI. Missing/mismatched routing headers return HTTP 400 with HeaderMismatch (-32020); missing required metadata returns -32602; unsupported versions return -32022 with supported and requested. Unknown or removed modern methods (including ping) return HTTP 404 and -32601. Header-safe values and Base64-sentinel names are validated by the SDK.

With the HTTP server running, these network-free calls exercise discovery, tool enumeration, and a real capability-tool execution:

META='{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}'
for METHOD in server/discover tools/list; do
  curl -sS http://127.0.0.1:8000/mcp \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -H 'MCP-Protocol-Version: 2026-07-28' -H "Mcp-Method: $METHOD" \
    --data "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"$METHOD\",\"params\":{\"_meta\":$META}}"
done
curl -sS http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' -H 'Mcp-Name: get_capabilities' \
  --data "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"_meta\":$META,\"name\":\"get_capabilities\",\"arguments\":{\"check_health\":false}}}"

The default HTTP response is request-scoped SSE, so JSON-RPC messages appear on data: lines. To check rejection, repeat the last request with Mcp-Name: wrong_name; expect HTTP 400 and code -32020. To check negotiation, set both the body version and version header to 2099-01-01; expect HTTP 400 and -32022, not a legacy fallback.

On stdio, write JSON bodies one per line without HTTP headers and keep stdin open until responses arrive (closing it is the graceful shutdown signal):

uv run python - <<'PY'
import asyncio
import json
import sys

async def smoke():
    proc = await asyncio.create_subprocess_exec(
        sys.executable, "-m", "bbaw_dse_mcp.main",
        stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE,
        limit=8 * 1024 * 1024,
    )
    meta = {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
    }
    try:
        calls = [
            ("server/discover", {}),
            ("tools/list", {}),
            ("tools/call", {"name": "get_capabilities", "arguments": {}}),
        ]
        for ident, (method, args) in enumerate(calls, 1):
            body = {"jsonrpc": "2.0", "id": ident, "method": method,
                    "params": {"_meta": meta, **args}}
            proc.stdin.write((json.dumps(body) + "\n").encode())
            await proc.stdin.drain()
            reply = json.loads(await asyncio.wait_for(proc.stdout.readline(), 30))
            assert reply["id"] == ident and reply["result"]["resultType"] == "complete"
            print(json.dumps(reply))
        proc.stdin.close()
        await asyncio.wait_for(proc.wait(), 10)
        assert proc.returncode == 0
    finally:
        if proc.returncode is None:
            proc.kill()
            await proc.wait()

asyncio.run(smoke())
PY

tests/contract/test_protocol.py covers raw HTTP and subprocess stdio, per-request errors, cache metadata, streaming-body replay, DNS-rebinding protection, and actual FastMCP modern/legacy clients. Run with uv run --extra dev pytest tests/contract/test_protocol.py --no-cov.

Upstream boundaries: SDK v2 supports both protocol eras, MRTR and subscriptions, but core experimental tasks have moved to an optional extension; this server does not register that extension or require client sampling/roots/elicitation. Its edition tools return complete results. A narrow ASGI guard compensates for SDK 2.3.0's header-only era router so modern bodies cannot evade header validation by omitting the version header or supplying a legacy one. It buffers/replays only MCP POST bodies, bounded to 8 MiB and 4,096 chunks (HTTP 413 above those limits); Host/Origin checks remain in FastMCP's outer middleware. See the official SDK v2 changes, FastMCP 4 migration guide, and HTTP transport requirements.

Prompt templates

Clients with MCP prompt support can start common, source-grounded workflows with:

  • research_correspondence — investigate a person's correspondence network.

  • analyze_edition_document — retrieve and analyze a known SD or MoP document.

  • deep_research — plan and execute a multi-step cross-edition investigation.

These prompts orchestrate the existing MCP tools in the host model. The server does not require a separate model-provider API key.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "editions": {
      "command": "uv",
      "args": ["run", "bbaw-dse-mcp"],
      "cwd": "/path/to/bbaw-dse-mcp"
    }
  }
}

Example Conversation

User: Search for letters mentioning Humboldt.

Agent: → search_documents(query="Humboldt", editions=["sd"], doc_types=["letter"])
       Inspect the returned native search hits and their source metadata.

User: Who was important for Schleiermacher in 1810?

Agent: → get_correspondence_statistics(editions=["sd"], ref="sd:S0003676",
             date_from="1810", date_to="1810", max_letters_to_analyze=500)
       Report indexed correspondence counts and the bounded partner ranking;
       distinguish frequency from historical importance and index coverage.

User: Can we trace Humboldt's correspondence network beyond this edition?

Agent: → authority_search_gnd(name_query="Humboldt, Wilhelm von")
       → cs_search_correspondent_network(person_gnd="118554727")
       Report the analyzed records, authority identities and completeness limits.

Tech Stack

  • FastMCP 4.x / MCP Python SDK 2.x — Native modern and legacy MCP protocol support

  • httpx — Async public HTTP APIs and pages

  • lxml — TEI-XML parsing

  • Pydantic v2 — Data models and settings

Documentation

License

MIT

Author

Tim Westphal, BBAW TELOTA

Available Tools

44 tools
cs_get_edition_infoA

Informationen über eine Edition in correspSearch abrufen.

PURPOSE: Metadaten zu registrierten Editionen

WHEN TO USE:

  • User fragt nach verfügbaren Editionen

  • Für Edition-Discovery

  • Um die Quelle von gefundenen Briefen zu identifizieren

Args: edition_id: Edition-UUID in correspSearch ctx: FastMCP Context

Returns: EditionInfo mit Metadaten zur Edition

Inputs: edition_id (required). Returns: Information about an edition registered in correspSearch.

cs_get_place_geonames_idA

Get the GeoNames ID for a place (convenience function).

PURPOSE: Quick lookup of a single GeoNames ID for a place.

WHEN TO USE:

  • When you just need the ID without details

  • For quick place-to-ID conversion

  • When you're confident about the place name

WHEN NOT TO USE:

  • When the place name might be ambiguous → use search_for_geonames_id()

  • When you need full place details

Args: place_name: Name of the place (e.g., "Berlin", "Paris") country: Optional ISO-2 country code to restrict search (e.g., "DE")

Returns: GeoNames ID as integer, or None if not found

Example: >>> berlin_id = await get_place_geonames_id("Berlin", country="DE") >>> # Returns: 2950159 >>> letters = await search_correspondences(place_geonames=str(berlin_id))

Inputs: place_name (required), country. Returns: result

cs_search_correspondencesA

Cross-Edition Briefsuche über correspSearch API.

PURPOSE: Briefe über Edition-Grenzen hinweg finden

WHEN TO USE:

  • User möchte Briefe in ALLEN Editionen finden

  • Cross-Referenzierung zwischen Editionen

  • Für umfassende Korrespondenz-Netzwerk-Analyse

  • Suche nach Korrespondenz einer historischen Person

WHEN NOT TO USE:

  • Für schleiermacher-spezifische Suche → nutze sd_search_letters()

Args: person_gnd: GND-ID(s) - einzelne ID oder Liste (z.B. "118540238" oder ["118540238", "118607626"]) person_viaf: VIAF-ID(s) - einzelne ID oder Liste (alternativ zu GND) start_date: Start-Datum (ISO 8601, z.B. "1810-01-01") end_date: End-Datum (ISO 8601, z.B. "1815-12-31") place_geonames: GeoNames-ID eines Ortes (z.B. "2879139" für Leipzig) occupation_wikidata: Wikidata-ID eines Berufs (z.B. "Q36180" für Schriftsteller) edition_id: UUID einer Edition zur Filterung cmif_url: URL einer CMIF-Datei (z.B. "https://gams.uni-graz.at/context:hsa/CMIF") availability: "online", "print" oder "hybrid" text_query: Volltextsuche in Briefinhalten (experimentell, undokumentiert) gender: "male" (männlich), "female" (weiblich), oder "unknown" (unbekannt) role: "sent" (nur als Absender), "received" (nur als Empfänger), oder "mentioned" (nur erwähnt) place_role: "sent" (Schreibort) oder "received" (Empfangsort) page: Seite der Ergebnisse (1-indiziert, je 100 Treffer) max_results: Maximale Ergebnisse (zur Anzeige-Begrenzung) ctx: FastMCP Context

Returns: CorrespSearchResult mit Briefen und Paginierungs-Info

Note: Mehrere Personen (Liste) werden mit AND kombiniert - findet nur Briefe, die ALLE angegebenen Personen enthalten.

Inputs: page, role, gender, cmif_url, +11 more. Returns: Result set from correspSearch API with pagination info.

cs_search_correspondent_networkA

Korrespondenz-Netzwerk einer Person analysieren.

PURPOSE: Netzwerkanalyse von Korrespondenzen

WHEN TO USE:

  • User fragt "Mit wem korrespondierte Person X?"

  • Netzwerk-Visualisierung vorbereiten

  • Wichtigste Korrespondenzpartner identifizieren

Args: person_gnd: GND-ID der fokalen Person start_date: Optional: Start-Datum für Zeitfilter end_date: Optional: End-Datum für Zeitfilter max_correspondents: Maximale Anzahl Korrespondenten im Ergebnis max_letters_to_analyze: Maximale Anzahl Briefe zu analysieren (pro Richtung) ctx: FastMCP Context

Returns: Dict mit Netzwerk-Statistiken und Top-Korrespondenten

Inputs: person_gnd (required), end_date, start_date, max_correspondents, +1 more. Returns: object

cs_search_for_geonames_idA

Search for GeoNames IDs by place name.

PURPOSE: Find GeoNames identifiers for places to use as filters.

WHEN TO USE:

  • When you need a GeoNames ID for correspSearch place filtering

  • To resolve place names to standard identifiers

  • For geographic analysis of correspondence networks

WHEN NOT TO USE:

  • For person or organization names → use search_for_gnd_id()

  • When you already have a GeoNames ID

Args: place_query: Place name to search for (e.g., "Berlin", "Paris") country: Optional ISO-2 country code to restrict search (e.g., "DE", "FR") limit: Maximum number of results to return

Returns: List of dicts with place information: - geonameId: The GeoNames ID (use this for correspSearch) - name: Place name - countryCode: ISO-2 country code - lat, lng: Coordinates - adminName1: First-level admin division (e.g., state) - population: Population count (if available)

Example: >>> results = await search_for_geonames_id("Berlin", country="DE") >>> geonames_id = str(results[0]['geonameId']) >>> letters = await search_correspondences(place_geonames=geonames_id)

Inputs: place_query (required), limit, country. Returns: result

cs_search_for_gnd_idA

Search for GND IDs by name using Lobid GND API.

PURPOSE: Find GND identifiers for persons, places, or corporate bodies.

WHEN TO USE:

  • When you need a GND ID for correspSearch filtering

  • To resolve person names to standard identifiers

  • For enriching metadata with authority data

WHEN NOT TO USE:

  • For full entity data → use get_gnd_entity() tools

  • For non-GND authority data → use other services

Args: name_query: Name or term to search for (e.g., "Goethe", "Humboldt") limit: Maximum number of results to return

Returns: List of dicts with 'id' (GND URI) and 'label' for matching entities

Example: >>> results = await search_for_gnd_id("Wilhelm von Humboldt") >>> gnd_id = results[0]['id'].split('/')[-1] # Extract ID from URI >>> letters = await search_correspondences(person_gnd=gnd_id)

Inputs: name_query (required), limit. Returns: result

cs_search_for_wikidata_occupationA

Search for occupation entities in Wikidata.

PURPOSE: Find Wikidata IDs for occupations to filter correspondence by profession.

WHEN TO USE:

  • When you need a Wikidata ID for correspSearch occupation filtering

  • To find letters by correspondent profession (writers, philosophers, etc.)

  • For professional network analysis

WHEN NOT TO USE:

  • For person names → use search_for_gnd_id()

  • For places → use search_for_geonames_id()

  • For non-occupation entities → use search_wikidata_entity()

Args: occupation_query: Occupation name to search for (e.g., "Dichter", "Philosoph", "Maler") limit: Maximum number of results to return

Returns: List of dicts with occupation entities: - id: Wikidata ID (e.g., "Q36180") - label: Occupation name in German - description: Brief description - uri: Full Wikidata URI

Example: >>> results = await search_for_wikidata_occupation("Schriftsteller") >>> occupation_id = results[0]['id'] # e.g., "Q36180" >>> letters = await search_correspondences(occupation_wikidata=occupation_id)

Inputs: occupation_query (required), limit. Returns: result

cs_search_wikidata_entityA

Search for any entity in Wikidata.

PURPOSE: General-purpose Wikidata entity search for various use cases.

WHEN TO USE:

  • When searching for entities that aren't occupations

  • For broader Wikidata lookups

  • When you need flexibility in entity type

WHEN NOT TO USE:

  • Specifically for occupations → use search_for_wikidata_occupation()

  • For GND/GeoNames data → use respective tools

Args: query: Search term for any Wikidata entity limit: Maximum number of results to return language: Language code for labels (default: "de")

Returns: List of dicts with entity information: - id: Wikidata ID (e.g., "Q36180") - label: Entity name - description: Brief description - uri: Full Wikidata URI

Example: >>> results = await search_wikidata_entity("Aufklärung") >>> entity_id = results[0]['id']

Inputs: query (required), limit, language. Returns: result

mop_browse_documentsA

Browse files and subcollections in MoP.

PURPOSE: Überblick über verfügbare Dateien in der MoP-Edition

WHEN TO USE:

  • User möchte sehen, was in der Edition verfügbar ist

  • Exploration ohne konkreten Suchbegriff

WHEN NOT TO USE:

  • Bei konkreter Suche → nutze search_documents()

  • Für Metadaten → nutze get_document() danach

Args: collection: Collection-Name (Texte, Register) limit: Maximale Anzahl Dateien ctx: FastMCP Context für Progress

Returns: Dict mit 'files' und 'subcollections' Liste

Inputs: limit, collection. Returns: object

mop_check_database_connectionA

Check if the database is reachable and responsive.

PURPOSE: Verify database connectivity for troubleshooting.

WHEN TO USE:

  • When other tools fail unexpectedly

  • To verify setup is working

  • Health monitoring

Returns: DatabaseStatus object with connection status, version, and paths

Inputs: no named parameters. Returns: object

mop_execute_xqueryA

Execute a raw XQuery against the database.

PURPOSE: Run custom queries for advanced users or debugging.

WHEN TO USE:

  • Other tools don't provide the needed functionality

  • Debugging or exploring data structure

  • Complex custom queries

WHEN NOT TO USE:

  • For common operations, use specific tools instead

  • Don't use for write operations (read-only!)

Args: query: XQuery string to execute max_results: Maximum number of results to return

Returns: Raw query result as string (usually XML)

Inputs: query (required), max_results. Returns: result

mop_extract_family_networkA

Familiennetzwerk aus einem Biogramm extrahieren.

PURPOSE: Verwandtschaftsbeziehungen analysieren

WHEN TO USE:

  • Für genealogische Forschung

  • Um höfische Netzwerke zu rekonstruieren

  • Analyse von Familiendynastien am Hof

Args: biogramm_id: XML-ID des Biogramms ctx: FastMCP Context

Returns: Dict mit Familienrelationen strukturiert nach Typ

Inputs: biogramm_id (required). Returns: object

mop_get_adjutanten_journal_entryA

Retrieve full text and metadata of a specific journal entry.

PURPOSE: Get complete details of a daily court journal entry.

WHEN TO USE:

  • After finding entries with search_adjutanten_journals()

  • User wants to read the full journal entry for a specific day

  • User needs detailed information about activities on a specific date

WHEN NOT TO USE:

  • For searching multiple entries → use search_adjutanten_journals()

  • For biographical data → use get_register_entry()

Args: document_id: Document ID from search results (e.g., "P0005285") ctx: FastMCP Context for progress reporting

Returns: Dict with: - id: Document ID - monarch: Which monarch's reign - date_from/date_to: Time range covered - shelfmark: Archive reference - days: List of daily entries, each with: - date: ISO date - place: Location - authors: Adjutants on duty - text: Full journal text for that day - url: Link to online edition

Raises: ToolError: If document not found or retrieval fails

Inputs: document_id (required). Returns: object

mop_get_biogramm_by_idA

Vollständiges Biogramm mit allen Details abrufen.

PURPOSE: Detaillierte biografische Daten einer Person abrufen

WHEN TO USE:

  • Nach search_biogramme() um Details zu bekommen

  • Um Familiennetzwerk, Karriere, Besitz zu analysieren

  • Für vollständige prosopographische Information

Args: biogramm_id: XML-ID des Biogramms (z.B. "P0005251") ctx: FastMCP Context

Returns: Dict mit allen biografischen Daten strukturiert

Inputs: biogramm_id (required). Returns: object

mop_get_documentA

Vollständiges Dokument abrufen.

PURPOSE: Detaillierte Ansicht eines spezifischen Dokuments

WHEN TO USE:

  • User möchte ein Aktenstück lesen

  • Nach erfolgreicher Suche → Details anzeigen

WHEN NOT TO USE:

  • Für Übersicht → nutze browse_documents() oder search_documents()

Args: document_id: Die xml:id des Dokuments include_xml: Ob TEI-XML inkludiert werden soll ctx: FastMCP Context

Returns: Document-Objekt mit Metadaten und Content

Inputs: document_id (required), include_xml (required). Returns: Generic document (letter, diary, lecture, etc.).

mop_get_register_entryA

Detailansicht eines Registereintrags.

PURPOSE: Vollständige Informationen zu Person, Ort, etc.

WHEN TO USE:

  • Nach Registersuche für Details

  • Für biographische/geographische Informationen

Args: entry_id: ID des Registereintrags register_type: Register-Typ ctx: FastMCP Context

Returns: Dict mit allen verfügbaren Informationen

Inputs: entry_id (required), register_type. Returns: object

mop_get_residential_topographyA

Fetch complete residential topography dataset for a specific year.

PURPOSE: Retrieve GeoJSON data with addresses and locations of court officials, royal family members, and other persons/institutions in Berlin and Prussia.

WHEN TO USE:

  • User asks about where people lived in a specific year

  • User wants to analyze residential patterns

  • User needs geographic distribution of court members

  • For mapping and spatial analysis

WHEN NOT TO USE:

  • For biographical register data → use search_register()

  • For document texts → use browse_documents() or search_documents()

Args: year: Year for which to retrieve data (1800, 1845, 1872, 1891, or 1914) ctx: FastMCP Context for progress reporting

Returns: Dict with: - year: The requested year - total_features: Total number of entries - features_with_coordinates: Number of entries with valid geographic coordinates - categories: Count of entries per category - cities: Count of entries per city - sample_features: First 10 features as examples - query_methods: Available search methods

Raises: ToolError: If year is not available or API request fails

Inputs: year (required). Returns: object

mop_list_adjutanten_by_monarchA

List all adjutants who served under a specific monarch.

PURPOSE: Identify who served as adjutant and when.

WHEN TO USE:

  • User asks "Who served as adjutant under Wilhelm I?"

  • User wants to know the rotation of adjutants

  • User researches prosopography of court officials

WHEN NOT TO USE:

  • For full biographical data → use search_register()

  • For journal content → use search_adjutanten_journals()

Args: monarch: Monarch name (Friedrich_Wilhelm_IV, Wilhelm_I, Wilhelm_II, Friedrich_III) ctx: FastMCP Context for progress reporting

Returns: Dict with: - monarch: Monarch name - total_entries: Number of journal entries analyzed - adjutants: List of adjutants with: - name: Full name - person_key: Register ID - entries_count: How many times they wrote entries - date_range: First and last appearance

Raises: ToolError: If monarch is invalid or query fails

Inputs: monarch (required). Returns: object

mop_list_available_wohntopo_yearsA

List all available years for residential topography data.

PURPOSE: Show which years have Wohntopographie datasets available.

WHEN TO USE:

  • User asks about available time periods

  • User wants to know which years can be queried

  • Before choosing a year for analysis

Returns: Dict with available years and description

Inputs: no named parameters. Returns: object

mop_search_adjutanten_journalsA

Search in Adjutantenjournale (court adjutant journals).

PURPOSE: Find daily court journal entries documenting royal activities, audiences, meetings, and events. Each entry shows who was on duty and what happened.

WHEN TO USE:

  • User asks "What did the king do on [date]?"

  • User wants to know about daily court life

  • User searches for specific events, persons, or places mentioned in journals

  • User wants to track activities of a specific monarch

  • User researches who served as adjutant when

WHEN NOT TO USE:

  • For biographical data → use search_register()

  • For correspondence → use letters search in Schleiermacher Digital

  • For institutional documents → use browse_documents()

Args: query: Full-text search term (searches in journal text) monarch: Filter by monarch (Friedrich_Wilhelm_IV, Wilhelm_I, Wilhelm_II, Friedrich_III) date_from: Start date in ISO format (YYYY-MM-DD), e.g., "1861-01-01" date_to: End date in ISO format (YYYY-MM-DD), e.g., "1861-12-31" person_key: Filter by person mentioned (register key, e.g., "P0002157") place_key: Filter by place mentioned (register key, e.g., "P0003556") limit: Maximum number of results (default: 50) ctx: FastMCP Context for progress reporting

Returns: List of journal entries with: - id: Document ID - monarch: Which monarch's reign - date_from/date_to: Time range covered - place: Where the court was located - authors: Adjutants who wrote the entry - snippet: Text excerpt showing matched content - url: Link to full entry on website

Raises: ToolError: If monarch is invalid or query fails

Inputs: limit, query, date_to, monarch, +3 more. Returns: result

mop_search_biogrammeA

Suche in MoP-Biogrammen (detaillierte Biografien).

PURPOSE: Detaillierte biografische Einträge finden

WHEN TO USE:

  • User sucht nach Person für biografische Details

  • Um Familienverhältnisse, Karriere, Besitztümer zu recherchieren

  • Prosopographische Forschung zu Hofbeamten

WHEN NOT TO USE:

  • Für einfache Registersuche → nutze search_register("personen")

  • Für Volltextsuche in Dokumenten → nutze search_documents()

Args: query: Suchbegriff (Name) birth_year: Filter nach Geburtsjahr death_year: Filter nach Sterbejahr max_results: Maximale Ergebnisse ctx: FastMCP Context

Returns: Liste von Biogramm-Treffern mit id, name, birth, death, gnd

Inputs: query (required), birth_year, death_year, max_results. Returns: result

mop_search_documentsA

Volltextsuche in MoP-Dokumenten.

PURPOSE: Dokumente finden, die einen bestimmten Begriff enthalten

WHEN TO USE:

  • User sucht nach Person, Institution, Thema

  • Explorative Suche zu höfischen Praktiken

WHEN NOT TO USE:

  • Für strukturierte Registersuche → nutze search_register()

Args: keyword: Suchbegriff collection: Collection (Texte) max_results: Maximale Ergebnisse ctx: FastMCP Context

Returns: Liste von SearchResult-Objekten

Inputs: keyword (required), collection, max_results. Returns: result

mop_search_registerA

Suche in MoP-Registern.

PURPOSE: Strukturierte Registereinträge finden

WHEN TO USE:

  • User sucht nach Person, Ort, Institution, Hof

  • Um IDs für weitere Suchen zu bekommen

WHEN NOT TO USE:

  • Für Volltextsuche → nutze search_documents()

Args: query: Suchbegriff register_type: Register (personen, orte, institutionen, hoefe, werke, aemter) max_results: Maximale Ergebnisse ctx: FastMCP Context

Returns: Liste von Register-Einträgen mit id, name, type, gnd (optional)

Inputs: query (required), max_results, register_type. Returns: result

mop_search_residential_topographyA

Search residential topography data with multiple filters.

PURPOSE: Find persons/institutions by various criteria in historical address data.

WHEN TO USE:

  • User searches for specific person by name

  • User wants to know who lived at a specific address

  • User wants to filter by profession, category, or location

  • User needs to find all court members in a certain category

WHEN NOT TO USE:

  • For biographical details → use get_register_entry()

  • For full dataset overview → use get_residential_topography()

Args: year: Year for data (1800, 1845, 1872, 1891, or 1914) name: Last name (partial match, case-insensitive) vorname: First name (partial match, case-insensitive) kategorie: Category filter (e.g., "Königliche Familie", "Diplomatie") taetigkeit: Occupation/activity filter stadt: City filter (partial match) strasse: Street name filter (partial match) ediarum_id: Exact Ediarum-ID match only_with_coordinates: Return only entries with valid geographic coordinates max_results: Maximum number of results to return ctx: FastMCP Context

Returns: Dict with: - year: The queried year - filters_applied: List of active filters - total_matches: Number of matching entries - returned_results: Number of results in response (limited by max_results) - results: List of matching features

Raises: ToolError: If year is not available or no filters provided

Inputs: year (required), max_results (required), only_with_coordinates (required), name, +6 more. Returns: object

sd_check_database_connectionA

Check if the database is reachable and responsive.

PURPOSE: Verify database connectivity for troubleshooting.

WHEN TO USE:

  • When other tools fail unexpectedly

  • To verify setup is working

  • Health monitoring

Returns: DatabaseStatus object with connection status, version, and paths

Inputs: no named parameters. Returns: Database connection status.

sd_execute_xqueryA

Execute a raw XQuery against the database.

PURPOSE: Run custom queries for advanced users or debugging.

WHEN TO USE:

  • Other tools don't provide the needed functionality

  • Debugging or exploring data structure

  • Complex custom queries

WHEN NOT TO USE:

  • For common operations, use specific tools instead

  • Don't use for write operations (read-only!)

Args: query: XQuery string to execute max_results: Maximum number of results to return

Returns: Raw query result as string (usually XML)

Inputs: query (required), max_results. Returns: result

sd_filter_lettersA

Filter letters by sender, receiver, place, and time period.

PURPOSE: Filter letters by specific criteria (FAST - uses cache)

WHEN TO USE:

  • User asks "letters from/to person X"

  • User asks "letters from Berlin"

  • User asks "letters between 1810 and 1815"

  • For correspondence network analyses

WHEN NOT TO USE:

  • For keyword search → use search_by_keyword()

  • For register search → use search_register()

Args: sender: Person ID of sender (from register, e.g., "S0003676") receiver: Person ID of receiver (from register, e.g., "S0003677") send_place: Place ID or name of sending location (e.g., "S0000065" or "Berlin") not_before: Earliest date (ISO 8601, e.g., "1810-01-01") not_after: Latest date (ISO 8601, e.g., "1815-12-31") max_results: Maximum results ctx: FastMCP Context

Returns: List of Letter objects

Inputs: sender, receiver, not_after, not_before, +2 more. Returns: result

sd_get_chronology_entriesA

Retrieve chronology entries for a date range.

PURPOSE: Access events from Schleiermacher's life across a time period

WHEN TO USE:

  • User asks what happened during a specific period

  • User wants biographical timeline for a date range

  • For temporal analysis of Schleiermacher's life events

WHEN NOT TO USE:

  • For single date → use get_chronology_entry()

  • For entire year → use get_chronology_year()

  • For keyword search → use search_documents()

Args: date_from: Start date in ISO 8601 format (YYYY-MM-DD) date_to: End date in ISO 8601 format (YYYY-MM-DD) ctx: FastMCP Context

Returns: List of dictionaries with date info and event descriptions, sorted chronologically. Includes both specific dates and date ranges that overlap with the query range.

Inputs: date_to (required), date_from (required). Returns: result

sd_get_chronology_entryA

Retrieve chronology entries for a specific date.

PURPOSE: Access events from Schleiermacher's life on a specific date

WHEN TO USE:

  • User asks what happened on a specific date

  • User wants biographical information for a particular day

  • After search → get full chronology entry

WHEN NOT TO USE:

  • For date range → use get_chronology_entries()

  • For entire year → use get_chronology_year()

  • For keyword search → use search_documents()

Args: date: Date in ISO 8601 format (YYYY-MM-DD), e.g., "1785-08-29" ctx: FastMCP Context

Returns: List of dictionaries with date info and event descriptions. Multiple events may occur on the same date.

Inputs: date (required). Returns: result

sd_get_chronology_yearA

Retrieve all chronology entries for a specific year.

PURPOSE: Access complete biographical timeline for a year in Schleiermacher's life

WHEN TO USE:

  • User asks "What happened in 1785?"

  • User wants overview of activities in a specific year

  • For annual biographical summaries

WHEN NOT TO USE:

  • For specific date → use get_chronology_entry()

  • For date range spanning multiple years → use get_chronology_entries()

  • For keyword search → use search_documents()

Args: year: Year (e.g., 1785) ctx: FastMCP Context

Returns: Dictionary with year, heading, and list of chronology entries. Entries are sorted chronologically within the year.

Inputs: year (required). Returns: object

sd_get_collection_statsA

Get statistics about documents in a collection.

PURPOSE: Understand the size and content of a collection.

WHEN TO USE:

  • User asks "how many documents are there?"

  • Getting an overview before browsing/searching

  • Verifying data availability

Args: collection: Collection path (relative to data_path). Empty = root.

Returns: CollectionStats object with document counts and metadata

Inputs: collection. Returns: Statistics about a collection.

sd_get_correspondent_statsA

Statistics about correspondents (for network analysis).

PURPOSE: Overview of most important correspondents

WHEN TO USE:

  • User asks "Who was important for X?"

  • User asks "Most frequent correspondents"

  • For quantitative analyses

Args: year: Optional year filter min_letters: Minimum number of letters ctx: FastMCP Context

Returns: List of dicts with person_name, total, letters_sent, letters_received

Inputs: year, min_letters. Returns: result

sd_get_diary_entriesA

Retrieve diary entries for a date range.

PURPOSE: Access multiple diary entries across a time period

Available years: 1808-1811, 1817, 1820-1834. Note: 1812-1816 and 1818-1819 are not extant.

WHEN TO USE:

  • User asks for diary entries in a date range

  • User wants to see activities over a period

  • For temporal analysis of diary content

WHEN NOT TO USE:

  • For single date → use get_diary_entry()

  • For keyword search → use search_in_documents()

Args: date_from: Start date in ISO 8601 format (YYYY-MM-DD) date_to: End date in ISO 8601 format (YYYY-MM-DD) ctx: FastMCP Context

Returns: List of dictionaries, each with date, left_side, right_side content

Inputs: date_to (required), date_from (required). Returns: result

sd_get_diary_entryA

Retrieve a specific diary entry by date.

PURPOSE: Access a specific day's entry from Schleiermacher's diary

Available years: 1808-1811, 1817, 1820-1834. Note: 1812-1816 and 1818-1819 are not extant.

WHEN TO USE:

  • User asks for diary entry on specific date

  • User wants to know what happened on a particular day

  • After search → get full diary entry

WHEN NOT TO USE:

  • For date range → use get_diary_entries()

  • For keyword search → use search_in_documents()

Args: date: Date in ISO 8601 format (YYYY-MM-DD), e.g., "1808-01-01" ctx: FastMCP Context

Returns: Dictionary with date, content from left side, content from right side, and raw XML of the entry

Inputs: date (required). Returns: object

sd_get_document_by_idA

Retrieve complete document.

PURPOSE: Detailed view of a specific document as Markdown

WHEN TO USE:

  • User wants to read a letter/diary entry

  • After successful search → display details

  • For citations and text analysis

WHEN NOT TO USE:

  • For browsing/exploring → use list_collections() or list_collection_contents()

  • For keyword search → use search_by_keyword()

Args: document_id: The xml:id of the document ctx: FastMCP Context

Returns: Formatted markdown string with document content

Inputs: document_id (required). Returns: result

sd_get_document_passagesA

Retrieve text passages from a specific document.

PURPOSE: Get actual text content from a document found via search

WHEN TO USE:

  • After search returns relevant document IDs

  • User wants to read specific sections

  • Need actual quotes for citations

WHEN NOT TO USE:

  • For discovery → use search_documents_direct()

  • For full document → use get_document_by_id()

Args: document_id: The xml:id of the document query: Optional search term to highlight/filter passages division: Filter to specific div by @n value page: Filter to specific page by pb/@n context_size: Characters of context around matches max_passages: Maximum passages to return ctx: FastMCP Context

Returns: List of Passage objects with text and location info

Inputs: document_id (required), page, query, division, +2 more. Returns: result

sd_get_file_infoA

Get basic metadata for a single document file.

PURPOSE: Extract basic TEI metadata from a document without full parsing.

WHEN TO USE:

  • After browsing, to get details about specific files

  • When you need title, date, or ID information

  • For quick metadata extraction

WHEN NOT TO USE:

  • For full document content → use get_document tools

  • For multiple files at once → use browse then call this for each

Args: file_path: Full path to the file (relative to /db) or just filename ctx: FastMCP Context for progress reporting

Returns: Dict with 'id', 'title', 'date', 'path', 'mime_type', 'size_bytes', 'modified'

Inputs: file_path (required). Returns: Metadata information about a file.

sd_get_raw_document_by_idA

Retrieve raw XML document by its xml:id.

PURPOSE: Fetch raw XML for a document using its TEI xml:id attribute.

WHEN TO USE:

  • After finding a document via search or browse

  • When you need the raw XML for custom processing

  • As a low-level building block for edition-specific tools

WHEN NOT TO USE:

  • For exploring/discovering documents → use browse or search tools

  • When you only have a file path → use get_raw_document_by_path()

Args: document_id: The xml:id attribute of the TEI document collection: Optional collection filter (relative to data_path) ctx: FastMCP Context for progress reporting

Returns: RawDocument with id and xml content

Inputs: document_id (required), collection. Returns: Raw XML document from the database (unparsed).

sd_get_raw_document_by_pathA

Retrieve raw XML document by its file path.

PURPOSE: Fetch raw XML for a document using its database path.

WHEN TO USE:

  • When you have a file path from browse_collection

  • When accessing documents with known paths

  • Faster than ID-based lookup when path is known

WHEN NOT TO USE:

  • When you have an xml:id → use get_raw_document_by_id()

  • For exploring documents → use browse or search tools

Args: doc_path: Path to the document (relative to /db) ctx: FastMCP Context for progress reporting

Returns: RawDocument with id, xml content, and path

Inputs: doc_path (required). Returns: Raw XML document from the database (unparsed).

sd_get_register_entryA

Get detailed information about a register entry.

PURPOSE: Complete register entry details, optionally with mentions

WHEN TO USE:

  • After register search for details about a person/place/work

  • For biographical information

  • To find mentions in letters/diaries (set include_mentions=True)

WHEN NOT TO USE:

  • For document details → use get_document_by_id()

Args: entry_id: xml:id of the register entry (e.g., "S0003676") include_mentions: If True, fetch mentions across letters, diaries, lectures max_mentions: Max mentions per category when include_mentions=True (default 20) ctx: FastMCP Context

Returns: PersonEntry, PlaceEntry, WorkEntry, or dict based on entry type

Inputs: entry_id (required), max_mentions, include_mentions. Returns: result

sd_list_collection_contentsA

List files and subcollections in a collection.

PURPOSE: List files and subcollections without parsing document contents.

WHEN TO USE:

  • User wants to see what's available in a collection

  • Exploring collection structure

  • Fast overview of files and folders

WHEN NOT TO USE:

  • For document metadata → use get_file_info() afterward

  • For specific keyword search → use edition-specific search tools

  • For full document details → use get_document tools

Args: collection: Collection name/path (relative to data_path). Empty = root. limit: Maximum number of files to return ctx: FastMCP Context for progress reporting

Returns: Dict with 'collection_path', 'file_count', 'files', and 'subcollections'

Inputs: limit, collection. Returns: Contents of a collection (files and subcollections).

sd_list_collectionsA

List available sub-collections in the database.

PURPOSE: Explore the database structure and find available collections.

WHEN TO USE:

  • User wants to know what data is available

  • Exploring the database structure

  • Finding the correct collection name for other queries

Args: parent: Parent collection path (relative to data_path). Empty = root.

Returns: Collection object with path, collections list, and document_count

Inputs: parent. Returns: Information about an eXist-db Collection.

sd_search_documentsA

Search documents in Schleiermacher Digital via eXist-db with facets.

PURPOSE: Primary search tool for finding documents by text, type, year, etc.

WHEN TO USE:

  • Full-text search in documents

  • Filter by document type (letter, diary, lecture, etc.)

  • Filter by year or date range

  • Any search query for document discovery

WHEN NOT TO USE:

  • For structured letter filtering by sender/receiver → use filter_letters()

  • For register search (persons, places) → use search_register()

  • For detailed text passages → use get_document_passages()

⚠️ CITATION WARNING: Only cite documents returned by this tool. Each result includes:

  • document_id: Use this EXACT value for citations

  • citation_url: Use this EXACT URL, do not construct your own NEVER invent document IDs or URLs that were not returned in the results.

Valid doc_types (from index):

  • "letter" or "letter fs" (8071 documents)

  • "lecture" or "lecture fs" (143 documents)

  • "chronology" (61 documents)

  • "intro" (42 documents)

  • "chronology-intro" (29 documents)

  • "diary" or "diary fs" (21 documents)

Args: query: Search terms (space-separated for multiple terms) doc_types: Filter by document types (letter, letter fs, diary, diary fs, lecture, lecture fs, chronology, intro) years: Filter by years (e.g., ["1810", "1811"]) date_from: Earliest date (ISO 8601, e.g., "1810-01-01") date_to: Latest date (ISO 8601, e.g., "1815-12-31") include_commentary: If True, search in commentary too (default: True) use_or_logic: If True, use OR between terms (default); if False, use AND limit: Maximum results (default: 50) ctx: FastMCP Context

Returns: List of SearchResult objects with document_id, title, type, date, kwic_snippets, and citation_url

Inputs: limit (required), query (required), use_or_logic (required), include_commentary (required), +4 more. Returns: result

sd_search_registerA

Search register using Lucene fulltext index.

PURPOSE: Find persons, places, works, or organizations using indexed search

WHEN TO USE:

  • User searches for person, place, work, or organization

  • For biographical/geographical/bibliographical information

  • To get IDs for further searches

WHEN NOT TO USE:

  • For fulltext search in letters/diaries → use search_by_keyword()

Args: query: Search term (name, title, etc.) register_type: Optional filter - 'person', 'place', 'work', 'org', or None for all max_results: Maximum results ctx: FastMCP Context

Returns: List of register entry dicts with id, title, desc, type

Inputs: query (required), max_results, register_type. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 44 tools

    Disambiguation2/5

    There are multiple pairs of essentially identical tools (sd_execute_xquery/mop_execute_xquery, sd_check_database_connection/mop_check_database_connection) and very similar search tools across editions (sd_search_documents/mop_search_documents). Additionally, cs_search_for_geonames_id and cs_get_place_geonames_id are confusingly similar, making tool selection difficult for an agent.

    Naming Consistency4/5

    The naming generally follows a consistent prefix_verb_noun pattern (e.g., sd_search_documents, mop_get_register_entry, cs_search_correspondences). Minor deviations exist: 'wohntopo' in mop_list_available_wohntopo_years contrasts with 'residential_topography' in other mop tools, and cs_get_place_geonames_id uses 'get' instead of 'search_for' seen in similar tools.

    Tool Count3/5

    44 tools is a heavy count for a single MCP server. While the server covers three distinct edition projects (Schleiermacher Digital, MoP, correspSearch), the count is inflated by redundant utilities (duplicate execute_xquery and check_database_connection) and many specific niche tools. The count is borderline but not extremely excessive given the multi-edition scope.

    Completeness4/5

    The tool set provides broad read-only coverage for the three digital editions, including browsing, full-text search, register lookups, document retrieval, and specialized features like diary/chronology access, biographical searches, residential topography, and cross-edition correspondence search. Minor gaps exist such as no direct get-by-ID for residential topography entries and no tool to retrieve a specific correspSearch letter, but overall the domain is well covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching OpenAleph entities and documents using natural language queries through the MCP protocol.
      13 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for WirLernenOnline.de that enables searching and retrieving educational materials, collections, topic pages, and metadata through natural language, compatible with OpenAI and Claude.
      12
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables querying the Historisches Grundbuch Basel corpus, including full-text search, person lookups, and property dossier retrieval, through MCP-compatible clients like Claude.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A read-only MCP server that enables natural language querying of DSpace 7+ repositories via the REST API, allowing users to search, retrieve items, and analyze repository data.
      38 PyPI
      3
      MIT