# MCP 与 CLI 调用实战

> 从第一句话到完整脚本的实战教程：用 AI 客户端一句话合并 PDF、下达多步骤任务，用 CLI 编写批处理脚本并固化为定时任务，附常见坑速查。

- 分类：智能体接入
- 关键词：MCP 实战、CLI 实战、调用教程、批处理、脚本示例、pdf_merge、image-resize、定时任务
- 在线原文：https://www.xyltools.com/docs/mcp-cli-tutorial

---

## 教程目标与准备

前两篇文章讲了如何接入和命令语法，本篇是动手教程——带您完整走一遍真实调用过程：在 AI 客户端里用一句话让工具箱合并 PDF、下达多步骤任务；在 PowerShell 里编写一个能统计成败的批处理脚本，最后把它固化为每天自动执行的定时任务。

- **您将完成**：1 次 MCP 对话调用、1 次 MCP 多步骤任务、1 个 CLI 批处理脚本、1 个定时任务
- **预计耗时**：约 20 分钟
- **前置条件**：已按「MCP 服务接入」或「CLI 命令行调用」完成接入，效率工具箱已登录且订阅有效

> **还没接入？**：AI 客户端用户请先阅读「MCP 服务接入」（设置页一键勾选即可）；脚本用户无需接入，只要本机装有效率工具箱就能直接调 CLI。

## MCP 实战一：一句话合并 PDF

1. **确认连接正常**：打开 AI 客户端的 MCP / 连接器管理页，确认 yinlian-toolbox 处于已连接状态，工具列表不为空。
2. **发出请求**：在对话框直接说需求，尽量把文件路径说全，AI 就不需要再到处找文件。
3. **AI 调用工具**：AI 识别出这是合并 PDF 的任务，自动选择工具箱的 pdf_merge 工具并按顺序构造参数。部分客户端会在调用前弹窗请求确认，允许即可。
4. **查收结果**：AI 汇报合并完成并给出生成的文件路径，打开确认即可。整个过程您只说了一句话。

**请求示例（直接复制到对话框）**

```text
请把桌面上的 封面.pdf、正文.pdf、附录.pdf 三个 PDF 按这个顺序合并成一个，命名为 成品手册.pdf，保存到桌面。
```

| 对话环节 | 背后发生的事 |
| --- | --- |
| 您说出需求 | 自然语言被 AI 解析为「合并 PDF」意图 |
| AI 挑选工具 | 从近 400 个工具中选中 pdf_merge（PDF合并） |
| AI 构造参数 | 按参数说明把三个路径用分号拼成 input_paths，output_path 指向桌面 |
| 工具执行 | 效率工具箱本地完成合并，文件不经过网络 |
| AI 汇报结果 | 把工具返回的结构化结果翻译成一句话告诉您 |

> **路径说得越全，结果越准**："帮我合并这几个 PDF"也能成功，但 AI 需要先用文件搜索工具定位文件，多花一轮对话。直接把完整路径（或"桌面上的 xxx.pdf"）说清楚，一步到位。

## MCP 实战二：一句话下达多步骤任务

MCP 通道的真正威力在多步骤任务上：您只需描述最终目标，AI 会自动拆解成多个工具调用并依次执行。下面这个需求包含「多图合 PDF」和「按目标体积压缩」两个步骤。

**多步骤请求示例**

```text
把 D:\扫描件 文件夹里的 8 张图片按文件名顺序合成一个 A4 大小的 PDF，然后把它压缩到 10 MB 以内，最终文件保存到 D:\输出。
```

| AI 拆解出的步骤 | 调用的工具 | 关键参数 |
| --- | --- | --- |
| 1. 多张图片合成 PDF | images_to_pdf（多图合PDF） | images=8 张图片路径；paper_size=a4 |
| 2. 压缩到目标体积 | pdf_compress（PDF压缩） | target_size_mb=10，自动调整压缩参数 |
| 3. 汇报结果 | — | 告知最终文件路径与压缩后的实际大小 |

> **让 AI 更懂「印联」的说法**：把设置页「MCP 接入」区提供的智能体规则文本粘贴到 AI 客户端的规则 / 系统提示词中。之后您说"印联""工具箱""用快印通打印"等任何别名，AI 都能准确路由到工具箱对应的工具，不会自己瞎实现。

> **不可逆操作会先确认**：涉及删除、覆盖、打印等不可逆操作时，规范配置的 AI 客户端会先向您确认再执行。如果 AI 直接执行了您没要求的高风险操作，请检查是否启用了客户端的"工具调用自动批准"。

## CLI 实战一：从第一条命令开始

1. **定位安装目录**：效率工具箱默认安装在 C 盘程序目录。下文统一用 $exe 变量指向 EfficiencyToolbox.exe，请把路径换成您的实际安装位置。
2. **查看工具清单**：执行 --list 查看全部近 400 条命令。这一步不需要登录授权，随时可跑。
3. **执行第一条命令**：选一个最简单的 pdf-merge 试试。看到 SUCCESS: 开头的输出行就是成功。
4. **忘记参数怎么办**：直接执行命令但不带必需参数，CLI 会返回错误并自动打印该命令的完整参数帮助。

**三步上手**

```powershell
$exe = "C:\Program Files\YinLian\EfficiencyToolbox\EfficiencyToolbox.exe"   # 换成您的实际路径

# 1. 查看全部命令（无需登录）
& $exe --cli --list

# 2. 合并两个 PDF
& $exe --cli pdf-merge --input-paths "D:\资料\a.pdf;D:\资料\b.pdf" --output-path "D:\资料\merged.pdf"

# 3. 忘参数时：故意不带参数，让 CLI 打印帮助
& $exe --cli image-resize
```

## CLI 实战二：编写批处理脚本

实战场景：把「原图」文件夹里的所有 JPG 统一缩放到 1920 像素宽（保持比例），输出到「处理后」文件夹，并统计成功 / 失败数量。脚本展示了遍历文件、调用 CLI、解析退出码三个关键动作。

**batch-resize.ps1**

```powershell
$exe = "C:\Program Files\YinLian\EfficiencyToolbox\EfficiencyToolbox.exe"
$src = "D:\原图"
$dst = "D:\处理后"
New-Item -ItemType Directory -Force -Path $dst | Out-Null

$ok = 0; $fail = 0
Get-ChildItem $src -Filter *.jpg | ForEach-Object {
    $file = $_.Name
    $lines = & $exe --cli image-resize --input-path $_.FullName --width 1920 --output-path "$dst\$file"
    if ($LASTEXITCODE -eq 0) {
        $ok++
    } else {
        $fail++
        # 退出码非 0：打印 ERROR: 行定位原因（3 = 未登录/订阅到期）
        $lines | Where-Object { $_ -like "ERROR:*" } | ForEach-Object { Write-Warning "${file}: $($_.Substring(6))" }
    }
}
Write-Host "批处理完成：成功 $ok 个，失败 $fail 个"
```

- 用 $LASTEXITCODE 判断单次调用成败，比解析输出行更可靠；退出码 3 代表未登录或订阅到期，先去效率工具箱里处理授权。
- 批量处理类命令还会输出 PROGRESS: 行，脚本可以实时解析百分比刷新自己的进度显示。
- 输出统一为 UTF-8。Python 集成时 subprocess 记得加 encoding="utf-8"，避免中文结果乱码。
- 脚本按顺序逐个处理，几百个文件也很稳定；工具箱本地执行，文件内容不上传。

## 组合用法：MCP 探索参数，CLI 固化流程

两条通道最顺手的配合方式：先用 MCP 对话把任务跑通、把参数试对，再让 AI 把同样的调用翻译成 CLI 命令写进脚本，最后挂到计划任务里每天自动执行。

1. **MCP 对话试跑**：在 AI 客户端里用自然语言把任务完整跑一遍，确认参数和结果符合预期（例如上面的"统一缩放到 1920 宽"）。
2. **让 AI 给出 CLI 写法**：直接对 AI 说："把刚才的处理改成效率工具箱的 CLI 命令，写成 PowerShell 脚本"。AI 会输出对应的 EfficiencyToolbox.exe --cli ... 脚本。
3. **挂到计划任务**：把脚本保存为 .ps1 文件，用 Windows 计划任务定时执行。下面示例让脚本每天 22:00 自动运行。

**创建每日定时任务**

```powershell
schtasks /Create /TN "YinLian-BatchResize" /TR "powershell -ExecutionPolicy Bypass -File D:\scripts\batch-resize.ps1" /SC DAILY /ST 22:00
```

> **定时任务的授权前提**：CLI 每次执行前都会校验登录状态与订阅有效期。若脚本在无人值守时段报退出码 3，说明凭据过期，打开效率工具箱重新登录一次即可恢复（凭据存本机，登录一次长期有效）。

## 常见坑速查

| 现象 | 原因 | 对策 |
| --- | --- | --- |
| AI 说找不到这个工具 | 接入后没重启客户端，或客户端启用的工具太少 / 被禁用 | 重启 AI 客户端，在工具管理面板确认工具箱工具已启用 |
| 调用返回"未登录"或退出码 3 | 两条通道共用授权门，未登录或订阅到期 | 打开效率工具箱完成登录 / 续费后重试 |
| AI 选错工具（如用 Word 合并去合 PDF） | 启用工具过多导致挑选准确率下降 | 只启用常用工具组，并粘贴设置页的智能体规则文本 |
| CLI 结果中文乱码 | 脚本按系统默认编码（GBK）读取了 UTF-8 输出 | Python 加 encoding="utf-8"；PowerShell 7 默认 UTF-8 无需处理 |
| 路径带空格或中文报"找不到文件" | 命令行参数未加引号被截断 | 所有路径用英文双引号包裹；多个路径用分号分隔写在一个参数里 |
| 脚本以为任务挂了 | 长时间任务没有输出——其实在持续输出 PROGRESS: 行 | 实时解析 PROGRESS: 行更新进度；确需中止按 Ctrl+C（退出码 2） |

## 相关文章

---

## 相关文章

- [智能体接入概览](https://www.xyltools.com/docs/agent-integration-overview)
- [MCP 服务接入](https://www.xyltools.com/docs/mcp-server-guide)
- [CLI 命令行调用](https://www.xyltools.com/docs/cli-command-reference)