Islam West Africa Collection (IWAC)

IWAC MCP 服务

一个只读的 Model Context Protocol 服务，用于访问 伊斯兰西非收藏（IWAC）。 以一键安装的 桌面扩展 （.mcpb）形式提供，供 Claude Desktop 使用，数据来自 IWAC Hugging Face 数据集。 此外，还为 ChatGPT 和其他 MCP 客户端提供托管端点 https://islam.zmo.de/mcp/ —— 完整的连接指南（适用于 Claude Desktop 和 ChatGPT）请参阅 docs/connecting.md。

安装

每个发行版都提供 适用于您操作系统的服务包以及一个研究技能 .zip 文件。.mcpb 为 Claude 提供数据和工具； .zip 则添加研究技能，教 Claude 如何使用这些工具。请先安装服务，然后也安装研究技能 — 强烈推荐，以充分发挥工具的作用：它能让 Claude 更高效地搜索和综合信息，减少无效查询。

1. MCP 服务 — 选择适用于您操作系统的服务包

您的操作系统	下载
Windows（Intel/AMD 或 Snapdragon）	iwac-mcp-server-windows.mcpb
macOS（Apple Silicon 或 Intel）	iwac-mcp-server-macos.mcpb

1. 使用上方链接下载适用于您操作系统的最新服务包。
2. 双击文件。Claude Desktop 会显示安装对话框 — 点击 Install。
3. 首次使用时，服务会从 Hugging Face 下载约 265 MB 的 parquet 数据 到 ~/.iwac-mcp/cache/（可在扩展设置中更改位置）。

服务包包含适用于您操作系统的服务和 DuckDB 二进制文件（x64 和 arm64）。 Claude Desktop 会提供 Node.js 运行时， 因此无需单独安装 Node.js 或 Python。我们为 Windows 和 macOS 发布桌面服务包。

扩展设置和更新

在 Claude Desktop 中打开 Settings → Extensions → Islam West Africa Collection (IWAC)，配置以下选项：

功能	凭据	设置
公开关键词搜索、筛选、统计信息和条目详情	无	默认设置。
语义搜索	无	默认开启（Semantic search）。首次进行语义搜索时会下载一次查询模型（约 350 MB）；关闭此设置即可跳过下载。
私有全文	有权读取私有数据集的 Hugging Face 令牌	启用 Use private full dataset，并输入 Hugging Face token (private dataset only)。

语义搜索会在你自己的计算机上运行 EmbeddingGemma 2，即创建语料向量所用的模型：无需 API 密钥，查询内容也不会离开你的计算机。该功能需要 Windows（x64 或 ARM64，并安装大多数电脑已有的 Microsoft Visual C++ 2015-2022 Redistributable）或 Apple 芯片 Mac；在 Intel Mac 上，语义工具会提示无法运行，但其他功能均可正常使用。共享托管端点提供公开数据。

**更新：**下载并打开适用于你操作系统的最新安装包，即可更新扩展。如果看不到 Hugging Face 字段，你安装的扩展可能早于 v3.6.0。更新后，请检查设置，保存任何更改，并重启 Claude Desktop。

可选的私有全文访问

公开数据仍为默认设置，无需令牌。在桌面扩展中，启用 Use private full dataset，输入 Hugging Face token (private dataset only)，保存设置并重启。请使用具有 fmadore/islam-west-africa-collection-full 读取权限的细粒度令牌。令牌字段已标记为敏感信息。切勿将令牌粘贴到聊天中或提交到代码库。

其他本地启动器可以设置 IWAC_PRIVATE_DATASET=true，并提供 IWAC_HF_TOKEN（或 HF_TOKEN）。仅提供令牌不会启用私有模式；公开数据下载不会发送该令牌。无需新增依赖项或账户系统。

私有文件使用 IWAC_CACHE_DIR 的独立 private-full/ 子目录（默认：~/.iwac-mcp/cache）。更改模式后请重启。缺少令牌以及私有 HTTP 401/403/404 错误都会导致操作失败，不会回退到缓存。网络中断时可以使用该模式的缓存。显式设置 IWAC_OFFLINE=true 后，无需身份验证即可使用已下载的文件；移除令牌不会删除私有文件。

请保持共享托管端点为公开状态。此设置适用于整个实例：所有能够查询私有实例的用户都可以访问其全文。因此，除非同时设置 IWAC_ALLOW_PRIVATE_HTTP=true，否则 HTTP 模式会拒绝在私有模式下启动；两种传输方式都会在启动时记录所提供的数据集。

2. 研究技能 — iwac-mcp-skill.zip（强烈推荐）

iwac-mcp 技能 将原始工具封装成结构化研究工作流：包含五阶段方法、法语区搜索策略、带置信度评级的来源归属，以及偏差／覆盖范围注意事项。它能大幅提升服务的使用效率——Claude 首轮就能选对工具和搜索词（减少无效查询）、正确搜索法语来源，并返回带引用的综合结果，而不是原始工具输出。你可以不安装它，直接使用这些工具；但安装后，每次查询都能发挥更大价值。

下载最新的 iwac-mcp-skill.zip，然后：

• Claude Desktop — 打开 Customize → Skills → + → Create skill → Upload a skill，选择该 zip 文件。（或者将其解压到 ~/.claude/skills/，然后重启 Claude Desktop。）

• Claude Code — 将其解压到你的技能目录；Claude Code 会即时发现它，无需重启：

  # macOS / Linux
  unzip iwac-mcp-skill.zip -d ~/.claude/skills/
  

  # Windows (PowerShell)
  Expand-Archive iwac-mcp-skill.zip -DestinationPath $HOME\.claude\skills\
  

  两种方式都会将技能放在 ~/.claude/skills/iwac-mcp/。仓库中的权威源文件位于 .agents/skills/iwac-mcp/；请将项目本地副本放在那里，而不要在 .claude/ 下重复放置同一技能。

  仍然值得按这种方式安装：在调用任何工具之前，系统会自动根据你的问题匹配已安装的技能。

服务还会提供该技能（skill://）

每个构建版本（包括 Docker 镜像）都会嵌入研究技能，并通过 MCP SDK 对 Skills 扩展（SEP-2640，io.modelcontextprotocol/skills）的实现提供该技能。支持该扩展的客户端会通过 skills/list 和 skills/get 发现技能，使用 resources/directory/read 浏览技能，并根据清单中的 SHA-256 摘要校验读取的每个文件。不支持该扩展的客户端会在 resources/list 中看到每个文件及其标题和一行摘要，并通过普通的 resources/read 读取：

资源	内容
skill://iwac-mcp/SKILL.md	研究工作流
skill://iwac-mcp/references/…	四个按需读取的参考文件
skill://iwac-mcp	技能目录，供 resources/directory/read 使用

裸 URI skill://iwac-mcp 现在表示一个目录，不再是最高至 v4.1.0 的版本发布时在此提供的 JSON 目录；skills/list 会提供相同的大小和摘要。技能内容是构建时快照；修改源文件后需要重新构建。对于在本地安装技能的客户端，仍可使用发布包 zip 文件。远程客户端无需下载发布包，也能读取相同的工作流。

它能为 Claude 提供什么

39 个只读工具，涵盖 IWAC 的七个子集，均无需 API 密钥。4 个 semantic_search_* 工具可以关闭；它们使用本地运行的 EmbeddingGemma 2 进行排序（参见 mcpb/README.md）。关键词和筛选条件匹配均不区分重音符号和大小写。统一的 search/fetch 工具对、统计工具、聚合工具、list_periodicals 和 get_sentiment_distribution 也会返回 MCP 结构化内容（outputSchema + structuredContent），这是 ChatGPT 连接器契约的要求。

分组	工具
跨子集	search、fetch、explore_corpus
文章	search_articles、get_article、semantic_search_articles
情感	search_by_sentiment、get_sentiment_distribution
索引	search_index、get_index_entry、list_subjects、list_locations、list_persons
统计	get_collection_stats、get_newspaper_stats、get_country_comparison、get_temporal_distribution
聚合	get_topic_distribution、get_field_distribution、get_cooccurrence、get_lexical_metrics、get_place_distribution、get_semantic_map、get_similar_items
出版物	search_publications、list_periodicals、get_publication_fulltext、semantic_search_publications
参考资料	search_references、get_reference、semantic_search_references
图像	search_images、get_image、semantic_search_images
其他	search_documents、get_document、search_audiovisual、list_audiovisual、get_audiovisual

聚合工具回答的是关于整个集合的问题，而非返回其中的条目：内容如何分布在预先计算的 30 个 LDA 主题中，哪些主题、地点或署名占主导，哪些内容会与哪些内容一同讨论，文本风格如何，内容指向地图上的哪些位置，在嵌入空间中的分布如何，以及给定条目的最近邻是什么。总共有 14 个工具（统计工具组、这些聚合工具、list_periodicals、get_sentiment_distribution 和 explore_corpus）声明了 MCP App 视图，因此在 Claude 中会以交互式图表呈现，而不是 JSON。

get_temporal_distribution 还支持伊斯兰历。使用 granularity="lunar_month" 时，它会将每年的数据汇总到十二个阴历月份中——这是公历时间轴在结构上无法生成的分组，因为回历年每年会漂移约 11 天，因此每个宗教节日都会分散到所有十二个公历月份中。在 16,579 篇日期完整的文章中，档案的规律十分明显：相对于均匀分布，斋月高出 73%，祖·希哲月高出 68%（朝觐和 Tabaski），闪瓦鲁月高出 42%（Korité），而赖比尔·敖外鲁月（Maouloud）则基本持平。search_articles 和 search_publications 支持使用 hijri_month（1–12 或任一种转写形式的月份名称）和 hijri_year，以检索峰值背后的条目。阴历日期由数据集处理流水线使用乌姆·库拉历表预先计算，与 islam.zmo.de「历史上的今天」区块使用的是同一转换器，因此两者不会出现差异；仅标注年份或月份的条目没有阴历日期，不会绘制在图表中，而会计入 imprecise_date_count。

四个全文工具（get_article、get_document、get_publication_fulltext 和 get_audiovisual）都可选用 keyword，返回每处匹配内容周围约 2,000 个字符的摘录，让 Claude 只需阅读长篇文章、档案文档、期刊期次或转录文本中的相关段落，而无需读取全文。如果需要全文，它们会分成每段 25,000 个字符提供：每段都会注明下一段的起始位置（next_offset），将其作为 offset 传回即可继续读取后续内容，直至读完。

每个结果对象都包含一个 url 字段，指向对应的规范 IWAC 记录，例如 https://islam.zmo.de/s/afrique_ouest/item/28576。

关于该合集

IWAC 是一个聚焦西非伊斯兰教和穆斯林的数字档案：

• 16,700+ 篇报纸文章，来自贝宁、布基纳法索、科特迪瓦、尼日尔 和多哥，时间跨度从 1961 年至今（大多为法语），每篇都附有 AI 摘要。公开数据集包含约 45% 文章的完整 OCR 文本，这些文本已公开于 islam.zmo.de；get_collection_stats 会报告实时比例。
• AI 情感分析（极性／中心性／主观性）涵盖已完成增强处理的 12,298 篇文章，由五个模型独立评分：gpt-5-6-luna（行内列所报告的模型）、 mistral-small-2603、deepseek-v4-flash-0731、gemma-4-31b-it 和 qwen3-8-27b。最新到达的约 4,400 篇文章尚未评分。五个模型对极性的判断仅在约 32% 的文章上达成一致，因此引用数据时，最诚实的做法是使用 get_sentiment_distribution(model="all")。 并非所有模型都覆盖相同的文章（qwen3-8-27b 为 12,098 篇评分，其余模型为 12,298 篇），因此每个模型都会报告各自的 coverage。 model="consensus" 返回预先计算的多数意见（并非第六个模型），而 search_by_sentiment(disputed=…) 可读取意见不一致的文章。
• 5,000+ 条规范记录（人物、组织、地点、事件、主题）
• 1,500+ 种伊斯兰出版物（期刊各期、图书），大多有完整 OCR
• 860+ 条学术参考文献，约半数附有摘要
• 1,800+ 件视听资料：来自布基纳法索、多哥和贝宁的法语网络视频（从公开频道采集，仍在持续增加，可按频道搜索，并可通过观看 URL 访问），以及 47 段已存档的尼日利亚豪萨语／阿拉伯语录音，附有文件
• 26 份档案文件和 30 张田野调查照片

研究工作台

explore_corpus 可将筛选结果与来源、关键词上下文、覆盖率热力图、比较、出版国／提及地点矩阵，以及支持分页的清单、CSL-JSON 和 BibTeX 导出相连接。iwac://datasets/{subset} 资源可展示当前列、字段可用性和数据集来源信息。 时间图表支持使用明确分母计算标准化占比。情感比较接受相同的筛选条件，并可指定一对模型；统计结果会针对明确报告的样本群体给出 Cohen’s kappa 和二次加权 kappa。精确图表筛选、来源阅读、返回导航和来源信息导出在整个应用中通用。示例、解读限制、缓存行为和本地嵌入迁移，请参阅工作台指南。

在支持 MCP Apps 的宿主上，全屏可展开视图，并会自动与助手共享当前筛选结果的简要摘要。询问此筛选结果会连同该筛选结果的快照发送明确问题；自动更新不会开始新的对话轮次。摘要包含有限范围的筛选条件、计数、来源 ID 和来源信息，并会标明省略内容；获取完整来源文本仍需检索。控件取决于宿主声明的功能。请参阅交互约定。

架构

• 数据：IWAC Hugging Face 数据集中的 parquet 文件会按子集（articles、publications、documents、audiovisual、images、index、references）延迟下载到本地缓存，并通过 DuckDB 视图进行查询。长期运行的服务每天会重新检查每个子集（IWAC_REFRESH_HOURS），并在无需重启的情况下替换为较新版本。每个请求都会固定使用其文件；旧版本会保留，供其他读取者使用并确保可复现性。所有 SQL 都使用参数化查询；匹配不区分重音符号和大小写。
• 传输方式：stdio（默认方式，Claude Desktop 的 .mcpb 使用此方式），以及无状态的 Streamable-HTTP 模式（node server/index.js --http），该模式通过 bearer token 进行保护，Docker 镜像会以此方式运行托管的 https://islam.zmo.de/mcp/ 端点。
• Docker：每次发布都会提供 ghcr.io/fmadore/iwac-mcp-server，用于自行托管 HTTP 端点——所需的环境变量和令牌设置请参阅 mcpb/README.md。

开发

此实现的构建和服务运行时均要求 Node.js 24 或更高版本。Node.js 20 已结束生命周期。内嵌运行时版本较旧的桌面宿主必须先升级，才能安装下一个软件包；清单会拒绝不兼容的运行时。

软件包位于 mcpb/ 下。构建／打包工作流请参阅 mcpb/README.md。

cd mcpb
npm ci
npm run install-bindings   # fetch the 4 macOS/Windows DuckDB binaries
npm run typecheck   # tsc --noEmit
npm run lint        # biome (linter only)
npm run build       # esbuild -> single server/index.js
npm test            # unit, fixture, app, skills, HTTP and token-budget tests
npm run test:browser # Chromium app behavior (install browser first)
npm run test:live   # full smoke test against the real HF dataset (~265 MB)

每次向 main 推送代码以及每个拉取请求都会触发 CI，运行版本检查、类型检查、lint、构建、单元测试，以及离线测试夹具和 HTTP 往返测试；在线冒烟测试每周运行一次（其固定计数用于检测数据集漂移）。发布流程：推送 v* 标签——发布工作流会重新运行完整测试套件，检查版本是否尚未发布，在 macOS／Windows 上打包并验证桌面软件包，并在发布前对 Docker 镜像进行冒烟测试。发布任务使用这些经过测试的构件。现有发布和注册表版本无法覆盖；发布新版本时请使用新的版本号。

路线图

请参阅 TODO.md。近期计划：提交至 Anthropic 扩展目录，并使用生产环境代码签名证书为软件包签名。

如何引用

机器可读的元数据位于 CITATION.cff 中——GitHub 的引用此仓库按钮（侧边栏）会将其呈现为 APA 或 BibTeX 格式，并填入当前版本。文中引用格式：

Madore, F. (2026). IWAC MCP Server (Version 4.3.1) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21805837

@software{madore_iwac_mcp_server,
  author    = {Madore, Frédérick},
  title     = {{IWAC MCP Server}},
  year      = {2026},
  version   = {4.3.1},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21805837},
  url       = {https://github.com/fmadore/iwac-mcp-server},
  license   = {MIT}
}

该 DOI 是概念 DOI，始终指向最新发布版本，因此版本更迭时仍然有效。如果需要引用你实际运行的确切版本，请从 Zenodo 记录获取对应版本的 DOI。

如果这款软件帮助你得出了研究发现，也请引用该馆藏本身——档案工作正是在这里进行的。

许可证

MIT

相关链接

• IWAC Hugging Face 数据集
• IWAC 数字档案
• 桌面扩展规范（MCPB）