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:

Related MCP server: WLO MCP Server

Available Tools

The composed server currently exposes 64 tools:

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_*, or cs_* response, including shared calls that resolve edition data, carries a provenance block in MCP _meta.provenance. It records every consulted source, the configured live backend, dataset, and UTC retrieval time. Because the current connectors do not expose one coherent machine-readable data release for their queried data, data_release is truthfully null and release_status is not_provided_by_source; a backend software version is never presented as an edition release.

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

search_documents_detailed(...) and search_entities_detailed(...) retain results from successful editions when another backend fails and expose per-source counts, failures, filter handling, completeness, and pagination. Their total_count is exact only when total_known=true; otherwise it is an explicit lower bound. strict_filters=true skips sources that cannot apply a requested filter instead of silently broadening the search. The established list-returning search tools remain backward compatible.

get_resource_relations(ref=...) exposes one common, evidence-backed relation model for Schleiermacher, MoP, and Jean Paul 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. 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.

MoP's shared full-text search now covers Druck, Korrespondenz, Adjutantenjournale, Hofkalendarium, and Instruktionen. Use doc_types=["<collection>"] to select one of them and mop_get_document_passages to read beyond the 2,000-character preview without silent passage truncation. 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+.

For on-demand OCR of Schleiermacher letters that are available only as facsimiles, install Tesseract and its German language data as well:

# Debian/Ubuntu
sudo apt install tesseract-ocr tesseract-ocr-deu

# Arch Linux
sudo pacman -S tesseract tesseract-data-deu

When get_document(ref="sd:…", view="text") encounters a letter without TEI body text, it retrieves the BBAW IIIF facsimiles at 3000 px width, runs Tesseract deu with positioned TSV output, and returns explicitly marked, unreviewed OCR. Set EDITIONS_SD_OCR_ENABLED=false to disable this fallback.

Configuration

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

# Schleiermacher Digital eXist-db
EDITIONS_SD_URL=http://localhost:8080
EDITIONS_SD_USERNAME=admin
EDITIONS_SD_PASSWORD=

# Praktiken der Monarchie eXist-db
EDITIONS_AB_URL=https://actaborussica.bbaw.de
EDITIONS_AB_PUBLIC_URL=https://actaborussica.bbaw.de
EDITIONS_AB_USERNAME=
EDITIONS_AB_PASSWORD=

# 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

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: → sd_search_documents(query="Humboldt", doc_type="letters")
       Found 23 letters mentioning Humboldt, mostly from 1810 —
       the year of the Berlin university founding...

User: Who was important for Schleiermacher in 1810?

Agent: → sd_get_correspondent_stats(year=1810)
       Based on letter frequency, the most important correspondents in 1810:
       1. Charlotte Schleiermacher (15 letters) — his sister
       2. Wilhelm von Humboldt (8 letters) — central figure in university reform
       ...

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")
       Cross-edition network across 12 editions: ...

Tech Stack

• FastMCP 3.x — Python MCP server framework

• httpx — Async HTTP client for eXist-db REST API

• lxml — TEI-XML parsing

• Pydantic v2 — Data models and settings

Documentation

• AGENT.md — Project overview and design decisions

• docs/TOOLS.md — Detailed tool specifications

• docs/ARCHITECTURE.md — Technical architecture

• docs/CODING_GUIDELINES.md — Extension and testing rules

License

MIT

Author

Tim Westphal, BBAW TELOTA