使用 MCP

本文档说明本地 Agent 或外部自动化如何通过产品 API 和 MCP 风格工具操作 Monkeys。它补充 产品数据装配手册。

外部调用模型很简单：

1. 发现产品上下文。
2. 先读后写。
3. 使用稳定的数据、workflow 和 tool 契约。
4. 通过产品入口触发 action。
5. 沉淀并检查结果。
6. 让重要 action 可追踪。

MCP 是操作入口，不是绕过产品模型的捷径。外部 Agent 仍然应该遵守 ontology、view、权限、workflow 契约、tool 契约和 artifact 处理规则。

操作模型

开始之前

确认 Agent 已具备：

• 可访问的 Monkeys 产品 endpoint。
• MCP server 或等价的产品操作适配器。
• 已为目标产品环境配置认证。
• 在操作需要时，已知 workspace 或 team 上下文。
• 有权限读取数据、执行 workflow、上传文件或更新 record。
• 能检查 tool schema 和 API contract。

建议最先检查：

• 展示当前连接上下文。
• 列出可访问的 workspace 或 team。
• 列出可用 workflows。
• 查询一个小的数据 view sample。
• 使用 generic API call 前，先检查 API 文档或 tool schema。

操作原则

先读后写

外部 Agent 在修改前应该先检查当前产品状态。

读取：

• 可用 workspace 或 team。
• 相关数据仓库和 views。
• Workflow 定义和必需输入。
• 已有执行历史。
• API 或 tool schema。
• 可能被更新的已有 records 或 artifacts。

然后只用明确标识和范围化 payload 写入。

优先使用专用工具

如果存在专用 MCP tool 或产品 API，就优先使用它。

只有在这些情况下才使用 generic API call：

• 没有专用 tool。
• 已经检查 endpoint schema。
• Request body 小、明确、可回看或容易复核。
• Agent 能解释为什么需要 generic call。

保持数据契约稳定

不要在 prompt 里临时发明新的 record 结构。使用 ontology、schema、view、workflow 和 tool 契约。

当 Agent 需要写数据时，应知道：

• 目标对象。
• 目标 record 或数据仓库。
• 必填字段。
• 允许的 enum 值。
• Artifact 关联规则。
• 权限和校验要求。

让 Action 可追踪

对重要操作，保留：

• 谁或什么发起了 action。
• 目标对象。
• 输入数据。
• 可用时记录 workflow 或 tool 版本。
• 执行结果。
• 创建或更新的 artifacts。
• 失败时的错误信息和重试状态。

当前操作能力

可用能力会随部署和 MCP server 版本变化。常见操作类别如下：

常见 MCP Tool 模式

具体 tool 列表可能演进，但以下名称代表当前常见模式：

当部署环境里的 MCP server 与本文档不同，以 MCP client 返回的 tool descriptions 为准。

连接和上下文

Step 1: 确认连接

让 Agent 展示当前连接上下文。

预期结果：

• Endpoint 或 host 正确。
• 认证可用。
• Agent 能解释自己正在操作哪个产品环境。

如果连接失败：

• 检查 MCP server URL。
• 检查认证配置。
• 检查网络访问。
• 检查产品 API endpoint 是否可达。

Step 2: 选择 Workspace 或 Team 上下文

很多操作需要 workspace 或 team identifier。

Agent 应该：

1. 列出可用上下文。
2. 按名称或 identifier 选择目标上下文。
3. 在 workflow、data 和 file 操作中一致复用该 identifier。

如果有 discovery tool，不要从过期日志或截图中猜 identifier。

数据操作

查询 Data View

当 Agent 需要检查产品数据时，使用 data view query。

推荐流程：

1. 确认 workspace 或 team 上下文。
2. 确认数据仓库或对象。
3. 通过 id 或 name 解析 view。
4. 必要时应用 tag、field、search 或 semantic filters。
5. 先请求小规模 preview。
6. 确认返回结构后再增加 limit。

结果应包含：

• 被选中的数据仓库或对象。
• 可用时展示被选中的 view。
• 返回 records。
• Count 或分页元数据。
• 当 view 或 tag 解析使用 fallback 时，返回 warnings。

数据抽样

当任务需要代表性 record 时，尤其是图片密集或标签密集数据，可以使用 sampling。

适合：

• 为生成任务挑选参考图。
• 检查数据质量。
• 查看标签分布。
• 为 workflow execution 构造小规模测试输入。

避免：

• 把随机样本当成完整数据集。
• 在用户没有要求抽样时，仅基于样本写入更新。
• 忽略 unresolved tags 或 fallback views 的 warnings。

通过 API 更新数据

当没有专用 data-write MCP tool 时，先做 API discovery，再使用 generic API call。

流程：

1. 列出 API docs。
2. 检查 endpoint schema。
3. 确认 method、path、query、body。
4. 先读取目标 record。
5. 发送最小合法 update。
6. 回读更新后的 record 或 view。

如果操作具有破坏性或影响范围很大，执行前需要明确的人类确认。

Workflow 操作

查找 Workflow

流程：

1. 使用 search 列出 workflows。
2. 使用稳定 identifier 选择 workflow，不只依赖展示名称。
3. 获取 workflow detail。
4. 检查 variables、required inputs、tasks 和 outputs。
5. 用产品 records 或明确用户输入构造 input data。

执行 Workflow

执行前：

• 确认 workflow identifier，必要时确认 version。
• 确认 input data 匹配 workflow variables。
• 确认被选中的 records 是预期输入。
• 确认输出预期。

执行：

• 使用 workflow execution tool，传入结构化 input。
• 记录返回的 execution identifier。
• Poll execution status，或稍后查询。

执行后：

• 检查终态 status。
• 检查 output payload。
• 找到生成 artifacts。
• 确认输出是否被持久化为 records 或进入数据仓库。
• 必要时记录后续动作。

更新 Workflow

Workflow update 是产品配置变更，要谨慎处理。

更新前：

• 读取当前 workflow detail。
• 保留必需的 version 或锁字段。
• 明确哪些 fields、variables、tasks 或 outputs 会变化。
• 能小改就不要大范围重写。
• 确认下游应用仍然理解输出。

更新后：

• 回读 workflow detail。
• 安全时执行小规模测试。
• 检查 execution history 或 logs。

文件和 Artifact 操作

上传文件

流程：

1. 确认目标 workspace 或 team 上下文。
2. 确认用途：source input、workflow input、generated result 或 documentation artifact。
3. 上传文件。
4. 记录 file identifier、URL、MIME type、size 和 metadata。
5. 相关时，将 artifact 连接到 record、workflow 或 output。

避免孤立文件。如果文件承载产品含义，就应该连接到产品数据。

下载文件

流程：

1. 解析 file 或 artifact identifier。
2. 下载文件或 base64 payload。
3. 保留 metadata。
4. 只用于用户要求的操作。

如果存在更新的 record 或 workflow result，不要把下载 artifact 当成最终权威来源。

Generic API Calls

Generic API call 很有用，但也很锋利。把它当成 fallback。

调用 generic endpoint 前，确认：

• 专用 MCP tool 不能覆盖这个任务。
• 已经检查 API docs。
• Method 和 path 正确。
• 必需 query 和 body 字段存在。
• Body 不包含无关字段。
• 对破坏性或大范围操作已经复核。

推荐模式：

{
  "method": "GET",
  "path": "/api/example",
  "query": {
    "limit": 10
  }
}

写操作要保持 body 小，并回读结果。

Cookbook

Cookbook: 检查一个 Data View

1. 展示连接上下文。
2. 列出 workspace 或 team。
3. 按 view name 或 id 查询 data view。
4. 先用小 limit。
5. 总结返回 records 和 warnings。
6. 需要时用更严格 filter 再查一次。

Cookbook: 从选中 Records 触发 Workflow

1. 查询 source view。
2. 用明确 identifiers 选择 records。
3. 列出 workflows 并找到目标 workflow。
4. 获取 workflow detail，检查必需 input。
5. 使用选中 records 构造 input data。
6. 执行 workflow。
7. Poll execution。
8. 检查 output 和 artifacts。
9. 确认 output 是否被持久化。

Cookbook: 创建或更新 Workflow

1. 列出现有 workflows，避免重复。
2. 如果有相似 workflow，获取 detail。
3. 构造最小 definition。
4. 用明确 fields 创建或更新。
5. 回读保存后的 workflow。
6. 安全时做小规模测试执行。
7. 记录假设和 output contract。

Cookbook: 上传文件作为 Artifact

1. 确认目标上下文。
2. 上传文件。
3. 记录 metadata。
4. 将文件连接到目标 record 或 workflow input。
5. 查询相关 view 或 record，确认可见。

Cookbook: 排查失败 Execution

1. 通过 identifier 获取 execution。
2. 检查终态 status 和 error message。
3. 搜索相关 execution history。
4. 检查 workflow detail。
5. 对比 input data 和 workflow variables。
6. 检查是否缺少必需 artifacts 或 records。
7. 只有在可能原因被处理后才 retry。

错误处理

安全检查清单

本地 Agent 修改产品状态前，确认：

• 目标 workspace 或 team 正确。
• 目标 record、workflow、view 或 file 使用稳定 id 标识。
• 尽可能先读后写。
• Request body 最小且范围清晰。
• 操作遵守产品数据契约。
• Action 可以被审计或解释。
• 破坏性或大范围变更已有明确人类确认。
• Agent 会在写入后回读结果。

Agent Prompt 模板

请求本地 Agent 操作 Monkeys 时，可以用这个模板：

Goal:
<what should change or be inspected>

Context:
- Product endpoint:
- Workspace/team:
- Data repository or view:
- Workflow:
- Relevant records or files:

Rules:
- Read before writing.
- Prefer dedicated MCP tools.
- Use stable identifiers.
- Keep writes minimal.
- Preserve artifacts and action history.
- Report warnings and exact output identifiers.

Expected output:
- Summary of actions
- Records/workflows/files touched
- Execution ids or artifact ids
- Any unresolved risks

完成标准

一次外部调用完成时，应满足：

• Agent 能解释自己读取了什么。
• Agent 能明确说明自己修改或触发了什么。
• Workflow execution 有终态或明确后续状态。
• Artifact 在承载产品含义时已经建立连接。
• 结果可以通过产品数据或 execution API 看见。
• 错误和跳过步骤被清晰报告。