用语义层约束 MCP 数据查询口径

让大模型连上数据仓库，问一句「上周各渠道的 ROAS 是多少」，很快就能得到一份漂亮的答案。问题是，SQL 能运行，不代表收入、归因和日期口径选对了。

adtribute 团队的做法是：模型负责理解问题、选择指标，服务端负责确定口径、生成 SQL 和解释结果。这篇文章值得看的地方，是它把哪些决定可以交给模型、哪些必须由代码执行，划出了可检查的边界。

模型选指标，服务端决定怎么算

adtribute 的 MCP server 让 Claude 等客户端查询营销归因数据，来源包括 Shopify、Meta、Google、TikTok、HubSpot、Klaviyo 和第一方追踪。

这些数据的难点不只是表结构。「收入」可能指毛收入或净收入，「新客」和贡献利润也有各自的业务定义。模型即使写出合法 SQL，仍可能算错问题。

他们为每个组织维护语义层（semantic layer），集中定义指标、维度、归因模型和计算字段，每项都有 key、显示名称和描述。模型通过 get_dimensions、get_attribution_models 等工具查看详情；get_context 只返回目录入口和条目数量，不带 key，避免一次塞满上下文。

查询工具接收的是业务参数：

{
  "intent": "ROAS by channel last week",
  "metrics": ["roas"],
  "dimensions": ["channel"],
  "date_range": { "from": "2026-10-26", "to": "2026-11-01" }
}

要看的是 metrics 和 dimensions：它们引用组织已经定义的 key，没有直接提交表达式或 SQL。

服务端先校验 key；遇到未知项，就返回合法选项供模型纠正。生成 SQL 时，标识符必须符合严格模式并加引号，筛选值和日期使用绑定参数，数据集则从已认证组织中取得。

SQL 合法与业务计算正确，是两道不同的检查。

作者给了一个早期踩坑案例：他们曾在求和前对原始行应用 spend > 0。由于花费和转化位于不同行，这个过滤会把收入悄悄清零。现在服务端拒绝指标过滤，并提示改用排序和限制返回数量。这个案例说明，安全拼接 SQL 还不够，服务端也要知道哪些操作会破坏数据含义。

公式和归因口径，为什么不能只写进提示词

ROAS、客单价、贡献利润都使用组织定义的计算字段，与报表共用公式。服务端在聚合之后展开公式，计算「总收入除以总花费」，避免把各行比率相加；除法用 NULLIF 防护，没有数据行的输入按零处理。

没有预定义比率时，模型可以提交 ad_hoc_formula，但只允许使用已知指标 key、运算符和常量，结果也会标明是临时公式。

临时公式还有一道机械式歧义检查：如果某个指标存在名称或描述共享词语的相邻候选，例如毛收入和净收入，而用户意图没有包含所选指标名称，服务端就返回候选让用户选择。维度没有同等检查，只靠指令要求模型列出所有合理候选，约束强度明显不同。

归因模型的选择则写成固定流程：

// Simplified
async function settleModel(q: Question): Promise<ModelChoice> {
  if (!q.needsModel || q.modelNamed) return { use: q.modelNamed };
  const agree = await sameUnderEveryModel(q); // conversion-side questions only
  if (agree) return { use: agree.reference, note: "model doesn't change these numbers" };
  const fallback = organizationDefault(); // exactly one marked default, or none
  return fallback ? { use: fallback, note: "organization default" } : { ask: viableModels() };
}

要留意 sameUnderEveryModel(q) 的适用范围：只有按转化自身字段分组、过滤的问题，例如日期、国家和商品，才会跨模型计算，并在小容差内比较结果。

用户在对话中指定模型，或加载的组织专用 skill 指定模型，都算明确选择。否则，服务端先尝试证明不同模型结果一致，再寻找描述以 Default Model 开头的唯一默认项。标了两个默认项，就按没有默认项处理。仍无法决定时，才返回 discovery_required，让用户在 First Touch、Linear 30 days 等候选间选择，模型不能顺手推荐一个。

日期同样有明确规则：默认按转化日期统计；要求点击日期，但模型没有点击数据时，服务端拒绝查询。与已有报表对账且日期口径不明时，要先问清楚。

查询之前确认，查询之后也要防止误读

plan_insights 接收查询参数，以及必填的用户原话 intent。它不返回指标值，只返回待澄清信息，或一份包含显示名称、来源说明、描述不足警告和精确行数的计划。模型被要求原样展示确认块，等待用户确认后再调用 get_insights。

每次 HTTP 请求都会创建新的 MCP server 实例，所以执行阶段重新校验参数、重新选择归因模型。计划的 session id 只用于关联日志，缺少它的调用也会被记录。

结果返回时，服务端生成 result_interpretation，写明模型、日期口径、指标、时间范围、时区和币种，要求模型原样放在开头。display_labels 把 key 映射为显示名称；SQL 仅在请求调试信息时返回。

总计和未展示行的「其余」部分，也由同一查询通过窗口求和计算，比率重新计算，不能相加。发生截断时，was_truncated、total_row_count 和说明会一起返回。

访问控制则落实到个人：通过 OAuth 连接组织专属 URL，每次请求验证 bearer token、组织成员身份和角色。管理员、编辑和报表查看者可以访问，受限报表查看者不行；组织还必须主动开启默认关闭的 MCP。

所有工具只读，查询由服务端生成 SELECT，受成本上限和超时约束。每次调用记录组织与用户，计划和查询额外记录用户原话、归因模型选择依据，查询再附仓库 job id，方便追查数字从何而来。

我的判断

我赞同它把业务定义放进数据模型，把默认值和拒绝规则放进代码。相较于让模型自由写 SQL，这种方式牺牲了部分探索自由，却让固定报表问题更容易复现和排查。

但这依赖一个前提：组织已经有可信的指标目录、公式和描述。毛收入与净收入如果连业务方都没区分清楚，语义层只能把混乱保存下来。

原文最有说服力的是过滤导致收入清零的具体案例，以及可检查的执行规则。作者没有给出准确率、延迟、成本或对照实验，因此不能据此断言方案能降低多少错误。作者也披露自己任职于 adtribute，这是一份产品工程经验分享。

还有两处边界要看清：每次查询前确认可能增加交互成本；原样展示和等待确认仍是对模型的指令。原文没有说明服务端是否强制验证「用户已确认」，session id 也只用于日志关联，所以计划与执行分离不能直接等同于强制审批。

能拿来做什么

• 如果你在 Node 服务里接入 AI 数据查询，先把常用指标、维度和公式做成可校验目录，让模型提交 key，再由服务端生成参数化查询。
• 给前端数据助手返回完整的解释字段，包括日期口径、时区、币种、总计和截断状态，让界面与模型都能准确说明数字。
• 把收入候选、默认模型冲突、点击日期不可用等情况做成明确的澄清或拒绝响应，并记录用户原话和查询 job id，方便定位口径问题。