Funnel Calibrator

一个 MCP 服务器，它根据销售漏斗的实际表现来重新校准广告决策——而不是根据对其的假设。

⚠️ 状态：正在开发中。 脚手架与设计决策已提交；MCP 服务器实现将于 2026 年 8 月 24 日落地。答辩：2026 年 8 月 25 日。

KSE AI Agentic Lab——个人实验实验室作业（第 7 周，MCP 集成）。

它解决的问题

本项目基于一个正在运营的乌克兰货到付款（COD）电商业务，通过 Meta 广告销售女装。它的漏斗包含五个阶段：

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

由于付款发生在交货时，广告支出的结果在资金投入的那一刻并不可知。要等两到四周之后，顾客取件或拒收时，结果才会明朗。该业务用两个覆盖整个产品组合的常数来弥合这一时间差——65% 的通过率和 52.5% 的买断率——并用它们计算每个产品仍能盈亏平衡的最大单条线索成本（Stop CPL），以及应当优化到的目标值（Goal CPL）。

这些常数是应用在单个产品上的组合平均值，而单个产品与其的偏差可能非常悬殊。 来源业务中的实测例子：某制造商的买断率实际为 37%，而假设为 52.5%；某产品的通过率实测为 53%，而假设为 65%；买断率与价格带强相关，从 690–790 ₴ 的约 93% 到 1290 ₴ 以上的约 55%。

当某个产品的实际**指标优于预期时，其真实盈亏平衡 CPL 会低于业务所依据的数字——于是广告目标可能落在真实盈亏平衡点之上*。广告后台里流量看起来很正常，而每条线索都在亏钱；这种亏损要到几周后的月度财务结算时才会显现出来。

这是一个开环控制系统：测量结果从未回到决策环节。Funnel Calibrator 将闭环闭合。

Related MCP server: KrystalView MCP Server

功能

服务器从历史订单数据中测量每个产品自身的漏斗费率，重新计算该产品的真实 CPL 边界，并针对修正后的数值审计拟定的广告决策——返回的是结构化证据，而不是一个有待无条件接受的结论。

有两个问题让这件事比一般情况更难度，两者都在工具契约中被显式处理：

• 截尾。 近期订单尚未完全可判定——在途的包裹既不是买断也不是退货。若把它们的数值直接计入，会人为地压低测量出来的费率。服务器会剔除未满可配置成熟窗口的数据队列组，并报告它搁置了多少订单。

• 样本量小。 按产品、尺码、颜色拆分后，计数很快会变小。每次测量都会标明样本量和可靠性情况，且当数值低于一个可配置阈值时，服务器拒绝下结论，而不是输出虚假的信噪。

架构

┌─────────────────────────────────────────────────────────────┐
│  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，以及与假设基线（assumed baseline）的偏差。

4. 诊断一个产品表现远超预期的原因——不同起因对应不同的解决策略——并推荐下一步行动。

5. 根据修正后的界限审计当天拟定中的广告决策。

6. 将校准后的结论及其证据链写回仓库。

每一步都依赖上一步的输出：仓库的内容决定测量什么，测量决定修正后的边界，边界决定拟定决策被成立还是被推翻。

自定义工具

完整的输入/输出模式、错误条件、副作用和运行示例：docs/tool-contracts.md。

为什么是这四个工具、它们为什么位于 MCP 边界，以及设计上放弃了些什么：docs/design-rationale.md。

数据源

一个本地、匿名化的历史订单队列快照数据集，由业务 CRM 导出，生成脚本为 scripts/export_snapshot.py。运行时无需身份验证和任何外部网络访问，从而演示结果具有确定性且可复现。

所有个人可识别信息——客户姓名、电话号码、地址、运单号——在导出时都被去除。快照只保留校准所需的字段：产品编码、订单状态、时间戳、金额以及对应订单的价值。匿名化策略和数据模式请见 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 配置： 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_silhouette——重新计算单位经济

• recommend_next_action——失效原因诊断

• audit_ad_verdict——决策审计

• Obsidian MCP 集成与端到端智能体流程

• 失败路径处理与演示

• 工具契约文档与答辩脚本

作业要求对照表

许可证

MIT——见 LICENSE。