# 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` 预览。

## 运行

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

MCP 客户端配置示例：

```json
{
  "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 计划。

## 验证

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

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