snw-derived-mcp

Agent Native 的派生属性 MCP 服务。外部 Agent 提交“目标对象 + 字段需求”，服务在 Amazon Ads mock 本体的三跳邻域内确定来源字段、校验 Link 基数、生成 Semantic Join SQL，并可创建和执行只读派生属性。

核心规则

• 全链路 to-one 直接投影；任一跳 to-many 必须聚合。

• 支持 1:1、1:N 和带 junction table 的 M:N Link；M:N 双向均视为 many。

• 支持 Count、Sum、Avg、Min、Max、去重计数、Collect List/Set。

• 路径最多三跳，超出返回 OUT_OF_NEIGHBORHOOD。

• 普通 Derived 拒绝过滤、排序和“取最新一条”。

• SQL 流程为 seed → semi-select → 根键传播 → 聚合 → LEFT JOIN 回根对象。

• DuckDB 可执行；Spark/Hive 可生成 LEFT SEMI JOIN 预览。

Related MCP server: Glossary MCP Server

运行

uv sync
uv run snw-derived-mcp --database var/snw-derived.duckdb

MCP 客户端配置示例：

{
  "mcpServers": {
    "snw-derived": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/snw-derived-mcp", "run", "snw-derived-mcp"]
    }
  }
}

外部 Agent 调用顺序

1. snw_list_object_types

2. snw_get_object_neighborhood

3. snw_analyze_field_request

4. 仅当结果为 READY 时，将返回的 plan、ontology_version、plan_digest 原样传给 snw_create_derived_property；同名更新必须显式设置 replace_existing=true

5. snw_execute_derived_property 验证 mock 数据结果

示例：object_type="广告组"、request="广告活动状态" 会定位到 AdGroup → Campaign.status，判断为全程 to-one，无聚合，建议字段名 campaign_status。

M:N 示例：object_type="广告活动"、request="标签名称列表" 会沿 Campaign ↔ Label 的 junction table 生成 Collect List 计划。

验证

uv run ruff check .
uv run mypy src
uv run pytest -q
uv build

本项目不连接 Palantir、真实 Amazon Ads 或生产数仓；实现的是本仓库规格锁定的 Derived 语义演示。