AMIRA — Africa Multiple Research Data

AMIRA MCP 服务

这是一个只读的 Model Context Protocol 服务，服务于 非洲多元互动研究地图集（AMIRA）。该研究数据平台隶属于拜罗伊特大学的 非洲多元卓越集群。AMIRA 发布于集群的公共 Omeka S 网站： data.africamultiple.uni-bayreuth.de。

AMIRA 由集群的数字研究环境（DRE）构建和维护，这是负责数字基础设施的部门。DRE 设计、构建并维护数据系统，连接全球各地的研究人员，包括非洲多元研究中心（AMRCs）及其合作机构。AMRCs 的合作伙伴包括约瑟夫·基-泽博大学、罗德斯大学、拉各斯大学和莫伊大学，双方共同开展数据整理和描述工作。拜罗伊特负责托管协调性 DRE 基础设施和元数据层。巴伊亚联邦大学是重要合作伙伴，并非 AMRC。

默认情况下，数据分散存储：数据保留在本地存储库中，而拜罗伊特负责托管指向这些数据的元数据层。研究数据可以被发现，无需迁移。高质量的元数据能让研究人员的数据更易于发现，也让他们的工作更广泛地为同行所知。

本服务提供 AMIRA 的项目、专题研究板块、约 4,000 项数字化研究条目、人员、机构、团体、馆藏、集群的书目（支持全文检索）（全文从开放获取 PDF 中提取）及其期刊、带有文字稿的播客节目，以及集群的 YouTube 视频（支持文字稿检索）——这些内容可通过 33 个 LLM 可查询的核心工具、五个研究工作流提示词，以及用于引用记录和批量导出的资源访问。借助一个 MCP 接口，客户端可以跨记录探索，以及浏览将这些记录联系起来的地点、语言和主题。

每条记录都包含一个 amira_url——即其在 Omeka S 网站上的公开页面（…/s/amira/item/<id>）——因此，研究结果可以通过链接引用回溯至来源。 AMIRA 专注于集群的研究数据。如需了解非洲多元卓越集群的新闻、活动和一般信息，请访问 africamultiple.uni-bayreuth.de。

**截至 2026 年 10 月 6 日的覆盖情况：**3,975 项研究条目（其中 1,419 项含数字化媒体）、93 个项目、555 篇出版物（其中 60 篇已提取全文）、87 种期刊、43 期播客、140 个视频，以及 3,085 个主题规范数据（其中 646 条为美国国会图书馆主题词）。这些数量是特定日期的快照；如需了解当前运行的服务实际包含的内容，请使用 get_collection_overview。请参阅出版物指南、了解各版本变更内容的变更日志，以及列出后续改进计划的路线图。

数据来源——以及为什么不需要其他内容

该服务是自包含且离线优先的。它从两个来源读取数据：

1. 打包在 .mcpb 中的完整数据快照——构建时从公开的 Omeka S REST API 抓取，并转换为精简的类型化记录，因此该服务无需任何设置即可完全离线运行。
2. （可选，默认启用） 通过 HTTPS 访问 Omeka S API。启动时和每天，探测程序都会比较项目和项目集的修改签名及总数。检测到变化后会触发完整抓取；每周强制抓取一次，也能捕获仅涉及词汇表的编辑。写入锁、不可变的代次和原子指针可在刷新失败时保留此前可用的快照。API 来源和安装路径用于划分缓存；在该站点的引文 URL 下提供记录之前，它们必须与清单一致。

最终用户无需 API 密钥、凭据或 VPN——这些数据与公开网站使用的数据相同，都是公开发布的。

工具

先调用 get_collection_overview 确定数据范围，然后再深入查看。

工具	用途
get_collection_overview	整个馆藏的计数和分类统计，以及快照的时效性
search_research_items	按关键词查找条目（必须匹配每个词；短语请加引号）、主题、地点（感知层级）、国家（精确匹配，支持别名，例如 Côte d'Ivoire = Ivory Coast）、贡献者、项目、分区、大学、资源类型、格式/体裁、语言、年份、has_media、added_since / modified_since；`export=csv
get_research_item	单个条目的完整元数据（按 Omeka id 或带类型的 ID 查询）：带类型的日期、注明当时所属机构的角色、包含区域/国家层级关系的地点、作为关联机构呈现的来源信息、带类型的标识符、馆藏、相关条目、媒体文件和 IIIF 清单；此外还提供自动生成的引文，以及 BibTeX/RIS/CSL-JSON 导出（citation_format）
search_projects / get_project	按关键词或缩写、大学、分区、PI、成员、资助方查找项目；详情包括条目分类统计、热门主题和示例条目
list_research_sections / get_research_section	按主题划分的分区，包含资助阶段（AM 1.0 / AM 2.0）、PI、计数和项目；可按名称或 ID 查看详情
search_persons / get_person	查找人员（姓名顺序不限）；个人资料包含 GND 和其他规范标识符、项目及研究分区角色、条目、出版物、播客、视频和主要合作者，并附有说明如何解读计数的 coverage_note。若姓名无匹配结果，会返回近似匹配的 suggestions（“Rudigr Seeman” → Seesemann, Rüdiger）；get_person 会在其 not_found 错误中列出这些建议
list_institutions / get_institution / list_cluster_partners / list_groups	按名称、缩写或 ID 查找组织（机构、Africa Multiple 合作伙伴类别和研究组），以及其项目、人员和条目
list_subjects	按条目频次排序的主题标题，每项均标记为美国国会图书馆主题标题（附 id.loc.gov URI）或自由标签（`vocabulary=lcsh
list_locations	所有地点——国家和城市以单一扁平列表呈现（汇总层级）——按条目数排序，并附坐标和 Wikidata ID；可按国家、名称、near（半径）或 bbox 筛选
list_collections	按研究条目数排序的馆藏（条目集），附 IIIF 馆藏链接；可与 collection 筛选器配合使用
list_categories	分面值：格式/体裁、语言、资源类型
list_years	按年份或年代统计的研究条目日期直方图，可查看时间覆盖范围及覆盖最多的年份/年代
search_publications / get_publication	按作者、主题、语言、类型、刊物、年份、添加日期和全文可用性筛选书目；可搜索所有语言的摘要和提取的 PDF 文本。详情包含每篇摘要及其语言、关联规范档、会议/篇幅/访问权限/论文元数据。citation_format 可按页选择 BibTeX/RIS/CSL-JSON；export 会将全部结果作为单个文件提供链接
list_publication_facets	统计完整筛选后书目中按类型、年份、语言、主题、作者/编者或刊物划分的数量；结果已排序并分页
list_journals	该研究集群发表论文所涉及的期刊，按出版物数量排序，并附 ISSN 和国家；可与 venue 筛选器配合使用
find_related	跨实体发现：从主题/地点/人员/项目切入，查找共同出现的实体（包括出版物）
search_podcasts / get_podcast	研究集群的播客单集，支持搜索文字稿并可按语言筛选；详情提供时长、音频文件和生成文字稿的模型；文字稿文本需主动选择查看
search_videos / get_video	研究集群的 YouTube 视频——支持全文搜索文字稿（匹配片段；缩略图；详情页中的文字稿需主动选择查看）
resolve_entity	解析名称或带类型的 ID（任一词汇表均可：item:9902 = research_item:9902）；对同名实体和未协调的字面值分别返回候选项。若查询无法解析、未指定类型，或使用 type=person，则会返回人员近似匹配 suggestions
get_entity_graph	有界的一跳图谱，区分明确关联和共现，并分页呈现引用证据
get_text_passages	查找选定出版物/视频/播客记录中的段落，并提供原文中的精确偏移量
compare_collections	使用相同筛选条件、分母和缺失数据情况，对比 2–4 个项目或馆藏
get_data_quality	快照覆盖范围、缺失元数据和未解析引用的计数
get_snapshot_changes	分页查看同一实例保留的快照中新增、更新或删除的记录

提示词和资源

五个提示词打包了多步骤研究工作流。宿主会将它们显示为斜杠命令；其参数会根据快照自身的机构名称自动补全，并且每个提示词都会重申引用规则。它们通过 prompts/list 列出，因此不会增加每轮工具负载。

提示词	参数	工作流
literature_review	topic、year_from?、year_to?	围绕某一主题的分类、出版物、全文段落及相关研究数据
project_dossier	project	一个项目的团队、馆藏、时期、地点和关联
person_profile	name	对一个人的消歧、档案、图谱和出版物列表；呈现为 AMIRA 的记录，而非对该人的评估
place_report	place	一个国家、城市或地区的条目、项目、主题和时期
transcript_evidence	query	来自文字记录和开放获取全文的引述段落

资源会公开工具调用之外的数据：

URI	内容
amira://record/{kind}/{id}	任意记录的可引用 JSON——与其 get_* 工具返回的投影相同；kind 遵循 resolve_entity 的 id（research_item、publication、person、location、subject 等）
amira://export/{corpus}/{format}/{query}	筛选后的导出数据（研究条目支持 CSV/JSONL；出版物支持 CSV/JSONL/BibTeX/RIS/CSL-JSON）。搜索工具在使用 export 调用时会将这些链接作为 resource_link 返回
amira://dataset	对所提供快照的 schema.org Dataset 描述：数量、覆盖范围、许可组合、资助方以及引用方式

档案和研究工作流

AMIRA_TOOL_PROFILE=full 是默认配置：包含 33 个核心工具；通过 HTTP 时为 35 个。 research、discovery 和 visualization 会公开规模较小、文档齐全的子集 （分别包含 22/12/14 个核心工具；HTTP 另加 search 和 fetch）。配置档案在启动时固定；它们减少发现成本，而非访问权限。档案之外的工具会被移除，渲染这些工具的应用也会一并移除。确切列表请参阅 src/toolProfiles.ts。

类型化 id 在两种命名形式中均可使用（item: / research_item:、 pub: / publication:、section:、person:、organisation:、project:、 video:、podcast:），包括每个 get_* 工具的 id。如果分页结果超过 40,000 个字符，结果会提前停止，并返回 response_limited: true 和正确的 next_offset——Claude Code 会将较大的工具结果移出对话。错误结果仅以 JSON 文本形式携带错误信息。

遍历图谱前请先使用 resolve_entity；将其类型化 id 原样传给 get_entity_graph。图谱边按不同来源记录计数，区分各个语料库，并区分目录关联与共现。types（例如 ["person"]）仅保留这些类型的邻居，并在应用边界限制前生效；neighbour_types 无论如何都会按类型统计所有邻居。共现或共享主题都不能证明存在合作关系。使用 edge_id 和返回的 snapshot_id 跟踪一条边，以便稳定地分页获取证据。图谱最多包含 100 个节点、200 条边和 42,000 个 JSON 字节，因此请检查 truncated。

get_text_passages 接受 1–10 个 publication:ID（或 pub:ID）、video:ID 或 podcast:ID 标识符。它每页最多返回 20 个段落、原始 UTF-16 偏移量和来源引用；每条匹配结果都可通过 next_offset 获取（scanned_matches_capped 表示某文档的匹配数超过 10,000 条）。这些是提取文本中的偏移量，不是 PDF 页码或音频时间戳。get_snapshot_changes 需要两个来自同一来源的本地版本；如果有历史记录，它会报告可用历史记录，而不会编造差异。

它可以回答的问题示例

你问……	模型使用……
“馆藏中关于伊斯兰教的内容有哪些？”	list_subjects keyword=Islam → search_research_items subject=Islam
“显示所有法语条目”	search_research_items language=French（代码 fr/fra/旧版 fre 也适用）
“Ulli Beier 有哪些贡献？”	get_person name="Ulli Beier"（解析为 'Beier, Ulli'）
“哪些条目来自尼日利亚？”	search_research_items location=Nigeria（拉各斯条目也会计入——location 会沿地点层级查询）或 country=Nigeria（精确匹配：不包含 Niger）
“AMIRA 收藏了哪些来自科特迪瓦的内容？”	search_research_items country="Côte d'Ivoire"（权威记录中存储为 "Ivory Coast"；常见别名可以解析）
“9 月以来新增了哪些内容？”	search_research_items added_since=2026-09-01（或 search_publications added_since=…）
“哪些拉各斯条目有数字化图像？”	search_research_items location=Lagos has_media=true → 使用 get_research_item 获取文件和 IIIF 清单
“将所有与伊斯兰教相关的条目导出为电子表格”	search_research_items subject=Islam export=csv → 读取返回的 amira://export/… 链接
“ILAM 馆藏中有哪些录音？”	search_research_items project_id=37700 resource_type=Audio
“哪些演讲中有人讨论去殖民性？”	search_videos keyword=decolonial（匹配字幕稿内容，并标记 matched_in）
“该集群的哪些出版物讨论了移民管控——它们具体说了什么？”	search_publications keyword="migration control"（匹配提取的全文内容，并标记 matched_in）→ get_publication include_fulltext=true
“有多少法语出版物，分别属于哪些类型？”	list_publication_facets facet=type language=fr → search_publications language=fr
“导出法语书目，以供我的文献管理器使用”	search_publications language=fr citation_format=ris → 按 next_offset 获取后续内容；合并完整的 ris 记录
“该集群在哪些期刊上发表文章？”	list_journals（按出版物数量排序）
“跨项目来看，哪些主题常与建筑一同出现？”	find_related entity_type=subject value=Architecture
“这张照片是什么时候拍摄的？”	get_research_item → 类型化的 dates（创建／采集／发布／……）
“为这个条目生成引文——以及 BibTeX”	get_research_item → generated_citation + bibtex（文献管理器可使用 citation_format=ris/csl-json）
“馆藏覆盖最多的是哪个年代？”	list_years bucket=decade sort=count

配套技能

研究工作流技能位于 .claude/skills/amira-mcp/： 包含集群背景、查询工作流、按任务划分的工具指南、引文规范和覆盖范围说明。 可通过以下任一方式安装：

• 下载 发布页面中的 amira-mcp-skill.zip，并将其解压到你的 Claude 技能目录（例如 ~/.claude/skills/）——解压后会生成 ~/.claude/skills/amira-mcp/。
• 或复制此仓库中的 .claude/skills/amira-mcp/ 文件夹到该目录。

……或让服务提供技能（通过 MCP 提供技能）

官方扩展；主机支持情况各异。 SEP-2640 现已定稿。服务遵循 已发布的 Skills 扩展，其中包含每个文件的 SHA-256 摘要和字节大小。对于不支持该扩展的客户端，仍可使用上方的 zip。研究工具和引用约定无论哪种方式都适用。

服务也会通过连接提供同一技能，遵循 SEP-2640 扩展 （io.modelcontextprotocol/skills）。无需下载，也无需保持同步：实现了该扩展的主机在连接时会发现此技能，并获取内置于运行中服务的版本，而不是可能早于其所描述工具界面的 zip。这是唯一能访问远程 HTTP 界面的方式——ChatGPT、Claude.ai 连接器和各 API 都没有本地技能目录。

方法	返回内容
skills/list	技能目录：skill://amira-mcp/SKILL.md、其 frontmatter，以及每个文件的 SHA-256 摘要和字节大小
skills/get	按 URI 获取单个技能，无需重新列出即可刷新摘要
resources/read	按需读取任意单个文件——SKILL.md 或参考文件
resources/directory/read	每次读取一个目录层级（skill://amira-mcp、skill://amira-mcp/references）

未使用时的开销：零。 技能文本绝不会注入服务的 instructions 或任何工具描述中，因此 tools/list 载荷——每轮都会重新发送的部分——无论主机是否支持该扩展，字节内容都完全相同。何时披露由主机决定；只有在实际读取时，才会加载三个参考文件。

设置 AMIRA_SKILLS=0 即可移除此功能及三个方法。

安装（最终用户）

从发布页面下载 amira-mcp-server.mcpb 并双击。Claude Desktop 会显示安装对话框；点击安装即可。 无需进一步配置。最新的带标签发布版本包含当前数据；滚动更新的 data-latest 预发布版本始终跟踪最新的网站快照。

在 ChatGPT、API 或任何远程客户端中使用

.mcpb 是适用于 Claude Desktop 的本地离线选项。同一服务也可以作为远程 Streamable HTTP 端点运行——只需一个 HTTPS URL，ChatGPT、Claude（网页端和桌面端远程连接器）、OpenAI 和 Anthropic API、Cursor、VS Code 及其他客户端即可通过粘贴 URL 连接（无需下载，数据始终是最新的）。远程接口提供相同的 33 个工具，另加与 OpenAI 兼容的 search / fetch 工具，供 ChatGPT 研究集成使用（共 35 个）。无需身份验证即可访问——数据公开且只读。

search 接受普通关键词（逐词匹配，而非精确短语），并可选用 limit 和 types 缩小结果范围；它会返回按相关性排序的结果，涵盖研究条目、书目（包括出版物全文）、播客、视频、项目和研究章节。search 结果和 fetch 文档中的 url 始终指向 AMIRA/Omeka 公共记录页面；DOI、YouTube/watch 和播客/listen URL 则作为次要元数据/文本链接保留。fetch 会根据 search 返回的 id 获取单条记录的全文——默认不包含视频和播客的文字稿（仅返回元数据和描述，因为完整文字稿可能长达数万字符）；设置 include_transcript=true 即可提取文字稿，并使用 transcript_offset / transcript_max_chars 分页（与 get_video / get_podcast 使用的参数名称相同）。出版物全文的处理方式相同（include_fulltext=true，使用 fulltext_offset / fulltext_max_chars 分页，与 get_publication 保持一致），而 max_chars 会限制整个文本正文的长度。追加内容窗口的大小会根据元数据头之后 max_chars 剩余的字符数来确定，因此 *_returned_chars 恰好等于写入 text 的字符数，下一页从 offset + returned_chars 开始，不会跳过内容。

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-mcp

端点：POST /mcp（MCP 端点）和 GET /healthz。使用 PORT / HOST 绑定。

• ChatGPT → 在 Settings → Security and login 下启用 Developer mode，然后从 ChatGPT Plugins 添加服务器 URL。研究集成使用 search + fetch；请参阅当前 OpenAI 设置指南。

• Claude（网页端或桌面端）→ Settings → Connectors → Add custom connector → https://<your-host>/mcp。

• OpenAI API（Responses）——将 mcp 工具指向此端点：

  { "type": "mcp", "server_label": "amira",
    "server_url": "https://<your-host>/mcp",
    "allowed_tools": ["search", "fetch"], "require_approval": "never" }
  

部署（可自托管，例如与 amira 网站一同部署）

多阶段 Dockerfile 会在构建时抓取最新快照，并运行自包含的打包程序（运行时无需 node_modules）。在 Linux 主机上，也可以通过反向代理使用 systemd 运行：

# /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-data

location /mcp { proxy_pass http://127.0.0.1:8787/mcp; proxy_buffering off; client_max_body_size 64k; }

proxy_buffering off 可确保 Streamable-HTTP/SSE 响应持续传输。即使与 Omeka 部署在同一位置，刷新操作仍使用 AMIRA_SITE_BASE（默认为公共 HTTPS API）。检测到更改时会执行完整抓取；部署在同一位置并不会减少 API 负载。服务会将请求正文限制为 64 KiB，并将速率限制状态限制为 10,000 个客户端。面向公众部署时，请在反向代理处配置连接数、请求速率和并发限制；进程内限制器仅用于辅助控制。关闭时会取消刷新任务，并为 HTTP 连接留出十秒的排空时间。

若要构建使用已审核的 data/ 快照、且构建期间不调用 Omeka 的版本：

docker build --build-arg SNAPSHOT_STAGE=bundled -t amira-mcp .

默认的 SNAPSHOT_STAGE=fetch 仍会抓取最新数据。两个阶段都会验证快照。镜像会固定基础镜像摘要；npm ci 使用已提交的锁文件。

开发 / 重新构建

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)

令牌预算

上下文是客户端最稀缺的资源，因此会测量并限制此服务消耗的两部分开销（scripts/weigh.mjs，按字节数除以 4 估算令牌数——只能与自身比较，不能与账单对照）：

	内容	预算	偏差
表面	tools/list 负载，每轮都会重新发送	每次完整配置传输 14,000 个令牌	超过 3% 时失败
响应	每个工具都以其最大限制调用	每次调用 20,000 个令牌且少于 45,000 个字符	超过 10% 时警告

工具描述并非根据快照生成，因此表面是代码的纯函数：test/unit/budget.test.mjs 会离线检查它，不需要任何数据，并断言空存储测量结果仍与基于完整快照记录的基线一致。响应权重需要真实数据，因此 npm run weigh -- --check 会在 smoke 作业中运行。此处的偏差只会触发警告——常规的 npm run fetch-data 不应导致构建失败——而绝对上限（Claude Code 会在 25,000 个令牌处截断工具结果）属于致命错误。如果任何探测调用失败，也属于致命错误，因为结构化拒绝约为 60 个令牌，否则会轻易低于所有上限。

1.18 版有意将完整配置的上限提高到估算的 14,000 个令牌，以容纳六个工具和实用的输出架构。较小配置的限制分别为 10,100（research，从 10,000 提高，以容纳 resolve_entity 中差一点就超出的字段）、6,500（discovery）和 9,500（visualization）。评估消融中关闭指导功能的表面也会像已发布版本一样进行测量和限制。已提交的基线记录了精确的表面大小、文本字节数、序列化传输字节数（文本和结构化内容都会计入），以及测量所用的快照。每个响应还必须少于 45,000 个字符：Claude Code 会将超过 50,000 个字符的任何工具结果存入文件，而不是放入对话中。分页结果和图的字节数都有上限，以确保符合要求。

当某项更改确实会使任一数字增大时：

npm run weigh -- --update    # rewrites test/token-baseline.json

提交差异。这正是该文件的意义：新增工具或更丰富的结果摘要所带来的成本会以数字的形式出现在代码审查中，而不是悄无声息地增加。

打包扩展：

npm run prepack-mcpb                       # clean + typecheck + build + test + smoke
npm run validate:manifest
npm run pack-mcpb                          # -> amira-mcp-server.mcpb

scripts/census.mjs 会重新运行字段映射背后的属性普查（scripts/census-report.json）——如果实例的模板发生变化，请重新运行并比较差异。相关设计决策记录在 ROADMAP.md 中；每个版本的内容则记录在 CHANGELOG.md 中。

持续交付

三项 GitHub Actions 工作流涵盖拉取请求和分发（两项分发工作流会抓取公开 API，不需要凭据）：

• CI（.github/workflows/ci.yml）——在拉取请求和推送到 main 时运行：先进行一次类型检查，然后在 Linux 上使用 Node.js 22、24 和 26，以及在 Windows 上使用 Node.js 24，运行离线单元测试套件（包括工具表面的令牌预算）；接着测试两种 MCP 传输方式，评估每个工具在最大限制下的响应大小，并验证 MCPB 清单。完整的依赖项审计发现高危或严重安全公告时会失败。 单独的容器任务会构建离线夹具镜像并检查运行状况。 Windows CI 还会打包夹具扩展并检查其文件列表。另有一项不会阻塞流程的任务，会针对 HTTP 服务运行官方 MCP 一致性测试套件。 Actions 均固定到提交 SHA；每个任务都设置了超时时间。

• Release（.github/workflows/release.yml）——推送 v* 标签时运行：检查标签是否与 package.json 一致，抓取最新快照，运行单元测试、在线测试和冒烟测试，并在只读任务中打包 .mcpb 和压缩配套技能（amira-mcp-skill.zip）；单独的发布任务会将两者附加到 GitHub Release，并提供构建来源证明。另有一项不会阻塞流程的任务会将 server.json 发布到 MCP Registry。

• 刷新数据快照（.github/workflows/refresh-data.yml）——每周运行，也可按需运行；只有在转换后的快照内容哈希发生变化时才会重建，包括条目集和词汇表的变化，并更新滚动的 data-latest 预发布版本。

通过 Actions 发布需要可写令牌。 如果组织禁用了默认工作流令牌的写入权限，请执行以下任一操作：(a) 在 Organization → Settings → Actions → General → Workflow permissions 下启用 Read and write permissions，或 (b) 添加仓库/组织密钥 RELEASE_TOKEN（具有 contents: write 权限的 PAT 或 GitHub App 令牌）。工作流会在存在 secrets.RELEASE_TOKEN 时使用它，否则回退到默认令牌。

配置（环境变量／扩展设置）

环境变量	扩展设置	默认值	含义
AMIRA_LIVE_REFRESH	从实时站点刷新数据	true	在启动时和定期检查间隔到期时，探测公共 API 并刷新快照
AMIRA_REFRESH_INTERVAL_HOURS	—	24	启用实时刷新时，服务运行期间按此间隔重复进行数据新鲜度探测；设为 0 可停用定期检查
AMIRA_FULL_REFRESH_HOURS	—	168	即使条目签名未变化，快照达到此时长后也强制执行完整抓取；最短为 1 小时
AMIRA_TOOL_PROFILE	—	full	full、research、discovery 或 visualization；更改后需重启
AMIRA_CACHE_DIR	刷新数据缓存目录	~/.amira-mcp/cache	存储刷新后快照的位置
AMIRA_SITE_BASE	站点基础 URL（高级）	https://data.africamultiple.uni-bayreuth.de	用于引用和刷新（接受 AMIRA_DASHBOARD_BASE，但会显示弃用警告）
AMIRA_SITE_SLUG	—	amira	在 amira_url 中使用的 Omeka 站点 slug
AMIRA_DATA_DIR	—	内置的 data/	覆盖内置快照路径（开发用）
AMIRA_EXPOSURE	—	full	仅限基准测试：限制工具公开的元数据（见下文）
AMIRA_GUIDANCE	—	on	仅限基准测试：设为 off 时，仍提供相同的工具，但不提供策展指导——指令、描述、错误建议、提示词、技能（见下文）；更改后需重启
AMIRA_SKILLS	—	on	通过已最终确定的 SEP-2640 扩展提供配套技能。设为 0／false／off 可撤销此功能及 skills/* 方法
PORT	—	8787	远程 HTTP 传输的端口（server/http.js）；.mcpb 会忽略此项
HOST	—	127.0.0.1	HTTP 绑定地址；如需远程访问，请显式设为 0.0.0.0。Docker 镜像会自行设置此项
AMIRA_ALLOWED_ORIGINS	—	localhost, 127.0.0.1, [::1]	允许调用 HTTP 端点的浏览器 Origin 主机名或 URL，以逗号分隔。不包含 Origin 的服务间客户端不受影响。请显式添加可信网页客户端的来源；不接受通配符。
AMIRA_RATE_LIMIT	—	120	/mcp 每个客户端每分钟的请求数（设为 0 可停用）。这是宽限上限——查询基于内存中的快照运行——而非安全控制；/healthz 不受限制
AMIRA_TRUST_PROXY	—	false	将请求归属到反向代理观察到的地址：优先使用 X-Real-IP，否则使用从右侧起第 AMIRA_PROXY_HOPS 个 X-Forwarded-For 条目（绝不使用客户端提供的最左侧条目）。在代理后方运行时启用此项，否则所有请求都来自代理，所有客户端将共用一个限流桶；客户端直接连接时切勿启用
AMIRA_PROXY_HOPS	—	1	当 X-Real-IP 不存在时，读取 X-Forwarded-For 所需信任的前置代理数量。IPv6 客户端按 /64 网段归入限流桶

快照布局与恢复

缓存位于 AMIRA_CACHE_DIR/<API identity hash>/ 下。active.json 指向当前不可变的 generations/<uuid>/ 目录以及两个之前的代次。未被引用的代次有 24 小时的清理宽限期。现有的扁平快照和来自同一数据源的旧版 cache/current 仍可读取；首次发布新版本时，会将扁平目标迁移到代次历史中。npm run fetch-data 也会将代次布局写入 data/；脚本必须使用 loadSnapshot，而不能假定 data/manifest.json 是当前快照。

崩溃的写入进程可能会留下 writer.lock。停止所有正在使用该缓存的进程，确认没有写入进程正在运行，然后删除该锁文件并重启。服务会刻意避免猜测旧锁是否可以安全地抢占。刷新失败时，最后一份可用数据仍会保留。/healthz、概览和数据质量报告会显示刷新尝试和成功时间、进行中状态以及失败类别。仅对上游暂时性故障重试，遵守有上限的 Retry-After，并在 15 分钟刷新截止时间到达或服务关闭时中止。探测无法提供事务性的 Omeka 快照；仍需定期执行完整抓取。

元数据暴露级别（基准实验）

AMIRA_EXPOSURE 可让评估在不同级别的元数据可见性下运行相同任务，即 LLM 访问研究中的“元数据中介”条件。这是实验标志，不是终端用户设置；默认值（full）是正常的服务模式。存在性标志（has_transcript / has_fulltext）在所有级别均可见；只有内容和关系受到限制，拒绝访问时会返回结构化错误（exposure_restricted / text_access_disabled），使模型能够说明无法回答的原因，而不是产生幻觉。

级别	模型可见内容
minimal	标题、类型、日期、URL、媒体标志。关键词搜索仅匹配标题；实体／分面／关系工具和结构化筛选会被拒绝
descriptive	+ 描述、摘要、目录（也可用于搜索）
structured	+ 主题、地点、人物、项目、章节、馆藏、场馆——可使用所有筛选器和实体工具
full	+ 文字记录和出版物全文（默认）

指引消融（基准实验）

AMIRA_GUIDANCE=off 会在不提供策展指引的情况下提供相同操作，以便评估衡量这些指引的作用。与 AMIRA_EXPOSURE 一样，这是实验标志；默认值（on）不会改变任何行为。工具列表在服务启动时构建，因此应在启动前设置该变量；如需更改，请重启服务。

通道	on（默认）	off
服务说明	在 initialize 时发送	无
工具	名称、标题、描述、带参数说明的架构	相同的名称、输入和输出架构（类型、枚举值、边界、必填字段）、注解和应用 _meta；不含标题、描述或 .describe() 文本；不含 anthropic/alwaysLoad 提示
错误	code、消息、suggested_tool、available_values	code 和简短的问题说明；不指向其他工具、不提供候选值、不提供建议（“请依据仍然公开的元数据作答……”）
结果	数据，以及 *_hint 分页提示、导出的 note、空搜索的 hint、人物 suggestions，还有 search_research_items 的放宽条件 suggestions 和 did_you_mean	相同的数据，但不含这些内容
提示词、配套技能	已注册并声明	均无
资源	标题和描述	仅 URI 和 MIME 类型

使用指引时，工具列表在 stdio 上每轮估算消耗 12,040 个 token，不使用时为 8,485 个（HTTP：12,981 和 9,044）；说明会在每个会话开始时额外增加 448 个 token。npm run weigh 会测量两种情况，并将其记录为基线。

架构

• 纯内存类型化记录。 Omeka JSON-LD 在构建时转换一次（src/transform.ts，证据见 scripts/census-report.json）；运行时加载精简记录并在启动时建立索引。无原生绑定；esbuild 打包产物可独立运行。

• 离线优先，原子刷新。 打包快照 + 锁定的生成版本发布；启动时以最新清单为准（旧缓存绝不会覆盖更新的打包快照）。

• 引用统一规范：每个实体都是一个 Omeka 条目，因此每条记录都包含 amira_url = <site>/s/amira/item/<o:id>。

• 全程支持忽略重音符号进行匹配（src/text.ts）。该馆藏以法语非洲内容为主，其中的规范记录与自由文本并不总是采用一致的重音符号——主题词标题使用 "Côte d'Ivoire"，而条目标题使用 "Cote d'Ivoire"。每次关键词比较都会对两侧进行折叠处理（NFD、删除组合附加符号、转为小写，并将弯引号、破折号和合字 œ/æ/ß 映射为普通形式），因此结果不再取决于调用方猜测的拼写。较长文本的折叠结果会进行记忆化缓存，并在刷新替换快照时清除。

• 交互式结果（MCP Apps）。 七个工具带有 _meta.ui.resourceUri，指向 text/html;profile=mcp-app 资源，因此实现了 io.modelcontextprotocol/ui 扩展的宿主（Claude、Claude Desktop）可以内联呈现结果。其他客户端会忽略 _meta，并获得完全相同的 JSON。

  工具	资源	呈现内容
  get_collection_overview	ui://amira/overview	统计信息卡片 + 按大学、分区、资源类型和语言排列的排名细目
  list_years	ui://amira/timeline	按年份或年代统计条目的直方图
  list_research_sections	ui://amira/sections	AM 1.0 / AM 2.0 资助阶段各分区的甘特图，带有“当前”标记
  find_related	ui://amira/related	径向共现关系图：种子位于中心，每种关系类型对应一个带标签的扇区
  get_entity_graph	ui://amira/graph	按实体类型划分的扇区图、类型标签、可选择的辐条及其证据、键盘导航
  list_locations	ui://amira/map	离线地图、国家/地区下拉菜单、地点表格和条目证据
  search_publications	ui://amira/bibliography	可筛选的书目（语言下拉菜单、作者建议）和所选条目的导出功能

  模块位于 src/ui/：shell.ts 存放设计令牌和共享的条形图原语；bridge.ts 打包官方 Apps SDK。每个应用都提供自己的 CSS 和渲染函数。模板不会从网络加载任何内容——不加载脚本、样式、字体或地图瓦片——因此无需 _meta.ui.csp 授权，并可在最严格的沙箱中运行。应用控件通过宿主调用允许列表中的只读工具；筛选下拉菜单也采用相同方式填充，因此其选项列表不会传递给模型。引用链接和文件下载也通过宿主 API 处理。每种可视化都提供表格或文本替代内容。详见应用开发与来源说明。 颜色取自 DREVisualizations Omeka 模块的主题（--primary / Africa Multiple 品牌调色板），因此聊天中的图表 与 AMIRA 网站上的同一图表看起来属于同一个系统；这些颜色也经过了与相应界面的 对照验证，而非凭目测选定——浅色模式下在 #fdfcfa 上使用 #007a50， 深色模式下在 #1b211e 上使用 #35a87d（主题自身的 #3fb488 恰好 超出深色模式的亮度范围，因此应用选用了低一档的颜色）。每张图表都只有一个 系列，类别显示在坐标轴标签上，因此使用一种强调色即可，也不需要图例。共现枢纽 按理需要用六种色相表示六种关系类型，但品牌调色板中没有一组六种色相能在所有 配对中保持色觉障碍（CVD）区分度（在绿色盲情况下，最佳候选组合的 ΔE 也只有 2.4），所以这里通过空间位置来区分——每种关系类型对应一个带标签的扇区—— 这种方式在灰度、打印和强制颜色模式下也能正常显示。

协议说明

已于 2026 年 10 月 6 日对照当前规范 和 TypeScript SDK 文档进行了验证。 该服务在两种传输方式上都使用 MCP 2026-07-28，并且仍能原样响应 2025 年时代的客户端。

该服务运行于 v2 TypeScript SDK，使用作用域包 （@modelcontextprotocol/server、/node、/client），而非冻结的 @modelcontextprotocol/sdk v1 单体包。若要处理入口点，有两点值得了解：

• 现代时代需要显式启用。 SUPPORTED_PROTOCOL_VERSIONS 是旧版 initialize 协议版本列表，截止于 2025-11-25；SDK 有意将 2026 版本字符串 保持为内部内容。createAmiraServer 会在 supportedProtocolVersions 中自行指定该修订版本，这样才能注册 server/discover——否则该方法会返回 -32601。
• 协议时代由入口决定，而非传输方式。 serveStdio(factory) 和 createMcpHandler(factory) 会按连接或请求决定协议时代，并固定使用 工厂创建的一个实例。手动连接纯粹的 StdioServerTransport 或 NodeStreamableHTTPServerTransport，只会提供 2025 年时代的服务。

具体到线上传输：server/discover 会公布 ["2026-07-28"]，结果中包含 resultType，可缓存的结果则带有实际的 ttlMs / cacheScope （tools/list、resources/list 和 server/discover 为 1 小时的 public； resources/read 为 24 小时，其 ui:// 应用 HTML 在每次构建中不可变）， 而不是使用 SDK 保守的默认值 { ttlMs: 0, cacheScope: "private" }。向后兼容由 处理程序的 legacy: 'stateless' 默认设置实现，它会为每个请求创建一个新实例来 响应 2025 年时代的流量——这与该服务一贯采用的模式相同。

该修订版本废弃的功能在这里都不会造成影响：Roots、Sampling、Logging 和 Elicitation 均未使用，日志会写入 stderr，工具顺序是确定的（按注册顺序）。 CORS 同时接受两代请求头（Mcp-Session-Id/MCP-Protocol-Version 和 Mcp-Method/Mcp-Name/X-Mcp-Header）。

引用本软件

如果你在查找或分析 AMIRA 材料时使用了此服务，请引用它。该仓库包含 CITATION.cff，因此 GitHub 的引用此仓库按钮会为你生成 BibTeX 和 APA 格式的引用。

@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}
}

请将数据与软件分开引用：各条记录可通过其 amira_url （https://data.africamultiple.uni-bayreuth.de/s/amira/item/<id>）引用， 每个工具结果都会返回该 URL，正是出于这个原因。

致谢与资助

由拜罗伊特大学 Africa Multiple 卓越集群的 数字研究环境（DRE） 构建和维护。DRE 是该集群的数字基础设施部门，负责设计和运行 AMIRA 背后的数据系统。底层记录的整理与描述由 Africa Multiple 研究中心的合作伙伴共同完成，包括约瑟夫·基-泽博大学、罗德斯大学、拉各斯大学、莫伊大学和巴伊亚联邦大学。

项目由德国研究联合会（DFG）根据德国卓越战略资助，项目编号为 EXC 2052/1 — 390713894 （Africa Multiple：重构非洲研究）。

许可证

MIT——详见 LICENSE。另请参阅 CONTRIBUTING.md 和 SECURITY.md。