African Speech Corpora MCP

Сервер только для чтения, реализующий Model Context Protocol — открытый стандарт, созданный Anthropic, для работы с публичными речевыми корпусами африканских языков: в первую очередь волоф, а также пулаар и серер.

Проект ориентирован в первую очередь на волоф (Wolof-first). Каталог 2.0 содержит 14 вариантов: 11 вариантов исходных источников и 3 производных. Пулаар (ful) и серер (srr) представлены только вариантами Kallaama без локальных метрик; проект не заявляет о покрытии суахили или амхарского. Встроенная блокировка валидации, созданная 26 августа 2026 года, делает доступными для запросов 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. Оценка «a priori» никогда не попадает на этот уровень.

Секунды являются каноническим представлением длительности. Десятичные часы и строки 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 Wolof, Urban Bus, Waxal crowdsource, 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, описанные как «a priori», являются 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 -m venv .venv безопасно только в том случае, если этот исполняемый файл python уже является Python 3.11 или новее. Если установка завершается ошибкой, например:

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, если явно не разрешены, а производные никогда не добавляются к своим родителям. Неизвестные, некоммерческие, с условием share-alike или неподтверждённые лицензии вызывают соответствующие предупреждения; 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 ..., намеренно остаются неопределёнными и должны быть проверены по первоисточнику перед любым использованием, особенно коммерческим.