Telco MCP

체크스팬 핀(Telco) T. 뜻.Telco MCP? Tere are Texas? Hmm, maybe confusion. We must write correct. Let's think carefully.

Need produce no extraneous preamble. We'll output Korean Markdown.

Let's compose final answer with the full translation, not include any other wrapper.# 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 또는 OpenAI에서 열고 다음을 보내세요.

INSTALL.md를 읽고 이 프로젝트를 처음부터 끝까지 설치하고 검증한 후 최종 체크리스트를 보고하세요. 해당 문서가 표시한 중단 조건을 따르고 애플리케이션 코드나 관련 없는 클라이언트 설정은 수정하지 마세요.

INSTALL.md는 완전한 설치 운영 절차입니다. 고정된 데이터를 준비하고, 선택한 클라이언트에 MCP를 등록하며, 8개 도구로 이뤄진 프로토콜을 검증하고, 안전한 복구와 제거 방법을 설명합니다.

직접 설정

전제 조건: Git, uv, 그리고 Claude Code 및/또는 Codex. Python 3.12와 잠긴(locked) 의존성은 uv가 관리합니다.

이 프로젝트는 저장소에 한정된 애플리게이션입니다. 소스를 클론하고 uv로 실행하십시오. standalone wheel이나 PyPI 설치는 의도적으로 지원되지 않습니다. 의미 카탈로그와 소스 매니페스트는 저장소 수준의 거버넌스 자산이기 때문입니다.

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

설치된 클라이언트만 사용하세요. 예: --clients codex. 클라이언트 인증은 MCP와는 별개이며, 서버 자체에는 모델 자격 증명이 필요하지 않습니다.

그런 다음 클라이언트에게 이렇게 요청하세요:

텔코 MCP를 사용하여 churn이란 무엇인가요? 분모(denominator)와 스냅샷 한계를 명시하세요.

거버넌스가 적용된 답변은 검토된 기본값을 먼저 제시하고, 대안도 명확히 구분합니다:

• 26.5370% = 1,869 / 7,043: 인증된 고객 이탈 점유율로, 전체 스냅샷 레코드 기준이며 광범위한 질문의 기본값입니다.

• 28.3655% = 1,869 / 6,589: Stayed + Churned를 사용하는 가정적 시작 기준의 고객(로고) 이탈률 프록시입니다.

이 데이터는 하나의 Q3 스냅샷이며 추세(trend)가 아니라는 점도 반드시 말해야 합니다.

프로젝트가 제공하는 것

• 비즈니스 개요, 문맥, 카탈로그 검색, 지표, 세그먼트 진단, 공정성 감사, 기록된 이탈 사유, 그리고 구조화된 기능/거부 안내를 제공하는 8가지 유형의 MCP 도구.

• 5개의 비즈니스 개념, 34개의 관리되는 지표, 29개 차원으로 구성된 시맨틱 버전 4.

• 제한된 필터/모집단을 사용하는 1차원·2차원 기술적 분해.

• 전기/요금, 누적 수익, 환불, 사용량, 만족도, 서비스, 사유 분석의 집계.

• 체크섬으로 고정된 준비, 읽기 전용 DuckDB, 소스에 바인딩된 결과 출처, 그리고 실패 시 차단(fail-closed)하는 검증된 시작. 합성 프로토콜 픽스처는 명시적 동의(opt-in)하는 경우에만 존재합니다.

• MCP 계약을 대체하지 않으면서 라우팅을 개선할 수 있는 선택적으로 미러링된 Claude/Codex Skills.

다음은 의도적으로 제공하지 않습니다: 추세, 취약, NRR/GRR, 수익 이탈, 예측(forecast), 예측(prediction), 인과 관계 주장, 시나리오/연율화 영향, 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가 명시적으로 승인되지 않는 한 충돌하는 등록을 거부하는 setup을 권장합니다.

데이터와 개인정보

소스는 가상/시뮬레이션된 캘리포니아 Q3 스냅샷이며 7,043개의 고유 로우가 포함된 텨 7,043명입니다. 3개의 소스 파일, 리비전, SHA-256 항목은 data/source_manifest.json에 고정되어 있습니다. 원본 CSV와 준비된 DuckDB 아티팩트는 재배포 권한이 확인되지 않아 커밋되지 않습니다. 업스트림 데이터를 다운로드하거나 사용하기 전에는 DATA_NOTICE.md를 읽으세요.

이 서비스는 집계 결과만 노출합니다. 로컬 환경, 런타임 데이터, MCP 구성, 자격 증명, 개인 키, 네이티브 추적, 그리고 전체 평가 응답 기록은 .gitignore를 통해 제외됩니다.

선택적 개발자 평가

네이티브 Codex 평가는 설치, 설정, doctor, 테스트 또는 CI에 포함되지 않습니다. 모델 사용량을 소비할 수 있으며 의도적으로 지원 항목입니다. 전체 임무는 정확히 15개의 golden question으로 구성됩니다. 각 수행은 하나의 새 응답 세션과 분리된 judge 세션을 사용하며, 결정적 증거 확인은 추가 하드 게이트입니다. 따라서 전체 실행에는 30개의 Codex 세션이 필요합니다:

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

실행기는 시작하기 전에 계획된 답변/판정 회수를 출력하고, 로컬 JSON과 Markdown 판정을 기록합니다. 검토되고 정화된 아티팩트만 게시하세요. 마지막으로 완료된 보고서는 14/15 점수였고, 현재 코드에서 이미 수정된 공정성 기본값 불일치를 드러냈습니다. 후속 재실행은 Codex 토큰 사용량 통제를 위해 중단되었으므로, 이 문서는 현재 인증이 아니라 분명히 수정 전 근거입니다. evals/README.md를 참고하세요.

라이선스

저장소 코드는 MIT 라이선스입니다. 소스 데이터셋의 권리는 별개로 유지됩니다. 자세한 내용은 LICENSE, DATA_NOTICE.md, CONTRIBUTING.md, 그리고 SECURITY.md를 참조하세요.