African Speech Corpora MCP

Model Context Protocol을 구현하는 읽기 전용 서버입니다. 이는 Anthropic이 만든 공개 표준으로, 아프리카 언어(주로 Wolof, 그리고 Pulaar와 Sereer)의 공개 음성 코퍼스 위에서 동작합니다.

이 프로젝트는 Wolof 우선입니다. 2.0 카탈로그에는 14개 변형이 포함되어 있습니다: 원본 소스의 11개 변형과 3개의 파생물. Pulaar(ful)와 Sereer(srr)는 로컬 메트릭이 없는 Kallaama 변형으로만 표현됩니다. 이 프로젝트는 Swahili나 Amharic 커버리지를 주장하지 않습니다. 2026년 8월 26일에 생성된 번들 검증 잠금(validation lock)은 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)" 평가는 이 수준에 절대 포함되지 않습니다.

초(seconds)가 표준 기간 표현입니다. 소수점 시간과 HH:MM:SS 문자열은 직렬화 시 파생됩니다. 모든 감사 메트릭은 범위, 소스, 방법, 관찰 날짜, 신뢰도를 명시합니다. 누락된 값은 null로 유지되며 0으로 변환되지 않습니다. 프로젝트가 게시한 수치는 로컬 관찰과 분리되어 published_metrics 아래에 유지됩니다.

Related MCP server: dspace-mcp

2026 Wolof 스냅샷

기계 판독 가능한 소스는 assets/wolof-audit-2026.csv입니다. 프로토콜, 제한 사항, 소스 테이블의 TOTAL 셀과의 불일치는 assets/wolof-audit-2026.md에 문서화되어 있습니다.

7개의 Wolof 변형에 로컬 관찰이 있습니다: ALFFA, FLEURS wo_sn, Kallaama Wolof, Urban Bus, Waxal crowdsource, Wolof TTS Baamtu, WolBanking77. 합계는 이 7개 행에서 다시 계산되며 중복된 수동 합계로 저장되지 않습니다: 사용 가능한 파일 148,102개, 전사된 파일 64,609개, 감사 수락 파일 50,494개, 오디오 2,329,382.06초, 전사된 초 515,185.06초, 감사 수락 초 302,048.06초.

중요한 제한 사항:

• "사전(a priori)"으로 설명된 FLEURS, Urban Bus, Waxal, Wolof TTS, WolBanking77 관찰은 audit_assumed_valid이며 전문가 검증이 아닙니다;

• ALFFA는 이 스냅샷에서 전문가 검증 파일이 명시적으로 0개입니다;

• 153개의 Kallaama 파일은 153개의 음성 턴이 아니라 긴 라디오 또는 인터뷰 녹음입니다; 36개 파일과 12:49:36은 로컬 프로토콜의 source_reported_expert 기준에 귀속됩니다;

• Urban Bus에는 정량화된 비율 없이 상당한 프랑스어 콘텐츠가 포함되어 있어 language_purity=mixed_fr입니다;

• Waxal은 517:38:05의 원시 오디오(특히 SSL에 유용)를 지도 ASR용으로 전사된 13:41:28과 분리합니다;

• 로컬 Wolof TTS Baamtu 스냅샷(36,009개 파일, 37:04:49)은 반올림된 공개 메트릭과 다르며, 이 TTS 코퍼스는 기본적으로 ASR에서 제외됩니다;

• WolBanking77은 관찰된 2,563개 오디오 파일을 다른 곳에서 보고된 9,791개 텍스트 구문과 구분합니다;

• Afrivoice는 530.74시간의 Wolof 오디오(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 도구

8개 도구 모두 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개의 손상 또는 비Wolof 파일이 있음을 확립하지만 행 식별자를 제공하지 않습니다. 따라서 서버는 해당 행을 제거했다고 가장하지 않습니다.

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는 이를 결정적으로 휠에 포함합니다. 테스트는 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. 수동 TOTAL 행이 아닌 단위 행을 CSV에 추가합니다;

2. audit_id, observed_at, source_reference, 방법, 신뢰도, 검증 기준을 제공합니다;

3. 관찰된 0과 누락된 값을 구분합니다;

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에서 이러한 검사를 실행하고, 빌드된 휠을 깨끗한 환경에 설치하고, CLI와 실제 MCP stdio 교환을 모두 테스트합니다. 버전 2.0.0은 문서화된 주요 변경 릴리스입니다: 공개 단위는 이제 더 구조화된 품질 응답을 가진 단일 언어, 단일 작업, 단일 구성 변형입니다.

라이선스

서버 코드는 Apache-2.0에 따라 라이선스가 부여됩니다. 각 코퍼스는 자체 라이선스를 유지합니다. TO BE CONFIRMED 또는 SEE DATASET ...로 표시된 카탈로그 항목은 의도적으로 불확실하게 유지되며, 특히 상업적 사용 전에 기본 소스와 대조하여 확인해야 합니다.