-
Notifications
You must be signed in to change notification settings - Fork 0
1.13 Archive Connectors Guide
New in v1.0.0-rc.2. ClioDeck ships three public-archive connectors as MCP tools on its built-in server. The Brainstorm chat can call them through the MCP tool-use loop; external MCP clients (Claude Desktop, Claude Code) can call them too once you've enabled the MCP server.
| Connector | Endpoint | API key | Status |
|---|---|---|---|
| Gallica (BnF) | SRU, public | None | Active by default |
| HAL (CCSD) | Solr, public | None | Active by default |
| Europeana | REST, requires wskey
|
Required — free, from pro.europeana.eu | Inactive until a key is configured |
The connectors live in backend/mcp-server/tools/searchGallica.ts, searchHal.ts, searchEuropeana.ts. They are registered unconditionally in backend/mcp-server/server.ts; Europeana checks for a key at call time and returns a typed missing_api_key error if none is set.
Gallica is the digital library of the Bibliothèque nationale de France. The connector queries Gallica's public SRU endpoint — no key, no quota beyond standard rate limiting.
Tool: search_gallica.
| Input | Type | Required | Notes |
|---|---|---|---|
query |
string | yes | Free-text query. Gallica indexes many languages, but the catalogue's metadata is French-first. |
topK |
int 1–200 | no (default 10) | Number of hits. |
dateFrom |
int 0–9999 | no | Earliest publication year (inclusive). |
dateTo |
int 0–9999 | no | Latest publication year (inclusive). |
docType |
string | no | Filter on Dublin Core dc:type (e.g. monographie, périodique, carte). |
HAL is the French open archive for scientific publications, hosted by CCSD (CNRS). The connector hits HAL's public Solr endpoint.
Tool: search_hal.
| Input | Type | Required | Notes |
|---|---|---|---|
query |
string | yes | Free-text Solr query. HAL indexes many languages. |
topK |
int 1–200 | no (default 10) | Number of hits. |
dateFrom |
int 0–9999 | no | Earliest production year (inclusive). |
dateTo |
int 0–9999 | no | Latest production year (inclusive). |
docType |
string | no | HAL docType_s. Common values: ART (journal article), COMM (conference paper), THESE (thesis), OUV (book), COUV (book chapter), REPORT. |
Europeana aggregates content from European museums, libraries and archives — around 50 million items. The connector needs a free API key (wskey).
Tool: search_europeana.
| Input | Type | Required | Notes |
|---|---|---|---|
query |
string | yes | Free-text query. |
topK |
int 1–200 | no (default 10) | Number of hits. |
mediaType |
enum | no | One of IMAGE, TEXT, VIDEO, SOUND, 3D. |
- Go to pro.europeana.eu/pages/get-api and request a key (free, immediate).
- In ClioDeck, open Settings → Archives.
- Paste the key into the Europeana field and click Save.
- The status badge turns to configured. To rotate, paste a new key over the existing one. To revoke, click Delete.
The key is encrypted via Electron's safeStorage (OS keychain on macOS, libsecret on Linux, DPAPI on Windows) — it is never written to .cliodeck/config.json and never appears in the workspace export.
This key is global, not per-project. It lives in the app-wide cliodeck-secrets store (secureStorage, keyed mcp.europeana.apiKey) and is mirrored to process.env.EUROPEANA_API_KEY at app startup and on every save/delete in Settings — never re-read per project. Checked specifically for the "does state bleed across a project switch" risk that broke other integrations elsewhere in this wiki (issues #33/#34/#39): there's no risk here, precisely because the key was never project-scoped to begin with — it's the same key regardless of which project is open.
The Europeana key stored in Settings → Archives only reaches the built-in MCP server when ClioDeck spawns it itself. If you've configured Claude Desktop (or another client) to spawn cliodeck-mcp directly, you must also set EUROPEANA_API_KEY in the client's MCP server configuration. The server reads the env var at every call, so you can rotate without restarting.
See the MCP Integration Guide for the snippet shape.
The three connectors are most useful in two situations:
- From Brainstorm, when an LLM with tool-use is asked an open-ended question and decides on its own to search Gallica or HAL for a primary source it doesn't have in the local corpus.
- From an external MCP client (Claude Desktop / Claude Code), as a way to ask a frontier model to plan a research trip or pre-screen archive holdings without ClioDeck's UI in the loop.
Results land in the chat as a tool-call event followed by a model turn that cites the returned URLs. The connectors do not import items into your bibliography or Tropy archive — those flows stay manual (Zotero connector / Tropy import).
The MCP-tool surface is the same in RC2 for all three connectors; the UI affordances differ. Only Europeana currently has a dedicated key-management UI in Settings → Archives, because it is the only connector that requires one. The fusion strategy document mentions FranceArchives and Transkribus as future candidates; they are not implemented in RC2.