African Speech Corpora MCP

Un servidor de solo lectura que implementa el Model Context Protocol, un estándar abierto creado por Anthropic, sobre corpus de habla públicos para lenguas africanas: wolof en primer lugar, además de pulaar y sereer.

El proyecto es prioritariamente wolof. El catálogo 2.0 contiene 14 variantes: 11 variantes de fuentes originales y 3 derivadas. Pulaar (ful) y Sereer (srr) están representados solo por variantes Kallaama sin métricas locales; el proyecto no afirma cobertura de suajili ni amárico. El bloqueo de validación incluido, generado el 26 de agosto de 2026, hace consultables 6 variantes de Hugging Face. Una ejecución de validación posterior puede producir naturalmente un estado diferente.

El servidor no entrena modelos, descarga corpus completos ni escribe en Hugging Face, OpenSLR, Kaggle, GitHub ni ninguna otra fuente remota.

Lo que mide el servidor

El pipeline de calidad mantiene separadas las siguientes etapas:

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

• Crudo: un archivo presente en la instantánea observada.

• Utilizable: un archivo que permanece tras las exclusiones cuantificables de la auditoría.

• Transcrito: audio asociado a una transcripción.

• Aceptado por auditoría: una unión explícitamente nombrada de material verificado por expertos y material solo asumido como válido por la auditoría.

• Verificado por expertos: solo expert_audited o source_reported_expert. Una evaluación “a priori” nunca entra en este nivel.

Los segundos son la representación canónica de la duración. Las horas decimales y las cadenas HH:MM:SS se derivan en el momento de la serialización. Cada métrica auditada indica su alcance, fuente, método, fecha de observación y confianza. Un valor faltante permanece como null; nunca se convierte en cero. Las cifras publicadas por un proyecto permanecen en published_metrics, separadas de las observaciones locales.

Related MCP server: dspace-mcp

Instantánea wolof 2026

La fuente legible por máquina es assets/wolof-audit-2026.csv. El protocolo, las limitaciones y las discrepancias con las celdas TOTAL de la tabla fuente están documentados en assets/wolof-audit-2026.md.

Siete variantes wolof tienen una observación local: ALFFA, FLEURS wo_sn, Kallaama Wolof, Urban Bus, Waxal crowdsource, Wolof TTS Baamtu y WolBanking77. Los totales se recalculan a partir de estas siete filas y nunca se almacenan como un total manual redundante: 148,102 archivos utilizables, 64,609 archivos transcritos, 50,494 archivos aceptados por auditoría, 2,329,382.06 segundos de audio, 515,185.06 segundos transcritos y 302,048.06 segundos aceptados por auditoría.

Limitaciones importantes:

• las observaciones de FLEURS, Urban Bus, Waxal, Wolof TTS y WolBanking77 descritas como “a priori” son audit_assumed_valid, no verificadas por expertos;

• ALFFA tiene explícitamente cero archivos verificados por expertos en esta instantánea;

• los 153 archivos Kallaama son grabaciones largas de radio o entrevistas, no 153 turnos de habla; 36 archivos y 12:49:36 se atribuyen a la base source_reported_expert del protocolo local;

• Urban Bus contiene contenido sustancial en francés sin una tasa cuantificada y por lo tanto tiene language_purity=mixed_fr;

• Waxal separa 517:38:05 de audio crudo, utilizable notablemente para SSL, de solo 13:41:28 transcritos para ASR supervisado;

• la instantánea local de Wolof TTS Baamtu—36,009 archivos y 37:04:49—es distinta de la métrica pública redondeada, y este corpus TTS se excluye de ASR por defecto;

• WolBanking77 distingue 2,563 archivos de audio observados de las 9,791 frases de texto reportadas en otro lugar;

• Afrivoice publica 530.74 horas de audio wolof, incluyendo 102.96 horas transcritas. Estas son cifras publicadas por la fuente, no mediciones de la auditoría local de 2026 ni evidencia de verificación experta. El conjunto de datos está auto-restringido en Hugging Face, por lo que sus archivos, esquema, divisiones y duraciones no pueden verificarse de forma independiente sin aceptar sus condiciones de acceso y proporcionar un token; por lo tanto, permanece en audit_status=pending;

• debido a que la fecha exacta de observación de la fuente no está disponible, observed_at=2026 tiene intencionalmente precisión solo de año.

Instalación

El paquete requiere Python 3.11 o superior. Se recomienda Python 3.12 y se selecciona explícitamente a continuación para que el entorno virtual no herede accidentalmente un intérprete de sistema más antiguo, como 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 .

Ambos comandos de versión deberían reportar Python 3.12.x. Crear el entorno con python -m venv .venv es seguro solo cuando ese ejecutable python ya es Python 3.11 o superior. Si la instalación falla con un error como:

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

entonces el entorno virtual se creó con Python 3.9.6. Desactívelo, elimine o renombre ese .venv local, instale Python 3.12 si es necesario y vuelva a crear el entorno con python3.12 -m venv .venv. Un entorno virtual conserva el intérprete con el que se creó; activarlo no actualiza Python.

El servidor stdio se inicia sin argumentos:

african-speech-mcp

También se puede iniciar explícitamente:

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

Ejemplo de configuración de Claude Desktop después de instalar el paquete, preferiblemente usando una ruta absoluta:

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

Este refactor no publica el paquete. No use uvx ni un identificador de PyPI hasta que se haya publicado explícitamente una versión.

Herramientas MCP

Las ocho herramientas declaran read_only_hint=true, destructive_hint=false e idempotent_hint=true.

Ejemplos conceptuales:

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,
)

La última llamada actualmente devuelve filter_available=false. Los totales agregados establecen que Waxal contiene 430 duplicados y 22 archivos corruptos o no wolof, pero no proporcionan identificadores de fila. Por lo tanto, el servidor se niega a fingir que eliminó esas filas.

Semántica de plan_training_set

quality acepta:

• any: seleccionar por tarea y licencia sin requerir transcripción;

• transcribed: usar la duración realmente transcrita;

• audit_accepted: incluir material experto y asumido como válido, con un desglose visible y una advertencia;

• expert_verified: usar solo bases de verificación genuinamente expertas;

• wolof_only: excluir mixed_fr, mixed, unknown y variantes sin evidencia suficiente de pureza de idioma.

metric_source es latest_audit (el predeterminado) o published. Las variantes sin una duración conocida permanecen listadas en hours_unknown_for. FLEURS es un benchmark y se mantiene fuera del entrenamiento a menos que include_benchmarks=true. Urban Bus requiere include_mixed_language=true. Las variantes TTS se mantienen fuera de ASR a menos que se habiliten explícitamente, y los derivados nunca se agregan a sus padres. Las licencias desconocidas, no comerciales, share-alike o no confirmadas producen advertencias apropiadas; commercial_use=null nunca se presenta como comercialmente compatible.

Validación persistente de Hugging Face

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

La validación verifica el identificador del conjunto de datos, la configuración, las divisiones, la columna de transcripción y cualquier columna de idioma declarada. El bloqueo se escribe mediante reemplazo atómico y registra checked_at, la información de esquema observada y una huella digital estable. También está vinculado al hash del catálogo, por lo que el servidor rechaza un bloqueo obsoleto.

Por defecto, --write crea validation-lock.json en el directorio actual sin modificar el paquete instalado. Para usarlo después:

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

Los estados posibles son unverified, verified, gated, unavailable, schema_mismatch y quality_blocked. Un identificador que responde nunca se marca como verified cuando falta la configuración o columna esperada. Para Afrivoice, establezca ASM_HF_TOKEN localmente antes de la validación; el token no se serializa ni se registra.

corpus_stats filtra estrictamente por configuración, por lo que FLEURS wo_sn nunca incluye otro idioma. Una distribución multilingüe sin una configuración separada debe declarar una columna de idioma y valores aceptados. Cuando el servidor no puede garantizar ese filtro, rechaza la solicitud o devuelve una advertencia explícita.

Catálogo y arquitectura

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

Ya no existe un segundo corpora.json a nivel raíz. El CSV de auditoría sigue siendo canónico en assets/, y Hatch lo incluye de manera determinista en la rueda. Las pruebas verifican totales y referencias entre el CSV y el catálogo.

Las variables útiles incluyen ASM_CATALOG_PATH, ASM_VALIDATION_LOCK_PATH, ASM_AUDIT_LOG_PATH, ASM_HF_TOKEN, ASM_REQUEST_TIMEOUT_S, ASM_REQUEST_RETRIES y ASM_VALIDATION_CONCURRENCY. Los registros de ejecución van a stderr para que stdout permanezca reservado para el protocolo stdio.

Contribuir con una auditoría o manifiesto

Una nueva auditoría debe:

1. agregar filas unitarias al CSV, nunca una fila TOTAL manual;

2. proporcionar audit_id, observed_at, source_reference, método, confianza y base de verificación;

3. distinguir un cero observado de un valor faltante;

4. referenciar la auditoría desde la variante correspondiente;

5. documentar las limitaciones en Markdown y agregar pruebas de consistencia.

Para habilitar el filtrado real, proporcione un manifiesto versionado con al menos:

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

Los identificadores deben provenir de la instantánea auditada. Nunca deben inventarse a partir de recuentos agregados.

Desarrollo y preparación de versiones

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

CI ejecuta estas comprobaciones en Python 3.11 y 3.12, instala la rueda construida en un entorno limpio y prueba tanto la CLI como un intercambio real de MCP stdio. La versión 2.0.0 es una versión de ruptura documentada: la unidad pública ahora es una variante de un solo idioma, una sola tarea y una sola configuración con respuestas de calidad más estructuradas.

Licencia

El código del servidor está licenciado bajo Apache-2.0. Cada corpus conserva su propia licencia. Las entradas del catálogo marcadas como TO BE CONFIRMED o SEE DATASET ... permanecen intencionalmente inciertas y deben verificarse contra la fuente primaria antes de cualquier uso, especialmente el uso comercial.