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，并遵循幂等键或版本合同 |
标识与组合规则
| 标识 | 业务含义 | 可传入 |
|---|---|---|
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 返回，应根据错误文本修正参数或决定是否重试。