AMIRA MCP Server
Provides search and retrieval of the cluster's YouTube videos, including full-text search over video transcripts, match snippets, thumbnails, and optional transcript details.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
AMIRA MCP Server
Read-only Model Context Protocol server for the Africa Multiple Interactive Research Atlas (AMIRA), the research-data platform of the Africa Multiple Cluster of Excellence at the University of Bayreuth. AMIRA is published on the cluster's public Omeka S site at data.africamultiple.uni-bayreuth.de.
AMIRA is built and maintained by the Cluster's Digital Research Environment (DRE), its digital infrastructure unit. The DRE designs, builds, and maintains the data systems that connect researchers across the Africa Multiple Research Centres (AMRCs) and partner institutions worldwide. Curation and description are joint efforts with partners at the AMRCs in Université Joseph Ki-Zerbo, Rhodes University, the University of Lagos, and Moi University. Bayreuth hosts the coordinating DRE infrastructure and metadata layer. Federal University of Bahia is a privileged partner, not an AMRC.
Storage stays distributed by default: data remains in its local repository, while Bayreuth holds the metadata layer that points to it. Research data becomes findable without being relocated. High-quality metadata makes researchers' data more discoverable and their work more visible to a wider community of peers.
This server exposes AMIRA's projects, thematic research sections, ~4,000 digitised research items, people, institutions, groups, collections, the cluster bibliography with searchable full text (extracted from the open-access PDFs) and its journals, podcast episodes with transcripts, the cluster's YouTube videos with searchable transcripts, and the Cluster Chronicles, its writer-in-residence works (essays and poems with their full text, photographs, events) — as 38 core tools an LLM can query, five research-workflow prompts, and resources for citable records and bulk exports. From one MCP interface, clients can move across records and the places, languages, and subjects that connect them.
Every record carries an amira_url — its public page on the Omeka S site
(…/s/amira/item/<id>) — so findings can be cited as links back to the source.
AMIRA focuses on the Cluster's research data. For news, events, and general
information about the Africa Multiple Cluster of Excellence, visit
africamultiple.uni-bayreuth.de.
Coverage checked 6 October 2026: 3,975 research items (1,419 with digitised
media), 93 projects, 555 publications (60 with extracted full text), 87 journals,
43 podcast episodes, 140 videos and 3,085 subject authorities (646 Library of
Congress headings). Counts are a dated snapshot; use get_collection_overview for
what your running server actually holds. See the publication guide,
the changelog for what each release changed, and the
roadmap for further improvements.
How it gets its data — and why nothing else is needed
The server is self-contained and offline-first. It reads from two sources:
A complete data snapshot bundled inside the
.mcpb— crawled from the public Omeka S REST API at build time and transformed into compact typed records, so the server works fully offline with zero setup.(optional, on by default) the Omeka S API over HTTPS. At startup and daily, probes compare item and item-set modification signatures and totals. A changed signal triggers a complete crawl; a weekly forced crawl also catches vocabulary-only edits. A writer lock, immutable generations and an atomic pointer preserve the previous usable snapshot if refresh fails. The API origin and installation path partition the cache and must match the manifest before its records can be served under that site's citation URLs.
End users need no API key, no credentials, and no VPN — it's the same openly published data that powers the public site.
Related MCP server: studyproof
Tools
Call get_collection_overview first to scope the data, then drill in.
Tool | Purpose |
| Counts and breakdowns across the whole collection + snapshot freshness |
| Find items by keyword (every word must match; quote a phrase), subject, location (hierarchy-aware), country (exact, with aliases such as Côte d'Ivoire = Ivory Coast), contributor, project, section, university, resource type, format/genre, language, year, |
| Full metadata for one item (by Omeka |
| Projects by keyword or acronym, university, section, PI, member, funder — detail with item breakdown, top subjects and sample items |
| Thematic sections with funding phases (AM 1.0 / AM 2.0), PIs, counts, projects; detail by name or id |
| People (either name order works) — profile with GND and other authority identifiers, project and research-section roles, items, publications, podcasts, videos, Cluster Chronicles works and top collaborators, with a |
| Organisations (institutions, Africa Multiple partner categories, and research groups) by name, acronym or id, their projects, people and items |
| Subject headings ranked by item frequency, each marked as a Library of Congress heading (with its id.loc.gov URI) or a free tag (`vocabulary=lcsh |
| Every place — countries and the places under them in one flat list (hierarchy rolled up) — ranked by item count, with coordinates and Wikidata ids. Each row's |
| Collections ranked by research-item count. A collection is a research project: cited by the project page, with the item set(s) filing it ( |
| Facet values: formats/genres, languages, resource types |
| Date histogram of research items by year or decade — coverage over time, most-covered year/decade |
| Filter the bibliography by author, subject, language, type, venue, year, date added and full-text availability; search abstracts in every language and extracted PDF text. Detail adds every abstract with its language, linked authorities, conference/extent/access/thesis metadata. |
| Counts by type, year, language, subject, author/editor or venue across the complete filtered bibliography; ranked and paginated |
| The journals the cluster publishes in, ranked by publication count, with ISSN and country — pair with the |
| Cross-entity discovery: pivot from a subject/place/person/project to co-occurring entities (incl. publications, and Cluster Chronicles works for subject/place/person), from an ILAM African Music article ( |
| The Cluster Chronicles, the cluster's writer-in-residence programme curated by Ute Fendler (Elnathan John 2021, Jean Luc Raharimanana 2023, Umar Timol 2024, Egara Kabaji 2026): one record per work, filterable by chronicler or other credited or depicted person, form (essay, poem, still image, event, video), year, subject, place and keyword (reaching into the essays' and poems' full text, with a snippet). Detail gives the credits with their roles (author, photographer, artist, translator, speaker, moderator), the people a photograph depicts, linked and literal subjects and places, the related works, videos and podcast episodes as typed ids, the images, and the abstract flagged as AI-written with the model that wrote it; the text is opt-in ( |
| Cluster podcast episodes with searchable transcripts, filterable by language; detail gives the duration, audio file and the model that generated the transcript; transcript text is opt-in |
| The cluster's YouTube videos — full-text search over transcripts (match snippets; thumbnail; transcript opt-in on detail) |
| Resolve names or typed IDs (either vocabulary: |
| Bounded one-hop graph with distinct explicit links/co-occurrences and paginated cited evidence |
| Find passages in selected publication/video/podcast/chronicle records, with exact original-text offsets |
| Compare 2–4 projects or collections using common filters, denominators and missingness |
| Snapshot coverage, missing metadata and unresolved-reference counts |
| Page added, updated or deleted records across retained snapshots from the same instance |
| The ILAM journal African Music read through its private full text, from public derived counts: content groups (AI-labelled) with their articles, the countries articles name, and word rates per year for up to six words |
| Records whose catalogue descriptions read most alike, across research items, publications, videos, podcasts, projects and sections, with cosine scores and |
| The collection as unnamed groups of records close in meaning: each group's size, type mix, top subjects, countries and projects, and the records nearest its centre; |
Prompts and resources
Five prompts package multi-step research workflows. Hosts show them as slash
commands; their arguments autocomplete from the snapshot's own authority names, and
each restates the citation rules. They are listed through prompts/list, so they
add nothing to the per-turn tool payload.
Prompt | Arguments | Workflow |
|
| Facets, publications, full-text passages and related research data on a topic |
|
| Team, holdings, periods, places and connections of one project |
|
| Disambiguation, profile, graph and publication list of one person, presented as AMIRA's records rather than an assessment of the person |
|
| Items, projects, subjects and periods for a country, city or region |
|
| Quoted passages from transcripts and open-access full texts |
Resources expose data outside the tool calls:
URI | Content |
| Any record as citable JSON — the same projection as its |
| A filtered export (CSV/JSONL for research items; CSV/JSONL/BibTeX/RIS/CSL-JSON for publications). The search tools return these links as |
| A schema.org |
Profiles and research workflows
AMIRA_TOOL_PROFILE=full is the default: 38 core tools, or 40 over HTTP.
research, discovery and visualization expose smaller documented subsets
(26/14/14 core tools respectively; HTTP adds search and fetch). Profiles are
fixed at startup; they reduce discovery cost, not access permissions. Tools
outside a profile are removed, and so are the apps that render them. See
src/toolProfiles.ts for the exact lists.
Typed ids work everywhere in either vocabulary (item: / research_item:,
pub: / publication:, section:, person:, organisation:, project:,
video:, podcast:, chronicle:), including the id of every get_* tool. Paged results
stop early, with response_limited: true and a correct next_offset, when a page
would exceed 40,000 characters — Claude Code moves larger tool results out of
the conversation. Error results carry the error as JSON text only. Structured
content travels only where a client reads it: on the tools with an output schema
and on those that render an app; elsewhere the result is its compact JSON text
alone, instead of the same bytes twice. Control and private-use characters are
scrubbed from every result, and a call that has not answered within 60 seconds
returns a deadline_exceeded error.
Use resolve_entity before graph traversal; pass its typed id unchanged to
get_entity_graph. Graph edges count distinct source records, separate each
corpus, and distinguish catalogue links from co-occurrence. types (for example
["person"]) keeps only neighbours of those types and applies before the bounds;
neighbour_types counts every neighbour by type either way. Neither co-occurrence
nor a shared subject establishes collaboration. Follow an edge with edge_id
and the returned snapshot_id for stable evidence paging. Graphs cap at 100 nodes,
200 edges and 42,000 JSON bytes, so check truncated.
get_text_passages takes 1–10 publication:ID (or pub:ID), video:ID,
podcast:ID or chronicle:ID identifiers. It returns at most 20 passages per page, original UTF-16
offsets and source citations; every match is reachable through next_offset
(scanned_matches_capped reports a document with more than 10,000 matches). These are extracted-text offsets, not
PDF page numbers or audio timestamps. On a curator server it also takes
research items and searches private texts (docs/curator.md). get_snapshot_changes requires two local
same-source generations; it reports available history instead of inventing a diff.
The ILAM full-text map
The full text of ILAM's journal African Music (item set 27724, about 1,000
articles from 1954 on) is private in Omeka, so the public API this server
crawls never carries it, and nothing here reads or quotes it.
DRE Visualizations
computed a map from it offline and committed only derived, public files: ids,
map coordinates, content groups, nearest-neighbour scores, per-article country
counts and aggregate word counts per year. The crawl fetches two of them at a
pinned release tag (v2.48.0, FULLTEXT_SOURCE in
src/fulltextMaps.ts), validates their shape, keeps only
the declared fields, and stores them beside the snapshot as
fulltext_maps.json. If GitHub is unreachable, the snapshot ships without the
map and its surfaces answer fulltext_map_unavailable. Every result is filtered
to research items present in the snapshot and filed in the item set, and cites
them by amira_url.
Surface | What it adds |
| For an article on the map: |
| The same neighbours, with the subjects, people, countries and formats they share |
| Articles whose full text names a country at least three times; each row carries |
| The groups with sample articles, the countries named across the journal, a group's articles ( |
Limits, stated in every response: group names are AI-generated (Claude Opus
5.5, from the titles of each group's articles) and experimental; judge a group
by its articles. Neighbour scores sit in a narrow band (about 0.90 to 0.97), so
ranks say more than raw values. Countries come from a gazetteer, with three
mentions minimum and journal addresses excluded; a mention is not a subject.
Word counts cover words found in at least ten articles, single word forms
without stemming; years with few words are marked sparse. 657 articles are on
the map: articles without full text, and those excluded as shared section text,
journal furniture or under 300 words, are not. These surfaces need the
descriptive exposure level. Searching passages of the text itself is a
separate decision, with ILAM and Rhodes University, and is not offered on the
public server; only the internal curator server, which already serves the text
to curators, searches it (docs/curator.md).
Example questions it can answer
You ask… | The model uses… |
"What does the collection hold on Islam?" |
|
"Show me all the French-language items" |
|
"What has Ulli Beier contributed?" |
|
"Which items come from Nigeria?" |
|
"What does AMIRA hold from Côte d'Ivoire?" |
|
"What has been added since September?" |
|
"Which African Music articles write about Ghana, and when?" |
|
"How did African Music use the word kwaito over time?" |
|
"Which articles are closest in content to this ILAM article?" |
|
"Which Lagos items have digitised images?" |
|
"Give me all Islam-related items as a spreadsheet" |
|
"What audio recordings are in the ILAM collection?" |
|
"In which talks does anyone discuss decoloniality?" |
|
"Which cluster publications discuss migration control — and what do they actually say?" |
|
"How many French-language publications are there, and of which types?" |
|
"Export the French-language bibliography for my reference manager" |
|
"Which journals does the cluster publish in?" |
|
"What themes travel with Architecture across projects?" |
|
"When was this photograph taken?" |
|
"Give me a citation for this item — and the BibTeX" |
|
"Which decade does the collection cover most?" |
|
Companion skill
A research-workflow skill ships in .claude/skills/amira-mcp/:
cluster context, a query workflow, a tool-by-task map, the citation discipline, and coverage caveats.
Install it either way:
Download
amira-mcp-skill.zipfrom the releases page and unzip it into your Claude skills directory (e.g.~/.claude/skills/) — it expands to~/.claude/skills/amira-mcp/.Or copy the
.claude/skills/amira-mcp/folder from this repo there.
…or let the server hand it over (Skills over MCP)
Official extension; host support varies. SEP-2640 is now Final. The server follows the published Skills extension, including SHA-256 digests and byte sizes for every file. The zip above remains available for clients without extension support. The research tools and citation contract work either way.
The server also serves that same skill over the connection, following the
SEP-2640 extension
(io.modelcontextprotocol/skills). Nothing to download and nothing to keep in sync: a host that
implements the extension discovers the skill on connect, and the copy it gets is the one built into
the running server rather than a zip that may predate the tool surface it describes. It is the only
route that reaches the remote HTTP surface — ChatGPT, Claude.ai connectors and the APIs have no
local skills directory.
Method | What it returns |
| The catalog: |
| One skill by URI, to refresh digests without re-listing |
| Any single file — |
| One directory level at a time ( |
Cost when unused: near zero. Skill text is never injected into any tool description, so the
tools/list payload — the part re-sent every turn — is byte-identical whether or not a host
supports the extension. The instructions add one sentence naming skill://amira-mcp/SKILL.md, and
resources/list names every skill file with a title and a one-line summary, so a host without the
extension (Claude Desktop, Claude Code) can still find the workflow and its three references and
read them with resources/read. Disclosure timing stays a host decision; the reference files load
only when something actually reads them.
Set AMIRA_SKILLS=0 to drop the capability and the three methods entirely.
Install (end users)
Download amira-mcp-server.mcpb from the
releases page
and double-click it. Claude Desktop shows an install dialog; click Install.
No further configuration is required. The latest tagged release carries the
current data; the rolling data-latest pre-release always tracks the freshest
site snapshot.
Curator access in Claude Desktop
Authorised AMIRA curators can see private records in Claude Desktop with the same extension (#26):
Install the
.mcpbas above.Open Settings → Extensions → AMIRA → Configure.
Paste your personal token into Curator token. The field is masked and the token is kept in the operating system's keychain.
Save, then disable and re-enable the extension (or restart Claude Desktop).
The extension then relays to the AMIRA curator server
(https://data.africamultiple.uni-bayreuth.de/curator/mcp) instead of serving
the bundled snapshot. It stores nothing private on your computer, and it never
falls back to public data: a rejected or revoked token, or an unreachable
server, shows up as an error. Clear the field and restart the extension to
return to the public dataset. Tokens are issued and revoked centrally by the
AMIRA team, so a revoked token stops working on every device at once. Other
clients: docs/curator.md.
Use it from ChatGPT, the API, or any remote client
The .mcpb is the local, offline option for Claude Desktop. The same server can
also run as a remote Streamable HTTP endpoint — one HTTPS URL that ChatGPT,
Claude (web + desktop remote connectors), the OpenAI and Anthropic APIs, Cursor,
VS Code and other clients connect to by pasting a URL (no download, always-fresh
data). The remote surface serves the same 38 tools plus the
OpenAI-compatible search / fetch tools for ChatGPT research integrations (40
total). Access is unauthenticated — the data is public and read-only.
search takes plain keywords (matched term-by-term, not as an exact phrase),
with optional limit and types to keep the result set tight, and returns
ranked hits across research items, the bibliography (reaching into publication
full text), podcasts, videos, projects and research sections. The url on
search results and fetch documents is
always the AMIRA/Omeka public record page; DOI, YouTube/watch, and podcast/listen
URLs are kept as secondary metadata/text links. fetch returns one record's full
text by the id search hands back — for videos and podcasts the transcript is omitted by default
(metadata + description only, since a full one can run to tens of thousands of
characters), and include_transcript=true pulls it in — paged with
transcript_offset / transcript_max_chars (the same names get_video /
get_podcast use). Publication full text works the same way
(include_fulltext=true, paged with fulltext_offset / fulltext_max_chars,
matching get_publication), and max_chars caps the whole text body. The
appended window is sized against what max_chars leaves after the metadata
header, so *_returned_chars is exactly what landed in text and the next page
starts at offset + returned_chars with no gap.
npm run build && npm run start:http # → http://localhost:8787/mcp
# or, self-contained, via Docker:
docker build -t amira-mcp . && docker run -p 8787:8787 amira-mcpEndpoints: POST /mcp (the MCP endpoint), GET /healthz and GET /metrics
(request count and p50/p95 latency of the last 256 /mcp requests, rate-limit
buckets, refresh state). Bind with PORT / HOST. Every release also publishes
the tested image, with build provenance, as
ghcr.io/am-digital-research-environment/amira-mcp-server:<version> (and
:latest), so a deployment updates by pulling a tag.
ChatGPT → enable Developer mode under Settings → Security and login, then add your server URL from ChatGPT Plugins. Research integrations use
search+fetch; see the current OpenAI setup guide.Claude (web or desktop) → Settings → Connectors → Add custom connector →
https://<your-host>/mcp.OpenAI API (Responses) — point the
mcptool at the endpoint:{ "type": "mcp", "server_label": "amira", "server_url": "https://<your-host>/mcp", "allowed_tools": ["search", "fetch"], "require_approval": "never" }
Deploy (self-hosted, e.g. alongside the amira site)
The multi-stage Dockerfile crawls a fresh snapshot at build time
and runs the self-contained bundle (no node_modules at runtime). On a Linux
host you can equally run it under systemd behind a reverse proxy:
# /etc/systemd/system/amira-mcp.service
[Service]
ExecStart=/usr/bin/node /opt/amira-mcp/server/http.js
Environment=PORT=8787 HOST=127.0.0.1 AMIRA_LIVE_REFRESH=true
Restart=always
User=www-datalocation /mcp { proxy_pass http://127.0.0.1:8787/mcp; proxy_buffering off; client_max_body_size 64k; }proxy_buffering off keeps the Streamable-HTTP/SSE responses flowing. The refresh uses AMIRA_SITE_BASE (the public HTTPS API by default), even when
co-located with Omeka. It performs a full crawl when changes are detected;
co-location does not eliminate API load. The server caps request bodies at 64 KiB
and rate-limit state at 10,000 clients. Configure connection, request-rate and
concurrency limits at the reverse proxy for public deployments; the in-process
limiter is a courtesy control. Shutdown cancels refresh work and gives HTTP
connections a ten-second drain window.
For a build that consumes a previously reviewed data/ snapshot without calling
Omeka during the build:
docker build --build-arg SNAPSHOT_STAGE=bundled -t amira-mcp .The default SNAPSHOT_STAGE=fetch still crawls fresh data. Both stages validate the
snapshot. The image pins its base digest and applies Debian's security updates
on top of it; its runtime stage carries no npm. npm ci uses the committed
lockfile.
Curator mode (internal, read-only)
The same image can run a second, internal endpoint for AMIRA's developers and
data curators that also serves private records and private values (#26):
AMIRA_ACCESS=curator. It crawls the Omeka API with a service key
(AMIRA_OMEKA_KEY_FILE), fetching over AMIRA_API_BASE (e.g. the internal
http://web/api) while every link keeps the public AMIRA_SITE_BASE, serves over HTTP only, and admits only holders of a
personal token listed by SHA-256 hash in AMIRA_MCP_TOKENS_FILE; deleting a
curator's line revokes them within seconds, and each request is audited by name.
Private records carry visibility: "private" and an admin_url instead of
amira_url; private values sit in a separate restricted block, including the
private ILAM OCR full text, which becomes searchable and readable. The cache
(AMIRA_CACHE_DIR, on tmpfs) is partitioned by access mode, each mode refuses
the other's snapshot, and data unconfirmed for 24 h is refused. Omeka answers
an unknown key with the public data rather than an error, so every crawl and
refresh first requires a keyed authentication probe (items?is_public=0) to
return private items; when it does not, or Omeka answers 401/403, the server
drops the data and wipes the cache. The service account needs view-all
(a reviewer for now). The server refuses to start when any
of this is missing, and a public server refuses a key. Generate a token with
node server/tokenCli.js <name>. Curators connect with a header-capable
client, or from Claude Desktop through the .mcpb relay. Configuration,
revocation, client setup, cache handling and what "private" covers:
docs/curator.md.
Develop / rebuild
npm ci
npm run fetch-data # crawl the public Omeka API -> ./data snapshot (~1 min)
npm run typecheck # tsc --noEmit
npm run build # esbuild -> server/{index,http,fetchCli,lib}.js
npm test # unit tests: transform fixtures, folding, snapshot + store lifecycle,
# and the full tool layer against a fixture snapshot via
# InMemoryTransport (offline)
npm run test:live # integration tests against the live API (network)
npm run smoke # test/smoke/stdio.mjs: spawn the stdio server, exercise every tool offline
npm run smoke:http # test/smoke/http.mjs: spawn the HTTP server on a free port: search/fetch +
# parity, CORS preflight for both protocol revisions, the rate limiter
npm run weigh # token budget report (needs ./data — run fetch-data first)
npm run benchmark # offline latency baseline against ./data (30 warm samples per query)
npm run lint # Biome, lint rules only (biome.json)
npm run evaluate-retrieval -- --judgments judgments.json --output report.json
# precision, recall, nDCG and MRR at k against researcher-authored judgmentsToken budgets
Context is the scarcest resource a client has, so both halves of what this server
spends are measured and gated (scripts/weigh.mjs, estimating tokens as
bytes/4 — comparable to itself, not to a billing statement):
what | budget | drift | |
Surface | the | 14,000 tok per full-profile transport | fails over 3 % |
Responses | each tool called at its maximum limit | 20,000 tok and < 45,000 characters per call | warns over 10 % |
No tool description is derived from the snapshot, so the surface is a pure
function of the code: test/unit/budget.test.mjs gates it offline against no
data at all, and asserts that the empty-store measurement still matches the
baseline recorded against the full snapshot. Response weight needs real data, so
npm run weigh -- --check runs in the smoke job instead. Drift there is only a
warning — a routine npm run fetch-data must not red the build — while the
absolute cap (Claude Code truncates tool results at 25,000 tokens) is fatal, as
is any probe whose call failed, since a structured refusal is ~60 tokens and
would otherwise sail under every ceiling.
Version 1.18 deliberately raises the full-profile ceiling to 14,000 estimated
tokens to accommodate six tools and useful output schemas. Smaller profile gates
are 10,100 (research, raised from 10,000 for resolve_entity's near-miss
fields), 6,500 (discovery) and 9,500 (visualization). The guidance-off
surfaces of the evaluation ablation are measured and gated like the shipped ones.
The committed baseline records the exact surface size,
text bytes, serialized wire bytes (text and structured content both count) and the
snapshot it was measured on. Every response must also stay under 45,000 characters:
Claude Code stores any tool result over 50,000 characters in a file instead of the
conversation. Paged results and the graph are byte-bounded to fit.
When a change legitimately grows either number:
npm run weigh -- --update # rewrites test/token-baseline.jsonCommit the diff. That is the point of the file: the cost of a new tool or a richer result summary lands in code review as a number instead of arriving unnoticed.
Pack the extension:
npm run prepack-mcpb # clean + typecheck + build + test + smoke
npm run validate:manifest
npm run pack-mcpb # -> amira-mcp-server.mcpbscripts/census.mjs re-runs the property census behind the field mapping
(scripts/census-report.json, generated on 10 June 2026 and not rerun since,
so it predates later template and property changes) — rerun and diff it if the
instance's templates change. The design decisions behind it are in ROADMAP.md; CHANGELOG.md
records each release.
Continuous delivery
Three GitHub Actions cover pull requests and distribution (the two distribution workflows crawl the public API — no credentials):
CI (
.github/workflows/ci.yml) — on pull requests and pushes tomain: type-checks and lints once, then runs the offline unit suite (including the tool-surface token budget) on Node.js 22.0.0, 22, 24 and 26 on Linux and Node.js 26 on Windows, then, on a crawled snapshot, exercises both MCP transports, replays the evaluation set's identity questions, weighs every tool's response at its maximum limit, and validates the MCPB manifest. zizmor lints the workflows, composite actions and Dependabot configuration. The complete dependency audit fails on high or critical advisories. The packed.mcpbis then unpacked on Windows and macOS and smoke-tested there, so CI runs the bytes users install. A separate container job builds an offline fixture image, checks health and fails on any fixable high or critical vulnerability Trivy finds in it. Windows CI also packs a fixture extension and checks its file list. A non-blocking job runs the official MCP conformance suite against the HTTP server. Actions are pinned to commit SHAs; every job has a timeout.Release (
.github/workflows/release.yml) — on a pushedv*tag: refuses a version already published on GitHub or the MCP Registry (released bytes are never replaced; fix a release with a new version), checks the tag againstpackage.json, crawls a fresh snapshot, runs unit, live and smoke tests, packs the.mcpb, zips the companion skill (amira-mcp-skill.zip), builds the image, fails on any fixable high or critical vulnerability in it (Trivy), and writes CycloneDX SBOMs of the image and of the bundle's runtime dependencies, in a read-only job that records the SHA-256 of each. The publish job verifies those bytes, repeats the guard, attests their build provenance and the bundle's SBOM, and creates the release as a draft with the version'sCHANGELOG.mdsection as its notes before making it public. Non-blocking jobs push the tested image to GHCR with provenance and SBOM attestations and stamp and publishserver.json(a placeholder in git) to the MCP Registry with a pinned, checksum-verified publisher.Image scan (
.github/workflows/image-scan.yml) — weekly and on demand; scans the publishedlatestimage with Trivy and keeps one issue labelledimage-vulnerabilities, assigned to the maintainer, open while it has fixable high or critical vulnerabilities. It comments when the findings change and closes the issue after a clean scan.Refresh data snapshot (
.github/workflows/refresh-data.yml) — weekly and on demand; rebuilds only when the transformed snapshot content hash changes, including item-set and vocabulary changes, updating the rollingdata-latestpre-release.
Publishing from Actions requires a writable token. If the organization disables write permissions for the default workflow token, either (a) enable Read and write permissions under Organization → Settings → Actions → General → Workflow permissions, or (b) add a repo/org secret
RELEASE_TOKEN(a PAT or GitHub App token withcontents: write). The workflows usesecrets.RELEASE_TOKENwhen present and fall back to the default token.
Semantic neighbours
get_similar_items finds records whose catalogue descriptions read most alike,
across research items, publications, videos, podcasts, projects and research
sections. The vectors come from the versioned
DRE Visualizations
releases semantic-embeddings-v1-<build>: google/embeddinggemma-2, 768
dimensions, L2-normalised, built offline from the public API only (title,
abstract or description, subjects and places; never full text).
The crawl downloads the newest release (or the one AMIRA_SEMANTIC_RELEASE
pins), verifies the model, dimensions, normalisation, row count, byte length,
SHA-256 and row norms against its manifest, and refuses any mismatch, so two
vector spaces never mix. It then computes, for every record present in the
snapshot, its ten closest records of each type, and stores those
(semantic_neighbours.json), never the ~15 MB of vectors: no model and no
vector runs at request time. Records absent from the snapshot are dropped
before ranking, and lists are filtered again at load, so a neighbour is always a
record the snapshot can cite. When no release verifies, the crawl keeps the
neighbours already served. A new release is picked up by the next crawl, which
a change on the Omeka site or the weekly forced crawl
(AMIRA_FULL_REFRESH_HOURS) triggers: a release alone does not start one. get_data_quality reports the release and its
coverage per type: records with neighbours, low-signal records (too little
own text, excluded by design) and records the build predates.
Scores are cosine similarities of descriptions: similar wording is not
evidence of a documented relation. So every neighbour is explained from the
catalogue links: shared names up to three subjects, places (a place shares
its country), people or the project the pair also shares (research sections
are too broad to count), with shared_counts when there are more, and basis: "wording_only"
marks a pair that shares none of them. get_research_item, get_publication,
get_podcast, get_video and get_project add the same five neighbours as a
similar block with include_similar: true; a record without neighbours
carries the reason there instead of an error. find_related entity_type=record
pivots on the same neighbours: the projects, sections, subjects, people,
countries and formats that the seed's 20 closest records share, counted per
corpus.
The same vectors give get_semantic_map: the crawl groups the records by
seeded spherical k-means (about a hundred per group, at most 30 groups, low-
signal records left out) and stores each group's member ids, nearest the
centre first. The groups are unnamed on purpose. The tool describes each one
by its type mix and its most frequent subjects, countries and projects, with
the records nearest its centre, so a group is characterised from its contents
rather than given an invented label. Group ids are renumbered per build
(1 = the largest).
Configuration (environment / extension settings)
Env var | Extension setting | Default | Meaning |
| Refresh data from the live site |
| Probe + refresh the snapshot from the public API at startup and on the periodic interval |
| — |
| When live refresh is on, repeat the freshness probe this often while the server is running; set |
| — |
| Force a complete crawl after this snapshot age even if item signatures are unchanged; minimum 1 hour |
| — |
| Corpus-vector release for |
| — |
|
|
| Refreshed-data cache directory |
| Where refreshed snapshots are stored |
| Site base URL (advanced) |
| Base for citations + refresh ( |
| — |
| Where the crawl and refresh fetch the API from: the full API URL including |
| — |
| Omeka site slug used in |
| — | bundled | Override the bundled snapshot path (dev) |
| — | — | Tests only: fetch the full-text map and the corpus-vector releases from |
| — |
| Benchmark experiments only: restrict which metadata the tools expose (see below) |
| — |
| Benchmark experiments only: |
| — | on | Serve the companion skill over the finalized SEP-2640 extension. |
| — |
| Port for the remote HTTP transport ( |
| — |
| HTTP bind address; set |
| — | — | Namespaced alternatives to |
| — |
| Comma-separated browser Origin hostnames or URLs allowed to call the HTTP endpoint. Server-to-server clients, which omit |
| — |
| Requests/minute per client on |
| — |
| Attribute requests to the address the reverse proxy observed: |
| — |
| Number of trusted proxies in front of the server, for reading |
| — | unset | HTTP only: require |
| — | unset | HTTP only: read that token from a mounted secret file instead |
| — |
|
|
| — | unset | Curator mode only: file with the Omeka service key ( |
| — | unset | Curator mode only: personal tokens, one |
| — |
| Curator mode only: first timer-driven retry after a transient failure leaves no data (the first crawl failed); doubles up to five minutes |
| — |
| Curator mode only: the keyed request that must return a non-empty array (proof that the key is accepted and has view-all) before any crawl or refresh |
| Curator token | unset | stdio / |
| Curator server URL (advanced) |
| The endpoint the relay forwards to. Must be |
| — |
| Curator mode only: refuse data Omeka has not confirmed for this long. Curator mode also requires |
Snapshot layout and recovery
The cache lives under AMIRA_CACHE_DIR/<API identity hash>/ (curator mode hashes
the access mode in too, so the two never share a directory). active.json names
the current immutable generations/<uuid>/ directory and two previous generations.
Unreferenced generations have a 24-hour cleanup grace period. Existing flat
snapshots and a same-source legacy cache/current remain readable; the first new
publication migrates a flat destination into generation history. npm run fetch-data
also writes the generation layout to data/; scripts must use loadSnapshot
rather than assuming data/manifest.json is active. A generation holds one JSON
file per corpus, manifest.json (written last), and, when the crawl reached
GitHub, fulltext_maps.json with the ILAM full-text map; the manifest's
fulltextMaps entry names its tag and article count, and a load fails if the
two disagree.
A crashed writer can leave writer.lock. Stop all processes using that cache,
confirm no writer is running, then remove that one lock file and restart. The
server deliberately never guesses whether an old lock is safe to steal. Failed
refreshes leave the last usable data available. /healthz, overview and data
quality report refresh attempt/success times, in-flight state and failure class.
Retries apply only to transient upstream failures, honor bounded Retry-After,
and abort after a 15-minute refresh deadline or shutdown. Probes cannot provide a
transactional Omeka snapshot; periodic complete crawls remain necessary.
Metadata-exposure levels (benchmark experiments)
AMIRA_EXPOSURE lets an evaluation run the same tasks under graded metadata
visibility — the "metadata mediation" condition of LLM-access studies. It is an
experiment flag, not an end-user setting; the default (full) is the normal
server. Existence flags (has_transcript / has_fulltext) stay visible at
every level; only content and relations are gated, and refusals are structured
errors (exposure_restricted / text_access_disabled) so a model can say why
it cannot answer rather than hallucinating.
Level | The model sees |
| Titles, types, dates, URLs, media flags. Keyword search matches titles only; entity/facet/relation tools and structured filters are refused |
| + descriptions, abstracts, tables of contents (searchable too) |
| + subjects, places, people, projects, sections, collections, venues — all filters and entity tools |
| + transcripts and publication full text (default) |
Guidance ablation (benchmark experiments)
AMIRA_GUIDANCE=off serves the same operations without the curatorial guidance,
so an evaluation can measure what that guidance contributes. Like
AMIRA_EXPOSURE it is an experiment flag; the default (on) changes nothing.
The tool list is built when the server starts, so set the variable before
starting it and restart to change it.
Channel |
|
|
Server instructions | sent on | none |
Tools | name, title, description, schemas with parameter descriptions | same names, input and output schemas (types, enums, bounds, required fields), annotations and app |
Errors |
|
|
Results | data, plus | the same data without them |
Prompts, companion skill | registered and declared | neither |
Resources | titles and descriptions | URIs and MIME types only |
The tool list costs 12,223 estimated tokens per turn on stdio with guidance and
8,535 without (HTTP: 13,116 and 9,046); the instructions add ~500 once per
session. npm run weigh measures both and the baseline records them.
Architecture
Pure in-memory typed records. The Omeka JSON-LD is transformed once at build time (
src/transform.ts, evidence inscripts/census-report.jsonof 10 June 2026); the runtime loads compact records and indexes them at startup. No native bindings; the esbuild bundles are self-contained.Offline-first with atomic refresh. Bundled snapshot + locked generation publication; the freshest manifest wins at startup (an old cache can never shadow a newer bundled snapshot).
Citations are uniform: every entity is an Omeka item, so every record carries
amira_url = <site>/s/amira/item/<o:id>.Accent-insensitive matching everywhere (
src/text.ts). The collection is francophone-Africa-heavy and its authority records are not consistently accented against the free text — "Côte d'Ivoire" is the subject heading while item titles carry "Cote d'Ivoire". Every keyword comparison folds both sides (NFD, drop combining marks, lowercase, and map curly quotes, dashes and the ligatures œ/æ/ß to plain forms), so the answer no longer depends on which spelling the caller guessed. Folds of large texts are memoised and dropped when a refresh replaces the snapshot.Interactive results (MCP Apps). Seven tools carry
_meta.ui.resourceUripointing at onetext/html;profile=mcp-appresource,ui://amira/app.html, so hosts implementing theio.modelcontextprotocol/uiextension (Claude, Claude Desktop) render the result inline. Every other client ignores the_metaand gets exactly the same JSON.Tool
View
Renders
get_collection_overviewoverviewStat tiles + ranked breakdowns by university, section, resource type and language
list_yearstimelineHistogram of items per year or decade
list_research_sectionssectionsGantt of the sections across the AM 1.0 / AM 2.0 funding phases, with a "now" marker
find_relatedrelatedRadial co-occurrence hub: the seed at the centre, one labelled sector per relation type
get_entity_graphgraphSector graph by entity type, type chips, selectable spokes with their evidence, keyboard navigation
list_locationsmapOffline map, country dropdown, place table and item evidence
search_publicationsbibliographyFilterable bibliography (language dropdown, author suggestions) and selection export
One page renders every view: it picks the view from the host's
toolInfo, or from the result's shape when a host sends none, so the Apps SDK ships once rather than seven times. The page is 181 KB, its gzip-compressed script 471 KB once decoded (it was 4.7 MB across seven pages), and a unit test holds it under 300 KB and 500 KB.The modules live in
src/ui/:shell.tsholds the design tokens,bridge.tsbundles the official Apps SDK, each view module supplies its own CSS and names its script insrc/ui/views/(plain browser JavaScript, linted and typechecked withtsconfig.views.json, beside the shared helpers of_shared.jsand the router of_router.js), andpage.tsassembles them at build time. The page loads nothing from the network — no scripts, styles, fonts or tiles — so it needs no_meta.ui.cspgrants and runs in the strictest sandbox. App controls call an allowlisted set of read-only tools through the host; filter dropdowns are filled the same way, so their option lists never reach the model. Citation links and file downloads also go through host APIs. Every visual has a table or text alternative.The bibliography, map and graph share their current selection with the model — filters, selected records, the opened place, the graph's chips and spoke, each record with its
amira_url— on hosts that acceptui/update-model-context. Updates are bounded, sent one at a time with the newest winning, and never start a turn. On hosts that accept app messages, "Ask about this selection" sends a question with its own snapshot. Record titles travel as data, never as instructions. See app development and provenance.Colours come from the DREVisualizations Omeka module's theme (
--primary/ the Africa Multiple brand palette), so a chart in the chat and the same chart on the AMIRA site read as one system, and were validated against those surfaces rather than eyeballed — light#007a50on#fdfcfa, dark#35a87don#1b211e(the theme's own#3fb488sits just outside the dark lightness band, so the app steps one down). Every chart is single-series, with the category on the axis label, so one accent is correct and no legend is needed. The co-occurrence hub would nominally want six hues for its six relation types, but no six-hue set from the brand palette survives all-pairs CVD separation (the best candidates bottomed out at ΔE 2.4 under deutan), so identity there is carried spatially — one labelled sector per relation type — which also survives greyscale, print and forced-colors.
Protocol posture
Verified against the current specification and TypeScript SDK documentation on 6 October 2026. The server speaks MCP 2026-07-28 on both transports, and still answers 2025-era clients unchanged.
It runs on the v2 TypeScript SDK — the scoped packages
(@modelcontextprotocol/server, /node, /client), not the frozen
@modelcontextprotocol/sdk v1 monolith. Two things are worth knowing if you
work on the entry points:
The modern era is opt-in.
SUPPORTED_PROTOCOL_VERSIONSis the legacyinitializeladder and stops at 2025-11-25; the SDK keeps the 2026 string internal on purpose.createAmiraServernames the revision itself insupportedProtocolVersions, which is what registersserver/discover— without it that method answers-32601.The era is owned by the entry, not the transport.
serveStdio(factory)andcreateMcpHandler(factory)decide the era per connection/request and pin an instance from the factory. Connecting a bareStdioServerTransportorNodeStreamableHTTPServerTransportby hand serves the 2025 era only.
Concretely on the wire: server/discover advertises ["2026-07-28"], results
carry resultType, and the cacheable results carry real ttlMs / cacheScope
(1 h public on tools/list, resources/list and server/discover; 24 h on
resources/read, whose ui:// app HTML is immutable per build) rather than the
SDK's conservative { ttlMs: 0, cacheScope: "private" } default. Back-compat is
the handler's legacy: 'stateless' default, which answers 2025-era traffic with
a fresh instance per request — the same shape this server always had.
The deprecations of that revision cost nothing here: Roots, Sampling, Logging
and Elicitation are all unused, logging goes to stderr, and tool order is
deterministic (registration order). CORS accepts both generations of headers
(Mcp-Session-Id/MCP-Protocol-Version and Mcp-Method/Mcp-Name/X-Mcp-Header).
Citing this software
If this server is part of how you found or analysed AMIRA material, please cite
it. The repository carries a CITATION.cff, so GitHub's Cite
this repository button will render BibTeX and APA for you.
@software{madore_amira_mcp_server,
author = {Madore, Frédérick},
title = {{AMIRA MCP Server}},
year = {2026},
publisher = {Africa Multiple Cluster of Excellence, University of Bayreuth},
url = {https://github.com/AM-Digital-Research-Environment/amira-mcp-server},
license = {MIT}
}Cite the data separately from the software: individual records are citable
by their amira_url (https://data.africamultiple.uni-bayreuth.de/s/amira/item/<id>),
which is what every tool result returns for exactly this reason.
Credits and funding
Built and maintained by the Digital Research Environment (DRE) of the Africa Multiple Cluster of Excellence, University of Bayreuth — the Cluster's digital infrastructure unit, which designs and runs the data systems behind AMIRA. Curation and description of the underlying records are joint efforts with partners at the Africa Multiple Research Centres (Université Joseph Ki-Zerbo, Rhodes University, University of Lagos, Moi University) and Federal University of Bahia.
Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany's Excellence Strategy — EXC 2052/1 — 390713894 (Africa Multiple: Reconfiguring African Studies).
License
MIT — see LICENSE. See also CONTRIBUTING.md and SECURITY.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Multi-engine scholarly research server for search, traversal, full text, and reading lists.
Hosted research subset: check citations, catch fake/retracted papers, search OpenAlex & PubMed.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Access the OpenAlex academic research catalog — 270M+ publications.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables users to create frozen, auditable snapshots of selected Markdown or text-layer PDFs and perform read-only, verifiable local searches with SQLite FTS5/BM25, preserving source hashes, schemas, and page/line anchors.82Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides read-only search and context-pack creation over a local source library, letting AI assistants retrieve relevant excerpts and audit cited quotations.20MIT
- FlicenseNot gradedqualityCmaintenanceEnables agents to search a local, fully offline personal document library (Markdown/txt/PDF/docx) via SQLite FTS5 trigram search with subject-terminology expansion, returning every hit with its domain, document title, section path, and page or offset provenance. It also exposes domain statistics, incremental ingestion, and document deprecation as tools, alongside a read-only, runtime-persona-scoped ask/coverage mode.-
- AlicenseNot gradedqualityBmaintenanceEnables Claude to query a locally imported collection of PDF, TXT, and MD files via SQLite FTS5 full-text search (including Chinese), and to browse notebooks, source files, and individual passages. Every search result carries traceable citations such as filename, page number, line number, or timestamp.MIT