Camscanner MCP

CamScanner MCP Skill 使用指南

通过 MCP 协议调用 CamScanner AI Tools，完成文档转换、图片增强、OCR、发票识别、云文档搜索等操作。认证由连接器自动处理，无需手动配置 API Key 或 Token。

核心流程

所有操作遵循统一的三步流程：

1. 上传本地文件（create_upload → 二进制上传 → complete_upload）→ 获得 file_id
2. 调用功能 tool（传入 file_id）→ 获得结果 file_id
3. 输出结果：download_file（本地）或 create_cloud_doc（云端）

重要：所有功能工具通过 file_id 接收文件输入。用户提供的本地文件先调用 create_upload 创建上传任务，再按返回的上传地址、方法和 headers/fields 上传二进制内容，最后调用 complete_upload 获得 file_id。工具返回的结果也是 file_id，需要 download_file 才能获取实际内容。

文件上传注意事项

上传时先从 MCP tool schema 读取 create_upload 和 complete_upload 的准确参数名，并按 schema 传入文件名、MIME 类型、文件大小等元信息。create_upload 返回 upload_id、短期 upload_url、HTTP 方法、headers 或表单字段；上传二进制时使用这些返回值。上传成功后调用 complete_upload，以其返回的 file_id 作为后续业务 tool 输入。

create_upload(filename, mime_type/content_type, size, ...)
→ 按返回的 upload_url/method/headers/fields 上传本地二进制
complete_upload(upload_id, ...)
→ file_id

多文件场景逐个执行上述上传流程，收集所有 file_id 后再调用批量处理工具。

文件传输

上传文件：create_upload → complete_upload

上传本地文件并获得 file_id。后续所有 MCP 功能工具均使用此 file_id 作为输入。

• create_upload：创建上传任务，传入文件名、MIME 类型、文件大小等 schema 要求的元信息，获得短期上传信息
• 二进制上传：按 create_upload 返回的 upload_url、HTTP 方法、headers/fields 上传本地文件内容
• complete_upload：提交上传完成信息，获得 file_id
• 限制：单文件最大 100MB，支持格式：jpg/jpeg/png/pdf/txt/docx/xlsx

下载文件：download_file

通过 file_id 获取文件的下载地址和元信息。

• 输出（MCP 模式）：

{"file_id": "xxx.docx", "download_url": "https://...", "file_size": 12345, "file_type": "docx"}

• 通过 download_url 下载文件并保存到本地

保存策略

默认保存策略

强制规则：当用户未明确指定保存方式时，Agent 必须同时保存到本地和云端。仅保存本地而不存云端是错误行为。

保存到云端：create_cloud_doc

将处理结果保存到用户的扫描全能王账号。

注意：file_ids 必须是 JSON 数组格式，例如 ["file_abc.jpg"] 或 ["file_1.jpg", "file_2.jpg"]。禁止使用对象形式如 {"item": "..."} 或其他非数组结构。

智能命名规则：保存到云端时，Agent 应根据用户意图和文件内容生成简洁标题（≤20字）。

• 示例：用户说"把这张发票转成 Excel" → title: "发票转Excel"
• 示例：多张扫描件合并 PDF → title: "扫描文档合并"
• 无法推断时不传 title，由服务端自动生成

能力范围

工具总览

不支持的操作

• 无在线协同编辑
• 无文件版本管理
• 无视频/音频处理
• 无 PDF 合并（多个 PDF 合为一个）
• 无批量文件夹管理
• 无云文档内容编辑（只能搜索）

意图路由规则

路由按以下优先级逐层判定，禁止仅凭关键词直接跳转 tool：

顶层分流：文档搜索 vs 文件处理

关键判断：用户需求是"搜索云端文档"还是"处理本地文件"。前者走 search_cloud_doc，后者走 convert_*/enhance_* 等工具。两者是独立流程，不混用。

第一层：判断输入文件类型

第二层：判断操作意图

第三层：判断数量与产物

常见错误路由（Agent 必须避免）

工具参数详解

convert_image — 图片格式转换

convert_pdf — PDF 格式转换

enhance_image — 图片增强

增强模式：

image_hd — 图片高清化

restore_photo — 老照片修复

translate_image — 图片翻译

常用语言代码：zh（中文）、en（英文）、ja（日文）、ko（韩文）、fr（法文）、de（德文）、es（西班牙文）、pt（葡萄牙文）、ru（俄文）、ar（阿拉伯文）、it（意大利文）、th（泰文）、vi（越南文）

watermark_image — 图片添加水印

watermark_file — PDF 添加水印

convert_images_to_pdf / convert_images_to_word / convert_images_to_excel — 多图合并

注意：file_ids 必须是 JSON 数组格式，如 ["file_1.jpg", "file_2.jpg"]，禁止使用对象形式。

validate_image — 篡改/AI 生成检测

convert_images_to_text — 多图 OCR 合并文本

convert_pdf_to_images — PDF 逐页转图片

输出：{"file_ids": [...], "sizes": [...], "page_count": N}

convert_pdf_to_images_zip — PDF 转图片 ZIP

输出：ZIP 二进制，内含 page_1.jpg, page_2.jpg 等逐页图片。

convert_txt — TXT 转 Word

extract_image — 公式提取

输出：PNG 二进制，包含所有检测到的公式区域裁剪拼接结果。

scan_image_edit — 图片版面分析

输出：JSON 对象，包含 result.urls（input_image、document_info、background_info）和 result.document_info（版面结构数据）。

edit_image — 图片文字编辑

edit_request 结构：

area_type 可选值：text、table、image、stamp

remove_watermark_pdf — PDF 去水印

限制：最多支持 100 页 PDF。

extract_receipt — 发票/票据识别

识别发票/票据图片，返回结构化 JSON 数据（发票类型、金额、日期、发票号等）。

返回数据结构（output_mode=raw 时直接返回）：

{
  "bills_list": [
    {
      "image_scan": {"angle": 0, "position": [...]},
      "display_type": "增值税普通发票",
      "invoice_type": "vat_normal",
      "fields": [
        {"display_key": "issue_date", "display_name": "开票日期", "value": "2026-08-01"},
        {"display_key": "invoice_tax_rate", "display_name": "价税合计", "value": "¥1280.00"},
        {"display_key": "invoice_number", "display_name": "发票号码", "value": "12345678"},
        {"display_key": "seller_name", "display_name": "销售方名称", "value": "某某公司"}
      ]
    }
  ]
}

常见字段：issue_date（开票日期）、invoice_tax_rate（价税合计）、invoice_number（发票号码）、invoice_code（发票代码）、invoice_price_without_tax（不含税金额）、invoice_tax_amount（税额）、seller_name（销售方）、buyer（购买方）等。若 invoice_type 为 "ot" 表示未识别到有效发票信息。

Agent 行为规范：

• 用户提到"识别发票"、"报销"、"票据"、"提取发票信息"时，使用 extract_receipt
• 不要与 convert_image(target_type=excel) 混淆：前者提取结构化字段，后者是图片内容转表格
• 识别结果是 JSON 数据，Agent 应解析后以人类可读方式呈现（如列出金额、日期等关键字段）
• 建议使用 output_mode=raw 直接获取 JSON，无需再 download_file

search_cloud_doc — 搜索云文档

搜索用户云端的 CamScanner 文档。支持关键词搜索、时间范围过滤、文档类型过滤，可组合使用。

返回数据结构：

{
  "docs": [
    {
      "doc_id": "https://...",
      "title": "合同扫描件",
      "create_time": 1724500000,
      "modify_time": 1724600000,
      "dir_id": "folder_abc",
      "dir_title": "工作文档"
    }
  ],
  "total": 3
}

Agent 行为规范：

• 用户说"找/搜/查我的文档"时，走 search_cloud_doc，不走 convert/enhance 等文件处理流程
• 多关键词用空格分隔，采用 OR 语义
• 未传 keyword 时返回最近文档列表
• 默认返回 5 条，用户需要更多时增加 limit
• 时间意图应转换为 Unix 时间戳传入 start_time/end_time，而非作为关键词
• 搜索策略：先 search_scope=title，无结果再用 search_scope=full 重试一次

Agent 展示规范（强制）：向用户呈现搜索结果时，必须至少包含以下四列信息：

Agent 禁止省略类型列或仅展示标题和链接。

create_cloud_doc — 保存到云端

操作示例

示例 1：图片转 Word

用户：帮我把这张扫描件转成 Word

Agent 执行步骤：

1. 上传用户图片（create_upload → 二进制上传 → complete_upload）→ 获得 file_id_1
2. convert_image（file_id=file_id_1, source_type="image", target_type="word"）→ 获得 result_file_id
3. download_file（file_id=result_file_id）→ 保存到本地
4. create_cloud_doc（file_ids=[result_file_id], file_type="word", title="扫描件转Word"）→ 保存到云端

示例 2：多张图片合并为 PDF

用户：把这 3 张照片合成一个 PDF

Agent 执行步骤：

1. 上传 3 张图片 → 获得 file_id_1, file_id_2, file_id_3
2. convert_images_to_pdf（file_ids=[file_id_1, file_id_2, file_id_3]）→ 获得 result_file_id
3. download_file（file_id=result_file_id）→ 保存到本地
4. create_cloud_doc（file_ids=[result_file_id], file_type="pdf", title="照片合并PDF"）→ 保存到云端

示例 3：图片增强后保存

用户：这张照片太模糊了，帮我增强一下

Agent 执行步骤：

1. 上传用户图片 → 获得 file_id_1
2. 判断场景：模糊 → 优先尝试 image_hd（高清化）
3. image_hd（file_id=file_id_1）→ 获得 result_file_id
4. download_file + create_cloud_doc

示例 4：PDF 转 Excel 仅保存本地

用户：把这个 PDF 表格转成 Excel，保存到桌面

Agent 执行步骤：

1. 上传用户 PDF → 获得 file_id_1
2. convert_pdf（file_id=file_id_1, source_type="pdf", target_type="excel"）→ 获得 result_file_id
3. download_file（file_id=result_file_id）→ 保存到用户指定路径

示例 5：图片翻译

用户：翻译这张英文截图为中文

Agent 执行步骤：

1. 上传用户图片 → 获得 file_id_1
2. translate_image（file_id=file_id_1, to="zh"）→ 获得 result_file_id
3. download_file + create_cloud_doc（file_type="image", title="英文截图翻译"）

示例 6：发票识别

用户：帮我识别这张发票

Agent 执行步骤：

1. 上传用户图片 → 获得 file_id_1
2. extract_receipt（file_id=file_id_1, output_mode="raw"）→ 获得结构化 JSON
3. 解析 bills_list 中的 fields，以表格或列表形式向用户展示关键信息（金额、日期、发票号等）

示例 7：搜索云文档

用户：找一下我上周的合同文档

Agent 执行步骤：

1. 解析意图：关键词="合同"，时间范围=上周（转为 Unix 时间戳）
2. search_cloud_doc（keyword="合同", start_time=1724000000, end_time=1724600000）
3. 向用户展示搜索结果（必须包含标题、类型、所在目录、链接四列）

错误处理

重试策略

• 所有转换/增强操作均为幂等操作，可安全重试
• 重试间隔：429 → 等 10 秒、500 → 等 5 秒、504 → 增加 timeout_sec
• 重试最多 1 次
• create_cloud_doc 重试可能产生重复文档（可接受）
• 认证失败不重试，直接提示用户

操作限制

1. 文件大小：上传文件不超过 100MB
2. 支持的图片格式：JPG、JPEG、PNG
3. 支持的文档格式：PDF、TXT、Markdown
4. 多图合并上限：最多 100 张
5. 认证：由连接器自动管理，用户无需手动操作

意图消歧规则

当用户表述同时命中多个操作时：

原则：存在会改变 tool 选择的歧义时，追问用户而非猜测。

安全约束

• 认证由连接器管理，Skill 不存储、不记录任何凭据
• 输入文件上传到服务端处理，结果通过 file_id 获取
• 使用 create_cloud_doc 时，结果持久保存到用户账号
• 不使用 create_cloud_doc 时，服务端临时文件按保留策略自动清理
• 禁止将 file_id 作为永久引用——它有时效性，过期后需重新上传