# MCP Agent 使用指南

本指南用于把 Arkme 开放平台直接交给 Agent 使用。Tool 名称、描述、参数、返回结构、枚举和边界以 MCP Host 连接后取得的标准 `tools/list` 为准。

## 连接

| 配置 | 值 |
| --- | --- |
| MCP Server URL | `https://openapi.jotmo.cc/mcp` |
| Transport | Stateless Streamable HTTP |
| 认证 Header | `Authorization: Bearer arkme_...` |

MCP Host 通过 `tools/list` 发现当前可用能力，并通过 `tools/call` 执行调用。成功结果同时包含 `structuredContent` 和等价 JSON 文本；运行环境同时暴露两种表示时，使用 `structuredContent`，不要把两份等价内容同时加入分析上下文。

## Tool 选择

只使用 `tools/list` 实际提供的能力，以描述和参数、返回合同选择 Tool；名称前缀不代表每个业务都提供同样的能力。

| 任务 | 选择规则 |
| --- | --- |
| 不知道稳定标识，只知道人物、会话或主题名称 | 若该业务提供名称解析，使用对应的 `resolve_*`，根据候选证据消歧 |
| 不知道有哪些会话、成员或主题 | 使用该业务提供的列举或查询 Tool 分页发现 |
| 已知时间范围、状态、参与人、发送人或容器等结构化条件 | 使用对应的 `query_*` |
| 按正文关键词定位聊天或记录 | 若该业务提供关键词搜索，使用对应的 `search_*`；命中结果是检索证据 |
| 已知稳定标识，需要当前概览、状态或版本 | 使用返回这些字段的精确读取 Tool；已有所需事实时不重复读取 |
| 已知稳定标识，需要正文 | 使用该业务的正文读取 Tool；录音、通话使用转写查询分页读取，批量读取概览不返回转写正文 |
| 已知聊天消息坐标，需要它附近的对话 | 使用消息上下文读取 Tool |
| 创建、发送、更新、移动、流转或删除 | 使用对应写 Tool，并遵循幂等键或版本合同 |

## 标识与组合规则 {#agent-identifiers}

| 标识 | 业务含义 | 可传入 |
| --- | --- | --- |
| `user_ref` | 当前调用账号范围内可跨业务复用的人物公开引用 | `participant_user_ref`、`participant_user_refs`、`target_user_ref`、`sender_user_refs` 等人物引用字段；参与人筛选不等于发送人筛选 |
| `chat_session_uid` | 即我私聊、群聊或联系人会话 | 聊天会话、消息和发送能力的同名字段，以及通话查询的 `chat_session_uids` |
| `chat_session_uid` + `sequence` | 当前会话中的消息 | 消息查询、搜索、精确读取与上下文能力的同名字段 |
| `conversation_uid` | 微信导入会话 | 微信导入消息、群成员读取的 `conversation_uid`，以及会话批量读取的 `conversation_uids` |
| `message_uid` | 微信导入消息 | 微信导入消息批量读取的 `message_uids`；不是即我聊天消息坐标 |
| `recording_uid` | 一条录音 | 录音批量读取的 `recording_uids`、转写查询的 `recording_uid` |
| `summary_uid` | 已保存的录音日总结或时间线版本 | 总结正文读取的 `summary_uid`；不能与 `recording_uid` 互换 |
| `speaker_uid` | 当前账号的正式录音说话人标记 | 录音查询的 `speaker_uids`；不是录音内的 `speaker_index`，不能用于其他业务 |
| `call_uid` | 一次通话 | 通话批量读取的 `call_uids`、转写查询的 `call_uid` |
| `topic_uid` | Record 个人主题 | 记录容器或安排能力的同名字段 |
| `record_uid` | 一条记录 | 记录读写能力或安排关联字段 |
| `arrangement_uid` | 一条安排 | 安排查询、更新、流转和删除能力 |
| `team_ref` | 当前账号范围内的团队引用 | 团队成员查询与移除的 team_ref 字段 |

不同标识不可互换。`topic_uid` 只表示个人主题；即我聊天使用 `chat_session_uid`，微信导入会话使用 `conversation_uid`。团队与群的成员关系独立；user_ref 可跨能力复用，成员权限由目标团队或群分别判断。持有标识不代表拥有读取权限。

`speaker_index` 和 `sender_index` 分别是本页 `speakers` 和 `senders` 的零基索引，不是人物标识，不可跨页或跨业务复用。只有返回了 `user_ref` 才可将该引用用于人物关联；不能仅按显示名合并身份，通话的 `participant_side` 也不代表参与人本人。微信导入群成员是导入快照中的当前名单，不是历史发言人集合或微信实时成员。

## 按数据依赖组合

Tool 之间没有固定工作流。先确定任务要得到或改变的业务事实，再盘点已经掌握的稳定标识和仍缺少的输入；只调用能够补齐下一个缺失输入的 Tool。

缺少标识时，从当前业务实际提供的解析、列举、查询或搜索能力中选择。将输出中语义和类型完全匹配的字段传给下一次调用，不因名称或字符串形态相似而互换。

已有任务所需的公开标识或消息坐标时，直接传给消费 Tool，不重复调用产生它们的解析、列举、查询或搜索 Tool。需要复核当前状态或并发控制值时仍应使用精确读取 Tool；需要正文时选择返回正文的能力，概览与摘要不能代替正文。

解析 Tool 返回当前页候选和 `has_more`。确认候选唯一时可直接使用其标识，但本页只有一项且 has_more=true 不能据此认定全局唯一；存在多个候选时应根据用户提供的上下文选择，无法可靠区分时让用户确认；`has_more=true` 时原样传回 `next_page_cursor` 继续查询。继续分页时保持决定结果集的筛选条件不变；`limit` 只控制单页大小，可以调整。不得仅凭名称猜测。

写 Tool 结果未知时只能使用完全相同的业务参数重试；Tool 包含 `idempotency_key` 时，同一业务意图必须复用原值。`expected_version` 冲突时先重新读取当前事实，再决定新的写入意图。

## 读取范围与完整性

录音查询的 order 缺省 asc，desc 从最新录音开始；最新指录音开始时间，不是上传或修改时间。时间条件按录音重叠范围筛选，有人物条件时要求该人物在范围内有有效话语。转写查询不继承列表筛选；省略时间窗时读取整条录音，显式传入 start_at/end_at 时，按重叠选择完整原句话语，不做字级时间裁剪。

已有稳定标识时可直接读取所需正文，无须先读取概览。录音和通话的批量读取返回概览或状态，转写正文由各自的转写查询分页返回。

已确认的即我账号使用 `user_ref`：录音对应 `speaker_user_refs`，通话对应 `participant_user_refs`，微信导入会话对应 `participant_user_ref`。录音与通话多目标取并集。微信无已绑定私聊时返回空，不代表没有相关微信数据；可按用户给出的微信名称解析候选，不推断账号绑定。录音标记名称使用说话人解析，微信备注名、昵称或群名使用微信导入会话解析；名称不自动合并身份。

解析与人物筛选均读取当前可见状态，不创建人物、会话或绑定。页间标记或绑定变化可能改变结果，需要一致重读时从第一页重新查询。空页仍应检查 `has_more`，扫描未结束不能断言不存在目标。

时间字段的单位、上下界是否包含、默认范围和排序以各能力字段合同为准，不跨业务套用。微信导入会话按最新消息时间筛选，消息按发送时间筛选；分析某段时间内的全部历史消息时，不要用同一时间窗预先排除会话，应不带时间条件枚举会话，再逐个查询目标时间范围内的消息。

需要覆盖整个查询范围时，按该能力的分页字段逐页读取，直到 `has_more=false`，不能按本页条数判断是否结束。使用不透明游标时，将返回的 `next_page_cursor` 原样传回 `page_cursor`，保持账号、能力、对象和筛选条件不变；`limit` 只控制单页大小，可以调整。每页处理后累计中间结果，需要引用时保留业务标识与原文定位信息。

分页结束只表示本次可读结果已读完，不保证业务数据完整。返回 `found=false` 表示当前不可读，不能推断对象不存在或已删除；转写还需判断 `transcript_state`，群成员还需判断 `roster_state`。媒体元数据也不等于可下载的媒体正文。

录音转写的 bounded 模式不通过继续分页补回截断句尾；需完整原话时改用 text_mode=full，从首页重新读取。full 模式按 utterance_index 和字符坐标拼接同一句的续片，不跨录音或结果快照复用话语序号；坐标以 Unicode code point 计数。truncated=true 表示当前项不是整句，不等于续读后仍缺正文。确认片段连续覆盖 text_total_length，并检查 transcript_state。通话转写及其他正文或名单仍按各自的截断合同处理，不能套用录音 full 模式或假定分页能补回截断内容。

录音总结是自动生成的参考内容；核对原话时读取转写，不必先读取或等待总结。已有 summary_uid 可直接读正文；需要选择版本时按覆盖时间查询。读取时先检查 found 和 content_state，仅 ready 返回正文，JSON 分片须拼齐后解析。查询和读取均不触发生成。

群治理写入允许部分成功；业务拒绝见逐项 reason，基础设施错误可能已经生效。撤回以相同坐标重试；成员写复用原单条状态幂等；结果未知时核对当前状态，重新入群后不得自动重放旧的移出意图。治理查询固定 sequence 上界，但不提供数据库快照，晚到消息需另轮复查。

## 失败处理

HTTP `401` 表示认证不可用；`429` 应遵循 `Retry-After` 退避；`502` 或 `503` 表示依赖或开放平台暂时不可用。进入 JSON-RPC 后的参数或业务失败以 `CallToolResult.isError=true` 返回，应根据错误文本修正参数或决定是否重试。