11 - MCP 产品定义（Agent 操作面）¶

本文定义 Clip票夹 对 AI Agent 暴露的产品能力：定位、边界、工具清单、鉴权与安全、异步约定、分阶段落地。
实现仍走现有 REST（08-api.md）；MCP 是意图层包装，不平行造第二套业务 API。
机器可读请求/响应形状以 packages/shared 的 zod 为准；本文与代码冲突时先改文档达成共识再动代码（见 AGENTS.md）。

1. 产品定位¶

一句话：MCP 是工作区上下文下的报销工具箱；人确认边界内的写操作，系统保留与 Web 相同的隔离与审计红线。

2. 与现有产品的关系¶

┌─────────────┐     session cookie      ┌──────────┐
│  Web (人)   │ ───────────────────────►│          │
└─────────────┘                         │  API     │
                                        │ /api/v1  │──► PostgreSQL / 队列 / 文件
┌─────────────┐  Bearer + workspace     │          │
│ MCP Server  │ ───────────────────────►│          │
│ (Agent 面)  │   意图 → REST 映射      └──────────┘
└─────────────┘
       ▲
       │ MCP tools/list · tools/call
┌─────────────┐
│ Agent 宿主  │
└─────────────┘

3. 用户与场景¶

3.1 典型使用者¶

3.2 主旅程（Agent）¶

1. 定位上下文：列出可访问工作区 → 选定当前 workspaceId（后续写操作默认落在此空间）。
2. 感知状态：工作区摘要（待报销金额/张数、队列积压、未匹配附件、额度剩余）。
3. 收票：上传文件 → 轮询解析任务 → 处理失败/重复。
4. 核对：检索发票 → 必要时修正白名单字段、配对附件、重放 OCR（优先免费 replay）。
5. 组单：建批 → 入批/拆批 → 排序 →（可选）标记已报销 paid（需确认）。
6. 交付：触发导出 → 轮询导出任务 → 取得受控下载信息，交还人或下游系统。
7. 收尾：查看通知、标记已读；异常用机器可读 code 决定重试或升级给人。

3.3 明确不做的旅程¶

• 配置或读取邮箱授权码、财务门户密码、Webhook secret。
• 创建/删除工作区、转让 owner、管理系统用户。
• 管理员跨工作区排障下载。
• OA/财务系统自动提交报销单（半自动填报若落地，仅允许「生成预填结果 + 人确认」）。

4. 设计原则¶

1. 工作区钉死：会话级或 tool 级必须有明确 workspaceId；禁止用「猜默认空间」跨空间扫数据。
2. 金额只传分：tool 入参与出参中的金额字段均为 integer 分；展示文案可由 Agent 自行格式化。
3. 异步可轮询：上传解析、导出均为任务型；tool 返回 taskId / exportId，另提供状态查询；MCP 层不要求宿主支持 SSE（SSE 为可选增强）。
4. 默认瘦响应：列表与摘要省略 ocr_raw_json、完整附件二进制等大字段；详情按 flag 增量拉取。
5. 错误可分支：失败返回与 API 对齐的 code（如 DUPLICATE_FILE、BATCH_STATE_INVALID），message 给人读，details 给模型结构化重试。
6. 危险写二次确认：软删发票、批次标 paid、删批等 tool 要求显式 confirm: true（或宿主侧 human-in-the-loop 批准）。
7. 凭据零暴露：任何 tool 响应不得出现解密后的密钥、完整 session、信封主密钥；账户类只读若开放，仅掩码元数据。
8. 幂等友好：上传/入批/导出支持可选 idempotencyKey（产品层约定；落地时与 API 幂等策略对齐），避免 Agent 重试造成双批或双导出。
9. 审计可区分：经 MCP 的写操作标记 actor_type=agent（及 token id），与浏览器操作区分，便于追责与限流。

5. 能力分层¶

角色下限与 08-api.md §3.7 一致：viewer 仅 L0–L1（及 L3 若开）；member 可达 L2；manager 才涉及 L4 与批次删/改名等。

6. 工具目录（产品契约）¶

命名采用 动词_名词 蛇形，稳定后不轻易改名；新增 tool 只追加。
下列「映射 REST」指语义归属，实现可聚合多次调用。

6.1 L0 — 上下文¶

若实现选择「无会话态、每 tool 必传 workspaceId」，可取消 set_workspace，改为强制参数；产品上二选一写死，避免混用。

6.2 L1 — 只读¶

6.3 L2 — 写闭环¶

补传附件（POST /invoices/:id/attachments）可并入 upload_invoices 的 invoiceId 可选参数，或单独 attach_file_to_invoice；产品实现时择一，避免两个入口语义漂移。

6.4 L3 — 增强只读（可选）¶

6.5 L4 — 触发类（可选）¶

6.6 永不暴露的能力（产品黑名单）¶

7. 鉴权与令牌产品¶

7.1 身份模型¶

7.2 Token 能力集（scope）¶

签发时可子集化，默认建议：

另可选约束：

• 单工作区钉死：token 仅允许一个 workspace_id，忽略或拒绝其它 id。
• 只读令牌：仅 L0–L1（+L3），适合「问答式」Agent。
• TTL 与轮换：短有效期 + 刷新或重新签发；支持用户一键吊销。

7.3 限流（产品口径）¶

8. 数据与错误约定¶

8.1 字段口径¶

与 08-api.md §1 一致：

• ID：uuid 字符串
• 金额：integer 分
• 业务日期：YYYY-MM-DD
• 时间戳：ISO 8601 UTC
• 分页：page / pageSize / sort，响应含 total

8.2 Tool 结果形状（逻辑）¶

成功：直接返回资源 JSON（可与 REST 同形或经 MCP 层做字段裁剪）。
失败：

{
  "code": "BATCH_STATE_INVALID",
  "message": "批次非 collecting，无法入批",
  "details": {/* 可选 */},
}

跨工作区或无权限资源：表现为不存在（404 语义 / NOT_FOUND 类 code），不泄露其它空间是否持有该 id。

8.3 异步模式¶

upload_invoices / reparse_invoice / export_batch
        → 立即返回 taskId 或 exportId
        → Agent 调 get_task / get_export 直到终态
        → done 后再 get_invoice / get_download_url

终态枚举与 API 对齐：任务 done | failed | duplicate | ...；导出 done | failed。
产品要求：tool 描述（description）中写清「须轮询」，降低模型误判同步完成。

8.4 文件如何进 MCP¶

宿主与 MCP 之间的文件传递依赖 MCP 实现能力（path、base64、资源 URI 等）。产品要求：

• 仅允许约定扩展名：pdf / jpg / jpeg / png
• 单文件大小上限与 API 一致（默认 ≤ 10MB）
• 单次上传 ≤ 20 个文件
• MCP Server 将文件转为对 API 的 multipart，不在磁盘上留下可被其它租户读取的明文缓存（临时文件用完即删）

9. 安全与合规红线¶

1. 多用户数据必须带工作区边界；复合外键 + RLS + 成员校验与 Web 共用。
2. 密钥与 OCR key 不进 MCP 日志、trace、tool 回显。
3. ocr_raw_json 默认不下发；需要时显式 includeOcrRaw 且仍受工作区权限约束。
4. 下载只给受控、短时、需鉴权的获取方式，不做永久公开 URL。
5. Agent 写操作全量审计：谁、哪个 token、哪个工作区、哪个 tool、关键资源 id、结果 code。
6. 内网部署默认：MCP 只在内网或 localhost 暴露；若 HTTP 传输须 TLS 与内网 ACL。
7. 提示注入：tool 返回的发票备注、商户名、OCR 文本视为不可信数据，系统提示中应要求模型不得将其当作指令执行（实现侧可在 description 与 wrapper 中重复此约束）。

10. 宿主集成（产品体验）¶

10.1 连接方式（目标形态）¶

10.2 配置项（用户可见）¶

10.3 Agent 系统提示（产品侧建议文案要点）¶

• 先 list_workspaces / get_workspace_summary，再改数据。
• 金额按分计算；展示给人时再换算元。
• 解析与导出必须轮询至终态。
• 标 paid、删除类操作前向用户确认。
• 不要索要或保存用户邮箱/门户密码。
• 不要声称已向学校财务系统提交成功（本系统不提供该能力）。

11. 成功指标（产品）¶

12. 分阶段落地¶

与 06-roadmap.md 业务里程碑解耦，MCP 可并行推进，但依赖对应 REST 已可用。

智能组单（suggest_batch）作为 L2 增强 tool 单列：只返回建议 invoiceIds 与金额分，不自动入批；入批须用户确认后再调 add_invoices_to_batch。（后端 POST /batches/suggest 已落地，见 03 §5.6。）

13. 文档与实现同步¶

相关文档：

• 功能优先级：02-features.md
• 架构与鉴权：03-architecture.md
• REST 契约：08-api.md
• 里程碑：06-roadmap.md

14. 名词表¶

15. 开放问题（写入时未锁死，实现前需拍板）¶

1. 会话态 workspace：set_workspace 会话缓存 vs 每 tool 必传 workspaceId。
2. 下载交付：MCP 直接返回短时 URL vs 返回「请到 Web 下载」的占位（内网 Agent 无浏览器时前者更必要）。
3. 服务账号：是否允许非自然人的 bot 用户加入工作区（审计与责任主体）。
4. Idempotency-Key：先做 MCP 层去重表，还是并入 API 正式契约。
5. 多文件上传在 MCP 的编码：path 引用（stdio 本机）与远程宿主的 base64 体积上限。

拍板后更新本节为「已决」并改 §6/§8 正文，避免实现分叉。