Funnel Calibrator

판매 퍼널이 실제로 하는 일에 맞춰 광고 결정을 재보정하는 MCP 서버입니다 — 추정된 일이 아니라.

⚠️ 상태: 작업 진행 중. 스캐폴딩과 설계는 커밋되었으며, MCP 서버 구현은 2026년 8월 24일에 공개됩니다. 방어 발표: 2026년 8월 25일.

KSE AI Agentic Lab — 개인 실험 과제 (7주차, MCP 통합).

이 프로젝트가 해결하는 문제

이 프로젝트는 Meta 광고를 통해 여성 의류를 판매하는 우크라이나의 착불 결제(COD) 이커머스 사업을 기반으로 합니다. 여기의 퍼널은 다섯 단계로 구성됩니다.

Meta ads ──► Lead ──► Call-centre approval ──► Shipment ──► Buyout at post office ──► Profit

결제가 배송 시점 이루어지므로, 광고 캠페인의 결과는 돈을 지출할 당시에는 알 수 없습니다. 그 결과는 고객이 택배를 수령하거나 수령하지 않는 시점, 즉 2~4주 후에야 드러납니다. 이 공백을 극복하기 위해 사업은 포트폴리오 공통 상수 두 가지 — 승인율 65%와 수령률 52.5% — 를 사용하며, 이를 모든 제품마다 손익분기가 유지되는 최대 비용 per RM(Stop CPL) 과 최적화 목표(Goal CPL) 를 계산합니다.

이 상수들은 개별 상품에 적용되는 포트폴리오 평균이며, 개별 상품은 이 평균에서 크게 벗어납니다. 실제 기업에서 측정된 사례: 한 공급사의 제품은 가정된 52.5% 대신 37%의 수령률을 보였고, 어느 제품의 승인율은 가정된 65% 대신 53%로 측정되었습니다. 또 수령률은 가격대와 강한 상관관계를 가지는데, 690–790₴ 구간에서 약 93%, 1290 ₴이상 구간에서는 약 55%로 나타났습니다.

어떤 제품의 실측 비율이 가정보다 나쁘면, 그 제품의 실제 손익분기 CPL은 사업이 운전하는 기준보다 낮아집니다 — 그래서 광고 목표가 실제 손익분기점보다 위에 세팅될 수 있는 일이 생깁니다. 광고 대시 최적의 트래픽은 정상으로 보이지만, 실행 결과는 모든 리드가 손실을 부담하며 손해는 몇 주 후 월간 손실이 결산되는 시점에만 드러납니다.

즉 이 시스템은 열린 루프 제어(open-loop control) 시스템입니다. 측정은 다시 decision 되돌아오지 않습니다. Funnel Calibrator가 이 루프를 닫아줍니다.

Related MCP server: KrystalView MCP Server

하는 일

서버는 과거 주문 데이터로 각 제품의 자체 퍼널 지표를 측정하고, 그 제품의 실제 손익 CPL 경계치을 다시 계산하며, 제안된 광고 결정을 교정된 수치에 견주어 감사합니다 — 맹신해야 하는 판결 대신에 구조화된 근거를 반환합니다.

이를 일반적인 경우보다 어렵게 만드는 문제는 두 가지며, 두 가지 모두의 도구 계약서에 명시되어 있습니다:

• 중도절단(Censoring) 미해결 주문. 최근 주문은 아직 확정이 아닙니다 — 배송 중인 택배자는 수령도 반품도 아닙니다. 단순하게 모두 셀 경우 측정 지표가 감소됩니다. 이 서버는 설정가능한 성숙 기간보다 어린 코호트를 제외하며, 그는 얼마나 많은 주문을 남겨 두었는지 보고합니다.

• 작은 표본 크기. 상품별, 한계별, 사이즈별·색상별로 하면 관측값은 금세 작아집니다. 모든 측정값에는 표본 크기와 신뢰도 플래그가 갖추어져 있으며, 서버는 설정할 수 있는 임계값 아래에서는 결론을 산정하지 않는 대신, 신뢰하기 어려운 확실한 소음을 쓰지 않습니다.

아키텍처

┌─────────────────────────────────────────────────────────────┐
│  Agent  (Claude Agent SDK)                                  │
│                                                             │
│    ├── MCP ──► Obsidian Local REST API      [existing]      │
│    │           decision journal: reads the day's objective  │
│    │           and prior conclusions, writes calibrated      │
│    │           verdicts back as a durable record            │
│    │                                                         │
│    └── MCP ──► Funnel Calibrator            [custom]        │
│                measure → recalibrate → recommend → audit    │
│                        │                                     │
│                        ▼                                     │
│                 local snapshot dataset                       │
│                 (anonymised order cohorts + unit economics)  │
└─────────────────────────────────────────────────────────────┘

커스텀 서버는 별도 프로세스로 실행되어 stdio 규격으로 통신하며, 에이전트와 독립적으로 시작이 가능합니다.

에이전트 흐름

1. 오늘의 광고 목표와 어제의 결론을 Obsidian 볼트에서 읽습니다.

2. 스냅샷에서 각 상품의 관측된 퍼널 지표들을 측정합니다(중도절단 및 표본 크기 인지).

3. 그 상품의 실제 Stop/Goal` CPL과 score 상위해서 추정된 베이스라인과의 deviation(drift)을 재계산합니다.

4. 상품이 낮은 성과를 내는 원인이 무엇인지를 진단합니다 — 원인마다 해결책이 다릅니다 — 그리고 다음 조치를 권고합니다.

5. 오늘 제안된 결정들을 보정된 지표와 대비해 감사합니다.

6. 재계산된 판정을 근거 체인 포함하여 볼트에 기록합니다.

각 단계는 전 단계의 결과물을 이어받습니다: 볼트 내용은 무엇을 측정할지를 좌우하고, 측정값은 보정된 한계치를 결정하며, 그 한계치가 제안된 결정의 유지 또는 반전을 좌우합니다.

커스텀 도구

입출력 스키마 전체, 오류 조건, 부수적인 영향 및 작업 예제: docs/tool-contracts.md.

왜 이 네 가지인지, 왜 MCP 경계에 두는지, 이 설계가 포기시키는 것: docs/design-rationale.md.

데이터 소스

로컬 팰레이트저 기반의 익명 처리된 스냅샷 데이터셋으로서, 비즈니스 CRM(고객관계관리) 즉 scripts/export_snapshot.py 가져옵니다. 실행 시점에 인증 또는 네트워크 액세스가 필요하지 않기 때문에 데모의 경우 확정적으로 재연 가능합니다.

고객 이름, 전화번호, 주소, 거래의 운송장 번호 등 개인 식별 정보는 export 과정 모두, 교정에 필요한 항목 — 제품 코드, 주문 상태, 타임스탬트, 금액, 단위 경제 지표 — 만 남습니다. 익명화 정책과 스키마는 data/README.md을 참죠하십시오.

빠른 시작

전제 조건: Python ≥ 3.11과 uv. Local REST API 플러그인이 있는 Obsidian은 에이전터 흐름에만 필요하며 서버 전용은 아닙니다.

git clone https://github.com/denkor1015-debug/funnel-calibrator.git
cd funnel-calibrator
uv sync

MCP 서버를 독립 모드로 실행합니다 (stdio의 MCP 소통, 대기 클라이언트):

uv run funnel-calibrator

MCP Inspector에서 노출된 도구들을 인터랙티브하게 확인합니다:

npx @modelcontextprotocol/inspector uv run funnel-calibrator

설정은 환경 변수로 읽기 때문에 템플릿을 복사하여 수정합니다:

cp .env.example .env

두 MCP 연결의 에이전터 조합: agent/mcp_config.example.json.

저장소 구조

src/funnel_calibrator/   MCP server: tool definitions, calibration math, policy engine
scripts/                 snapshot exporter (CRM ──► anonymised local dataset)
data/                    snapshot dataset + anonymisation policy
docs/                    tool contracts, design rationale, defence checklist
agent/                   MCP client configuration for both connections
tests/                   unit tests for calibration and policy logic

구축 계획

• 구성 요소 프레임 워크, 아키,, 보관 위험각에 대한 근거 문서

• PII 제거을 포함한 스냅샷 내보내기 도구

• measure_sku_funnel — 중도절단 및 표본 크기 판정

• recalibrate_cpl_bounds — 단위 경제성 재계산

• recommend_next_action — 실패 모드 진단

• audit_ad_verdict — 광고 결정 감사

• Obsidian MCP 통합 및 엔드투엔드 에이전트 흐름

• 파업 경로 처리 및 라이브 데모

• 도구 계약서 문서 및 발표 스크립트

Assignment 요구사항 대응표

라이선스

MIT — LICENSE을 참조하세요.