Telco MCP

チェックサムで固定されたTelco Customer Churnスナップショットに対して、ガバナンスに従ったリテンション分析を提供する、ローカルで読み取り専用のMCPサーバーです。Claude CodeまたはCodexがビジネス上の質問を解釈し、サーバーはメトリクスの定義、制約付きクエリ、集計実行、注意事項、来歴（provenance）を管理します。サーバー側にはLLMは存在せず、モデルAPIキーも必要ありません。

このプロジェクトが存在する理由

このプロジェクトは、Anthropicのセルフサービスデータ分析ワークフローから着想を得ています。ビジネスユーザーは、モデルにSQLやメトリクスのロジックを考案させることなく、数値を質問できるべきです。ホストモデルが意図を解釈し、MCPはレビュー済みのセマンティック定義と決定論的な集計操作のみを公開します。これにより幻覚リスクを大幅に減らせますが、ホストモデルのルーティングや最終的な表現が絶対に誤らないと主張するものではありません。

Related MCP server: spreadsheet-qa-kit MCP server

最速の始め方：エージェントにインストールを任せる

このリポジトリをClaude CodeまたはCodexで開き、次のメッセージを送ってください。

INSTALL.mdを読み、このプロジェクトをエンドツーエンドでインストール・検証し、最終チェックリストを報告してください。 停止条件に従い、アプリケーションコードや関係のないクライアント設定を変更しないでください。

INSTALL.mdは完全なインストール手順書です。固定されたデータを準備し、選択したクライアントにMCPを登録し、8つのツールで構成されるプロトコルを検証し、安全な復旧とアンインストールを説明しています。

直接セットアップ

前提条件：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を使って、チャーン（離脱）の状態を教えてください。分母とスナップショットの制約を明記してください。

ガバナンスに沿った回答では、レビュー済みのデフォルトを最初に示し、代替案を明記します。

• 26.5370% = 1,869 / 7,043：全スナップショット・レコードに占める、認定済みチャーン割合であり、広い質問に対するデフォルトです。

• 28.3655% = 1,869 / 6,589 ： Stayed + Churnedを使用した、代替の想定開始ベース、のchurn率プロキシです。

また、データがQ3の単一スナップショットであり、トレンドではないことを必ず述べる必要があります。

このプロジェクトが提供するもの

• ビジネスの概要、文脈、カタログ探索、メトリクス、セグメント診断、公平性監査、記録されたチャーンの理由、構造化された機能・拒否ガイドのための、8つの型付きMCPツール。

• セマンティックバージョン4。5つのビジネス概念、34のガバナンス対象メトリクス、および29のディメンションが含まれます。

• 制約付きフィルタと集計母集団を使った、1次元および2次元の記述ブレークダウン。

• 集計チャージ、累積収益、払戻し、利用量、満足度、サポート、理由の集計解析。

• チェックサム固定によるデータ準備、読み取り専用DuckDB、ソースに紐づく結果の来歴、検証済みかつフェールクローズの起動。合成プロトコルフィクスチャは、明示的なオプトイン時のみ利用できます。

• オプションのミラー版Claude Code／Codexスキル。MCP契約を置き換えずにルーティングを改善します。

意図的に提供しない機能は、トレンド、コホート、NRR／GRR、収益チャーン、フォアキャスト、予測、因果関係の主張、シナリオ・年換算スケーリングへの影響、ROI、アップリフト、任意の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件の一意な顧客レコードが含まれます。3つのソースファイル、リビジョン、SHA-256値は、data/source_manifest.jsonに固定されています。再配布権が確認できていないため、元のCSVおよび準備済みDuckDBの成果物はコミットしていません。上位のデータを取得または利用する前に、DATA_NOTICE.mdをお読みください。

このサービスは集計結果のみを公開します。ローカルの環境設定、実行時データ、MCP構成、認証情報、秘密鍵、ネイティブトレース、完全な評価応答レコードは、.gitignoreによって除外されています。

任意の開発者評価

Codexネイティブの評価は、インストール、セットアップ、doctor、テスト、CIの一部ではありません。モデル利用量を消費するため、意図的にオプトインです。評価全体は15のゴールデンクエスチョンで構成されています。各ケースでは、新しい応答セッションと専用のジャッジセッションを使用し、さらに決定的なエビデンスチェックを追加のゲートとして行います。フル実行は30のCodexセッションを開始します。

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

実行前に、事前設定された応答・ジャッジセッション数を出力し、ローカルのJSONおよびMarkdownの判定結果を書き出します。公開は、レビューとサニタイズ済みの成果物のみにしてください。最後に完了したレポートは14/15で、現在のコードで修正されたfairnessデフォルトの矛盾を明らかにしました。修正後の再実行は、Codexのトークン使用量を抑える目的で停止したため、そのレポートは修正前の証拠であり、現在の証明ではありません。まず、evals/README.mdを参照してください。

ライセンス

リポジトリのコードはMITライセンスです。データセット自体の権利は別途定められますができます。各ライセンスの詳細は、LICENSE、DATA_NOTICE.md、CONTRIBUTING.md、SECURITY.mdをご確認ください。