African Speech Corpora MCP

一个只读服务器，实现了由 Anthropic 创建的开放标准 Model Context Protocol，用于非洲语言的公共语音语料库：首先是沃洛夫语，另外还有普拉尔语和塞雷尔语。

该项目以沃洛夫语优先。2.0 目录包含 14 个变体：11 个原始来源变体和 3 个衍生变体。普拉尔语（ful）和塞雷尔语（srr）仅由 Kallaama 变体表示，没有本地指标；该项目不声称覆盖斯瓦希里语或阿姆哈拉语。随附的验证锁文件生成于 2026 年 8 月 26 日，使 6 个 Hugging Face 变体可查询。后续的验证运行自然可能产生不同的状态。

该服务器不训练模型、不下载完整语料库，也不向 Hugging Face、OpenSLR、Kaggle、GitHub 或任何其他远程源写入数据。

服务器衡量什么

质量流水线将以下阶段分开：

raw audio → usable audio → transcribed audio → audit-accepted audio → expert-verified audio

• 原始（Raw）：在观察到的快照中存在的文件。

• 可用（Usable）：在审计的可量化排除之后剩余的文件。

• 已转写（Transcribed）：与转写文本关联的音频。

• 审计接受（Audit accepted）：明确命名的专家验证材料与审计仅假设有效的材料的并集。

• 专家验证（Expert verified）：仅 expert_audited 或 source_reported_expert。“先验”评估永远不会进入此级别。

秒是规范的时长表示。十进制小时和 HH:MM:SS 字符串在序列化时派生。每项审计指标都说明其范围、来源、方法、观察日期和置信度。缺失值保持为 null；永远不会转换为零。项目发布的数字保留在 published_metrics 下，与本地观察分开。

Related MCP server: dspace-mcp

2026 年沃洛夫语快照

机器可读来源是 assets/wolof-audit-2026.csv。协议、限制以及与源表 TOTAL 单元格的差异记录在 assets/wolof-audit-2026.md 中。

七个沃洛夫语变体有本地观察：ALFFA、FLEURS wo_sn、Kallaama 沃洛夫语、Urban Bus、Waxal 众包、Wolof TTS Baamtu 和 WolBanking77。总计从这七行重新计算，从不存储为冗余的手动总计：148,102 个可用文件、64,609 个已转写文件、50,494 个审计接受文件、2,329,382.06 秒音频、515,185.06 秒已转写音频和 302,048.06 秒审计接受音频。

重要限制：

• 被描述为“先验”的 FLEURS、Urban Bus、Waxal、Wolof TTS 和 WolBanking77 观察是 audit_assumed_valid，而非专家验证；

• ALFFA 在此快照中明确有零个专家验证文件；

• 153 个 Kallaama 文件是长广播或访谈录音，而非 153 个语音轮次；36 个文件和 12:49:36 归属于本地协议的 source_reported_expert 基础；

• Urban Bus 包含大量法语内容，但没有量化比例，因此具有 language_purity=mixed_fr；

• Waxal 将 517:38:05 的原始音频（特别适用于 SSL）与仅 13:41:28 的监督 ASR 转写音频分开；

• 本地 Wolof TTS Baamtu 快照——36,009 个文件和 37:04:49——与公开的舍入指标不同，此 TTS 语料库默认排除在 ASR 之外；

• WolBanking77 区分了 2,563 个观察到的音频文件与别处报告的 9,791 个文本短语；

• Afrivoice 发布了 530.74 小时的沃洛夫语音频，包括 102.96 小时的已转写音频。这些是来源发布的数字，而非 2026 年本地审计的测量结果，也不是专家验证的证据。该数据集在 Hugging Face 上自动门控，因此其文件、模式、分割和时长无法在不接受其访问条件并提供令牌的情况下独立检查；因此它保持 audit_status=pending；

• 由于确切的来源观察日期不可用，observed_at=2026 特意只有年份精度。

安装

该包需要 Python 3.11 或更新版本。推荐使用 Python 3.12，并在下面明确选择，以便虚拟环境不会意外继承较旧的系统解释器（如 Python 3.9）：

git clone https://github.com/papasega/african-speech-mcp.git
cd african-speech-mcp
python3.12 --version
python3.12 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install -e .

两个版本命令都应报告 Python 3.12.x。仅当该 python 可执行文件已经是 Python 3.11 或更新版本时，使用 python -m venv .venv 创建环境才是安全的。如果安装失败并出现如下错误：

ERROR: Package 'african-speech-mcp' requires a different Python: 3.9.6 not in '>=3.11'

则虚拟环境是使用 Python 3.9.6 创建的。停用它，删除或重命名该本地 .venv，如有必要安装 Python 3.12，并使用 python3.12 -m venv .venv 重新创建环境。虚拟环境保留创建它的解释器；激活它不会升级 Python。

stdio 服务器无需参数即可启动：

african-speech-mcp

也可以显式启动：

african-speech-mcp serve --transport stdio
african-speech-mcp serve --transport streamable-http

安装包后的示例 Claude Desktop 配置，最好使用绝对路径：

{
  "mcpServers": {
    "african-speech-corpora": {
      "command": "/absolute/path/to/.venv/bin/african-speech-mcp"
    }
  }
}

此重构不发布该包。在明确发布版本之前，不要使用 uvx 或 PyPI 标识符。

MCP 工具

所有八个工具都声明 read_only_hint=true、destructive_hint=false 和 idempotent_hint=true。

概念性示例：

audit_corpus(corpus="waxal-crowdsource")

plan_training_set(language="wol", task="asr", quality="transcribed")
plan_training_set(language="wol", task="asr", quality="expert_verified")
plan_training_set(
  language="wol",
  task="asr",
  quality="audit_accepted",
  include_mixed_language=true,
)

filter_segments(
  corpus="waxal-crowdsource",
  exclude_duplicates=true,
  exclude_non_wolof=true,
  exclude_corrupt=true,
)

最后一次调用当前返回 filter_available=false。聚合总计确定 Waxal 包含 430 个重复文件和 22 个损坏或非沃洛夫语文件，但它们不提供行标识符。因此，服务器拒绝假装已删除这些行。

plan_training_set 语义

quality 接受：

• any：按任务和许可证选择，不要求转写；

• transcribed：使用实际转写的时长；

• audit_accepted：包括专家和假设有效的材料，并带有可见的细分和警告；

• expert_verified：仅使用真正的专家验证基础；

• wolof_only：排除 mixed_fr、mixed、unknown 以及没有足够语言纯度证据的变体。

metric_source 是 latest_audit（默认）或 published。没有已知时长的变体仍列在 hours_unknown_for 中。FLEURS 是基准，除非 include_benchmarks=true，否则不进入训练。Urban Bus 需要 include_mixed_language=true。TTS 变体除非显式启用，否则不进入 ASR，衍生体永远不会添加到其父级。未知、非商业、相同方式共享或未确认的许可证会产生适当的警告；commercial_use=null 永远不会被呈现为商业兼容。

持久化 Hugging Face 验证

african-speech-mcp validate
african-speech-mcp validate --write
african-speech-mcp validate --output validation-lock.json

验证检查数据集标识符、配置、分割、转写列以及任何声明的语言列。锁文件通过原子替换写入，并记录 checked_at、观察到的模式信息和稳定的指纹。它还绑定到目录哈希，因此服务器会拒绝过时的锁。

默认情况下，--write 在当前目录中创建 validation-lock.json，而不修改已安装的包。之后使用它：

export ASM_VALIDATION_LOCK_PATH="$PWD/validation-lock.json"
african-speech-mcp

可能的状态是 unverified、verified、gated、unavailable、schema_mismatch 和 quality_blocked。当预期的配置或列缺失时，响应的标识符永远不会被标记为 verified。对于 Afrivoice，在验证前在本地设置 ASM_HF_TOKEN；令牌既不会被序列化也不会被记录。

corpus_stats 严格按配置过滤，因此 FLEURS wo_sn 永远不会包含另一种语言。没有单独配置的多语言分布必须声明语言列和接受的值。当服务器无法保证该过滤时，它拒绝请求或返回显式警告。

目录和架构

src/african_speech_mcp/
├── audit.py              # audited CSV, duration formats, deterministic aggregation
├── catalog.py            # Pydantic v2 variants and invariants
├── cli.py                # serve, validate, catalog-show
├── config.py             # ASM_* settings
├── hf_client.py          # GET only, retries, bounded concurrency
├── models.py             # structured responses
├── server.py             # eight MCP tools
├── validation.py         # schema inspection and atomic lock files
└── data/
    ├── corpora.json      # single canonical catalog
    └── validation-lock.json

不再有第二个根级 corpora.json。审计 CSV 在 assets/ 下保持规范，Hatch 将其确定性地包含在 wheel 中。测试检查 CSV 和目录之间的总计和引用。

有用的变量包括 ASM_CATALOG_PATH、ASM_VALIDATION_LOCK_PATH、ASM_AUDIT_LOG_PATH、ASM_HF_TOKEN、ASM_REQUEST_TIMEOUT_S、ASM_REQUEST_RETRIES 和 ASM_VALIDATION_CONCURRENCY。运行时日志转到 stderr，以便 stdout 保留给 stdio 协议。

贡献审计或清单

新的审计必须：

1. 向 CSV 添加单元行，绝不添加手动 TOTAL 行；

2. 提供 audit_id、observed_at、source_reference、方法、置信度和验证基础；

3. 区分观察到的零和缺失值；

4. 从匹配的变体引用审计；

5. 在 Markdown 中记录限制并添加一致性测试。

要启用真正的过滤，请提供至少包含以下内容的版本化清单：

audit_id,corpus_key,revision,row_id,audio_path,is_duplicate,is_empty,is_corrupt,is_wolof,transcript_quality,reason

标识符必须来自审计的快照。绝不能从聚合计数中发明它们。

开发和发布准备

python -m pip install -e ".[dev]"
ruff check src tests scripts
pytest -q
python -m build

CI 在 Python 3.11 和 3.12 上运行这些检查，在干净环境中安装构建的 wheel，并测试 CLI 和真实的 MCP stdio 交换。版本 2.0.0 是文档化的破坏性发布：公共单元现在是单语言、单任务、单配置的变体，具有更结构化的质量响应。

许可证

服务器代码根据 Apache-2.0 许可。每个语料库保留其自己的许可证。标记为 TO BE CONFIRMED 或 SEE DATASET ... 的目录条目故意保持不确定，必须在使用前（尤其是商业使用）对照主要来源进行检查。