Telco MCP

Un servidor MCP local y de solo lectura para el análisis gobernado de retención sobre una instantánea de Telco Customer Churn fijada mediante checksum. Claude Code o Codex interpreta el lenguaje de negocio; el servidor es el propietario de las definiciones de métricas, las consultas acotadas, la ejecución de agregados, las salvedades y la procedencia. No existe ningún LLM en el servidor ni clave de API de modelo.

Por qué existe

El código fuente de este proyecto surge del flujo de trabajo de análisis de datos de autoservicio de Anthropic: los usuarios de negocio deberían poder pedir una cifra sin que un modelo tenga que inventar el SQL o la lógica de la métrica. El modelo anfitrión interpreta la intención, mientras que el MCP expone únicamente definiciones semánticas revisadas y operaciones agregadas deterministas. Con esto se reduce considerablemente el riesgo de alucinación, pero no se asegura que el enrutado del modelo anfitrión o la redacción final nunca puedan fallar.

Related MCP server: spreadsheet-qa-kit MCP server

Inicio más rápido: instalación manual en tu agente

Abre este repositorio en Claude Puppet o Codex y envía:

Lee INSTALL.md, instala y verifica este proyecto de principio a fin, e informa de la lista de verificación final. Respeta sus condiciones de parada; no modifiques el código de la aplicación ni la configuración de clientes no relacionada.

INSTALL.md es el runbook de instalación completo. Prepara el registro accidental de los datos, registra el MCP en los clientes seleccionados, verifica el protocolo de ocho herramientas y explica la recuperación y desinstalación seguras.

Configuración directa

Requisitos previos: Git, uv y Claude Code y/o Codex. El Python 3.12 y las dependencias fijadas (locked) las gestiona uv.

Se trata de una aplicación con alcance de repositorio porque el catálogo semántico y el manifiesto de fuentes son activos de gobernanza a nivel de repositorio. Si quieres, clona el repositorio y ejecuta con uv. La instalación como artefacto independiente o a través de PyPI no está soportada deliberadamente.

uv run --frozen telco-mcp setup --clients claude,codex
uv run --frozen telco-mcp doctor --clients claude,codex

Usa solo los clientes instalados, por ejemplo --clients codex. La autenticación de cliente es independiente del MCP; el servidor en sí no necesita credenciales de modelo.

A continuación, pregunta al cliente:

Usando el Telco MCP, ¿qué es el churn? Indica el denominador y la limitación de la instantánea.

Una respuesta gobernada empezará por el predeterminado revisado y etiquetar la alternativa:

• 26,5370 % = 1.869 / 7.043: la cuota certificada de churn sobre todos los registros de la instantánea y el predeterminado para preguntas generales.

• 28,3655 % = 1.869 / 6.589: una alternativa donde la base de partida asumida es usar Stayed + Churn, como proxy de la tasa de churn.

Debe indicar que los datos son una única instantánea de un trimestre, no una tendencia.

Qué ofrece el proyecto

• Ocho herramientas MCP con tipos para visiones generales de negocio, contexto, descubrimiento del catálogo, métricas, diagnóstico de segmentos, auditoría de fairness, motivos de churn registrados y guía estructurada de capacidad/negación.

• Versión semántica de datos con cinco conceptos de negocio, 34 métricas gobernadas y 29 dimensiones.

• Desgloses descriptivos unidimensionales y bidimensionales con filtros y poblaciones acotadas.

• Análisis agregado de cargos, ingresos acumulados, devoluciones, uso, satisfacción, servicio y motivos.

• Preparación fijada por checksum, DuckDB de solo lectura, procedencia de resultados ligada al nombre de la fuente y arranque verificado con cierre ante fallos (fail-closed). Un fixture sintético del protocolo solo existe tras la activación explícita.

• Skills espejo opcionales de Claude/Codex que mejoran el enrutado sin sustituir el contrato del MCP.

El proyecto no proporciona, intencionalmente, tendencias, cohortes, NRR/GRR, churn de ingresos (revenue churn), previsiones, predicciones, afirmaciones causales, impacto en escenarios anualizados, ROI, lift, SQL arbitrario ni exportaciones a nivel de cliente.

Arquitectura

Business question
  → Claude Code / Codex (+ optional Skill)
  → eight typed MCP tools
  → governed semantic layer
  → bounded parameterized compiler
  → read-only DuckDB
  → aggregate evidence + caveats + provenance
  → business-language answer

La explicación técnica y de negocio completa —incluyendo herramientas, datos, métricas, cobertura de preguntas, limitaciones, seguridad, ejemplos verificados y referencias de fuentes— está en docs/PROJECT_GUIDE.md.

Ordenes comunes

# Prepare or refresh the verified local artifact
uv run --frozen telco-mcp prepare

# Show the installed application version
uv run --frozen telco-mcp --version

# Register and verify selected clients
uv run --frozen telco-mcp setup --clients claude,codex
uv run --frozen telco-mcp doctor --clients claude,codex

# Run deterministic engineering checks
uv run --frozen pytest
uv run --frozen ruff check .
uv run --frozen mypy src scripts evals
uv audit --frozen

# Remove only this project's registrations; keep prepared data
uv run --frozen telco-mcp uninstall --clients claude,codex

Ejemplos de reparación manual están disponibles en .mcp.json.example y en .codex/config.toml.example. Prefiere setup porque resuelve las rutas exactas y rechaza registros con conflictos salvo que --replace se apruebe explícitamente.

Datos y privacidad

Los datos son una fuente ficticia/simulada de California3 con 7.043 registros únicos de clientes. Los tres archivos fuente, la revisión y los valores SHA-256 están fijados en data/source_manifest.json. Los CSV crudos y los artefactos preparados de DuckDB incluidos el a nivel de control de versiones porque no se han confirmado los derechos de redistribución. Lee DATA_NOTICE.md antes de descargar o usar los datos de origen.

El servicio solo expone resultados agregados. Los entornos locales, los datos de ejecución, la configuración del MCP, las credenciales, las claves privadas, las trazas nativas y los registros completos de respuestas de evaluación quedan excluidos mediante .gitignore.

Evaluación opcional para desarrolladores

La evaluación nativa de Codex no forma parte ni de la instalación, ni del setup, ni del run doctor, ni de las pruebas, ni de la CI. Esa evaluación puede suponer consumo de modelos y es deliberadamente opt-in. La evaluación completa consiste en 15 preguntas de tipo golden. Cada caso usa una sesión de respuestas nueva y una sesión de juez separada; las comprobaciones deterministas de la evidencia son un control adicional infrancionable. Una ejecución completa lanza, por tanto, 30 sesiones de Codex:

uv run --frozen python evals/run_native_matrix.py \
  --output-root evals/results/golden-15-new-run

El runner imprime el número planificado de sesiones de respuesta/juez antes de empezar y deja la decisión local en JSON y en Markdown. Publica solo artefactos que hayan sido revisados y cleaned. El último informe completado obtuvo un 14/15 y dejó a la luz de una inconsistencia que estaba fuera del valor por defecto de fairness y que se ha corregido en el código actual. Una nueva se reedición tras la corrección se detuvo para controlar el gasto de tokens de Codex, por lo que ese informe es, de forma explícita, una evidencia anterior a la corrección y no una certificación actual. Consulta evals/README.md.

Licencia

El código del repositorio está licenciado bajo MIT; los derechos del conjunto de datos de origen son independientes. Consulta LICENSE, DATA_NOTICE.md, CONTRIBUTING.md y SECURITY.md.