Telco MCP

一个本地、只读的 MCP 服务器，用于对校验和固定的 Telco Customer Churn 快照进行受治理的留存分析。Claude Code 或 Codex 负责解释业务语言；服务器自身拥有指标定义、受限查询、聚合执行、注意事项与数据源追溯。系统没有服务端 LLM，也不需要任何模型 API 密钥。

为什么需要这个项目

本项目的灵感来自 Anthropic 的自助数据分析工作流：业务用户应该能够直接查询一个数字，而不必让模型去发明 SQL 或指标口径。宿主模型负责理解意图，而 MCP 只暴露经过审核的语义定义和确定性的聚合操作。这大大降低了幻觉风险，但这并不意味着宿主模型的路由判断或最终措辞永远不会出错。

Related MCP server: spreadsheet-qa-kit MCP server

最快上手：手动安装到你的 Agent

在 Claude Code 或 Codex 中打开本仓库，然后发送以下指令：

阅读 INSTALL.md，端到端安装并验证本项目，然后填写最终清单。 遵守其中的停止条件；不要修改应用代码或无关的客户端配置。

INSTALL.md 是一份完整的安装手册，负责准备校验和锁定的数据、向所选客户端注册 MCP、校验八个工具的协议，并说明安全的恢复与卸载方式。

直接配置

前置要求：Git、uv，以及 Claude Code 和/或 Codex。Python 3.12 和锁定版本的依赖项由 uv 管理。

这是一个仓库级应用：克隆源代码并用 uv 运行。特意不支持单独的 wheel 或 PyPI 安装，因为语义目录和源清单属于仓库级的治理资产。

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

只使用已安装的客户端，例如 --clients codex。客户端身份认证与 MCP 本身相互独立，服务器自身不需要任何模型凭据。

然后向客户端提问：

使用 telco MCP，什么是客户流失（churn）？请说明分母和快照的局限。

一个有治理的答案会先给出经过评审的默认口径，并对备选口径进行标注：

• 26.5370% = 1,869 / 7,043：在全部快照记录中经认证的流失占比，也是泛化问题场景下的默认回答。

• 28.3655% = 1,869 / 6,589：备选口径，将 Stayed 与 Churned 假定为起始基数而计算的 logo 客户流失率代理指标。

它还必须说明：该数据只是一个 Q3 快照，而不是一个趋势。

项目提供了什么

• 八个强类型 MCP 工具，用于业务总览、上下文、目录发现、指标查询、细分诊断、公平性审计、已记录的流失原因，以及结构化的能力/拒答指导。

• 语义版本 4，包含 5 个业务概念、34 个受管控指标和 29 个维度。

• 带受限过滤器和确定总体的单维度/双维度描述性拆分。

• 对费用、累计收入、退款、用量、满意度、服务以及原因分析进行聚合计算。

• 校验和锁定数据准备、只读 DuckDB、可追溯到源头的结果来源，以及 fail-closed（隐式关闭）的验证型启动。仅在选择显式 opt-in 时才存在合成协议测试夹具。

• 可选的 Claude Code/Codex Skills 镜像，能在不替代 MCP 契约的前提下改进路由。

它故意不提供趋势、同期群、NRR/GRR、收入流失、预测、推断、因果关系断言、情景/年化影响、ROI、提升（uplift）、任意 SQL 或客户级导出。

架构

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

涉及工具、数据、指标、问题覆盖范围、局限性、安全性、已验证示例和引用来源的内容都在 docs/PROJECT_GUIDE.md 中有完整的技术和业务介绍。

常用命令

# 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

手工修复示例可在 .mcp.json.example 和 .codex/config.toml.example 中找到。推荐使用 setup，因为它能解析正确路径，并在没有得到 --replace 明确批准时拒绝同一位置的重复注册。

数据与安全

这是一个虚构/模拟的 Q3 加州快照，包含 7,043 条唯一客户记录。三个源文件、副本及 SHA-256 值均已固定记录在 data/source_manifest.json 中。原始 CSV 和制备好的 DuckDB 工件没有被提交，因为再分发权尚未确认。请务必阅读 DATA_NOTICE.md 后再下载或使用上游数据。

服务只暴露聚合结果。本地环境、运行时数据、MCP 配置、凭据、私钥、原生调用堆栈测试以及完整评估响应记录都通过 .gitignore 剔除。

可选开发者评估

原生 Codex 评估不属于安装、setup、doctor、测试或 CI 的一环。它会消耗模型用量，所以是有意设定为显式开启（opt-in）的。整个评估恰好包含 15 个黄金问题。每个案例各使用一个全新的回答会话和一个独立的评判者会话；“确定性证据核查”是额外的一道硬关卡。因此完整运行会启动 30 个 Codex 会话：

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

运行器会在开始前打印预期的回答/评判数，并在本地写出 JSON 与 Markdown 判定结果。发布前请只公开那些已经过审查和脱敏处理的结果。 最后一份已完成的报告 为 14/15 分，并暴露了一个公平性默认值不一致的问题，当前代码中已经修复。修复后的复跑为控制 Codex token 消耗已被停止，因此该报告只代表修复前的证据，而非当前认证。具体请见 evals/README.md。

许可证

仓库代码采用采用 MIT 许可；源数据集的独立权利与它们本身并存。详见 LICENSE、DATA_NOTICE.md、CONTRIBUTING.md 和 SECURITY.md。