把开源项目 OfficeCLI 接进你的 Agent：内置 MCP 服务器与一键注册路径
本文基于 OfficeCLI 仓库 commit 459b1a4（2026-08-04）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/iOfficeAI/OfficeCLI 最新代码与文档为准。
**这个 MCP 服务器只向 Agent 暴露一个工具、一个参数，能力面全部藏在那个参数的字符串里——理解这一点，接入和排障就都顺了。**先说清对象：OfficeCLI 是 GitHub 上 iOfficeAI/OfficeCLI 这个开源项目，Apache-2.0 许可，NOTICE 文件写明 Copyright 2026 OfficeCLI，由 goworm 创建维护。它不是微软的产品，也不是”用命令行操作 Office”这个泛指概念；文中提到 Word、Excel、PowerPoint 时，指的是 .docx / .xlsx / .pptx 这三种文件格式和打开它们的应用，跟这个项目的归属没有关系。它的卖点是单个自包含二进制，.NET 运行时打包在里面，机器上不装 Office 也能读写这三种文件。
站内讲 MCP 的文章各管一段：MCP 协议本身是什么讲的是协议层的握手与消息模型，一个 MCP 服务器该暴露多少个工具讲的是工具数量对上下文预算的影响，Pascal Editor 的 MCP 接入是另一个项目在同一个协议上的做法。这篇只做一件事：把 OfficeCLI 这个具体仓库的接入路径和能力面读出来，代码在哪、写了什么、对你意味着什么。
一、它给 Agent 的不是一堆工具，是一个命令行入口
打开 src/officecli/McpServer.cs，第一个反直觉的地方是 WriteToolDefinitions：整个 tools/list 只写出一个工具，名字就叫 officecli。它的 inputSchema 里只有一个必填属性 command，类型是「字符串或字符串数组」。tools/call 里还有一道硬拦截——工具名不等于 officecli 就直接返回 -32602，注释写明理由是「误路由的调用不能悄悄执行，否则会以一个不存在的工具名去改文件」。
拿到 command 之后走 ExtractArgv：数组形式逐个取值，非字符串元素退化成它的 JSON 原文；字符串形式交给 Tokenize 做引号感知切分。Tokenize 有两处值得留意。一是它从不调用 shell，切出来的 token 直接进进程内的 System.CommandLine 解析器，所以不存在命令注入面。二是双引号内部的反斜杠只转义 " 和 \ 两个字符，其余原样保留——注释解释得很直白：旧的”转义下一个字符”规则会把 text="A\nB" 吞成字面量 AnB，现在 \n 保持两个字符，留给下游的属性解析器变成真正的换行。另外，如果模型照抄技能文件里的示例、把开头的 officecli 也带进来了，ExtractArgv 会把它剥掉。
真正执行在 RunCliRaw：拿共享的 RootCommand 解析 argv，把 Console.Out 和 Console.Error 临时换成 StringWriter，调用 pr.Invoke()，再换回来。这里有个刻意的设计决定——解析失败不短路。注释说明，让 Invoke 继续跑，System.CommandLine 会把终端用户看到的那份错误加用法块原样写进被捕获的流里，Agent 因此能读到完整的选项列表，而不是一句被剥掉上下文的报错。
结果如何封装，看 SurfaceCliResult。stdout 和 stderr 同时非空时合并输出，避免丢掉”成功了但有告警”这种情形。最有意思的是退出码 2 的处理：退出码 2 且 stdout 非空被判定为「应用成功但有保留」——元素已经加进去了，只是某个不支持的属性被丢弃，这种情况不置 isError，理由是把它报成硬错误会让 Agent 重发一个其实已经生效的操作。而脚本直接跑 CLI 时仍然看到退出码 2，快速失败的语义只在 MCP 这层被放宽。
两条特例绕开了命令根。一是 load_skill / skill / skills，这几个动词在 src/officecli/Program.cs 里是早期分发，压根没进 System.CommandLine，所以 McpServer 用 HandleSkillCommand 从同一个 SkillInstaller 单独供上。二是截图：IsScreenshot 判定 argv 首个 token 是 view 且参数里出现 screenshot，然后 RunScreenshotArgv 会在调用方没给 -o 时自动注入一个临时文件路径，把渲染出的 PNG 读回来做成 base64 的 image 内容块返回。自动注入的临时文件用完即删，调用方自己指定的 -o 则原样保留。
协议层是手写的最小实现：initialize 返回的 protocolVersion 是 2024-11-05，capabilities.tools.listChanged 为 false，serverInfo.name 是 officecli。支持的方法只有 initialize、notifications/initialized、tools/list、tools/call、ping。JSON-RPC 2.0 允许的数组批量请求明确不支持，会回 -32600 并说明原因；根节点不是对象的其它情况同样是 -32600，解析失败是 -32700。所有 JSON 都用 Utf8JsonWriter 手写，文件头部注释给的理由是避开反射，以便发布时做裁剪。
二、注册这条路：命令改了哪个文件
src/officecli/McpInstaller.cs 干的事只有一件：把「用哪个可执行文件、带什么参数启动 MCP 服务器」写进各家客户端的配置。officecli mcp <target> 注册，officecli mcp uninstall <target> 反注册，officecli mcp list 查状态；不带任何参数的 officecli mcp 则是启动服务器本身，这个分发在 Program.cs 里，还留了个老别名 mcp-serve。
识别的目标有四类，别名都在 Install 的 switch 里：lms / lmstudio / lm-studio、claude / claude-code、cursor、vscode / copilot。这四类之外的写法会打到 default 分支，往 stderr 打一句未知目标并返回非零。
真正容易踩的是「记哪条路径」。OfficecliPath 这个属性按优先级解析：先看 Core.Installer.InstalledBinaryPath 指向的规范安装位置（Unix 是 ~/.local/bin，Windows 是 %LOCALAPPDATA%\OfficeCli），文件存在就用它，因为自安装是原地覆盖同一个文件，路径永远不变；再退到 PATH 上找到的 officecli，而且 ResolveOnPath 刻意不解析符号链接，行为对齐 which；最后才退到当前进程路径。注释把理由说透了：绝不能用 Environment.ProcessPath，它会把符号链接解析成带版本号的实际目标，包管理器一升级这条路径就烂了。
Claude Code 这一路走的是另一套。注释指出 Claude Code 读的是 ~/.claude.json 顶层的 mcpServers，而不是 ~/.claude/settings.json——后者没有这个键，写进去会被静默忽略，服务器根本不出现在列表里。而且这个文件是运行中的客户端在写的活状态，所以安装器优先调官方 CLI：先 claude mcp remove -s user officecli 清掉旧条目（因为 mcp add 在名字已存在时会报错），再 claude mcp add -s user officecli -- <路径> mcp。claude 不在 PATH 上时才退回直接写 JSON。调子进程那段也做了防御：两个流异步排空，WaitForExit 给 30 秒上限，超时就 Kill——注释说串行 ReadToEnd 曾经在子进程交错输出大量 stderr 时死锁过。
Cursor 和 VS Code 走通用的 JSON 安装器，分别写 ~/.cursor/mcp.json 和 ~/.vscode/mcp.json，键都是 mcpServers。LM Studio 不是改一个 JSON，而是在 ~/.cache/lm-studio/extensions/plugins/mcp/officecli 下建目录，写 manifest.json、mcp-bridge-config.json、install-state.json 三个文件，然后提示你重启 LM Studio 才生效。反注册时若 officecli 是唯一一个 server，UninstallJson 会把整个 mcpServers 键删掉，不留空对象残渣。
三、能力面其实写在工具描述里
只有一个工具，模型怎么知道能干什么？答案是那段很长的 description。WriteToolDefinitions 把三段拼起来：ToolDescription 常量、McpHelpStrategy 常量、再加 SkillInstaller.BuildSkillTriggerSummary() 的返回值。
ToolDescription 列出了动词全集：create、view、get、query、set、add、remove、move、swap、validate、batch、raw、help、load_skill；view 的模式包括 text、annotated、outline、stats、issues、html、svg、screenshot、forms。它还写死了一条四步交付门，措辞是「报告文档完成之前」必须过：先 validate 通过 schema 校验；再 view issues 确认没有溢出与结构问题（溢出指文字或元素超出了它所在的框、页面或单元格边界，文本模式下看不出来，渲染出来才现形），并扫一遍正文里残留的占位符；然后用 view <file> screenshot --page N 渲染出图做视觉审查，描述里要求「带着有问题的预设去看」，渲染不出来就明说未做视觉验证；最后以 save <file> 收尾把改动刷到磁盘。描述里同时留了退路：这道门是否强制，以格式为准，load_skill pptx（或 word / excel）里的 SKILL.md 才是权威。
McpHelpStrategy 是操作层的几条经验：先用 view 的 outline / stats / issues 摸清文档再动手；同一个文件上有 3 次以上修改就用 batch 走一个开关文件周期；get 输出的键可以直接当 set 的输入键；路径是 1 起始的，形如 /slide[1]/shape[2]、/body/p[3]、/Sheet1/A1。
第三段最能说明这个项目对模型行为的观察。SkillInstaller.BuildSkillTriggerSummary 生成的是一行祈使句，要求在对任何 Office 文件执行 create/add/set/remove 之前先 load_skill，后面跟着每个技能一句话的触发词，SkillTriggers 字典里有 10 条，覆盖幻灯片、Word 文档、电子表格、可填表单、跨页平滑切换动画（morph，指相邻两页间同名元素自动补间的过渡效果）、3D 平滑切换、融资路演稿、学术论文、数据看板、财务模型。方法上的注释解释了为什么用祈使语气：信息性的措辞（“想看完整指南可以……”）在实测中连能力不错的模型都会忽略，直接跳去 create/add 猜 schema，只有 FIRST … BEFORE … 这种命令式才真的触发技能加载。这是「推最小触发、拉完整细节」的分工——常驻上下文里只留一行，细节留在 skills/ 下 11 个目录各自的 SKILL.md 里，用 load_skill 现取。
四、这套接入由哪些块组成
下面这些路径都是仓库里实际存在的位置，你可以逐个打开对照。
| 组成部分 | 它负责什么 | 仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| MCP 服务器主体 | stdio 上的 JSON-RPC 循环、单工具定义、结果封装 | src/officecli/McpServer.cs | 排查”调了没反应”或”成功却被判成错误” |
| 客户端注册器 | 把二进制路径写进各家客户端的 MCP 配置 | src/officecli/McpInstaller.cs | 首次接入、换机器、升级后路径失效 |
| 早期分发入口 | mcp、load_skill 等在进命令解析器之前就被拦下 | src/officecli/Program.cs | 想弄清某个子命令为什么在 MCP 里走了别的路 |
| CLI 命令根 | 动词与参数的唯一定义处，MCP 与终端共用 | src/officecli/CommandBuilder.cs 及同名分部文件 | 想确认某个开关在 MCP 里能不能用 |
| 技能包 | 分格式、分场景的 SKILL.md，按需拉取 | skills/ 下 11 个目录，各 1 份 SKILL.md | 做路演稿、财务模型这类有固定套路的活 |
| 远程抓取守卫 | 所有 http/https 拉取的地址校验与体积上限 | src/officecli/Core/SsrfGuard.cs | 文档里带了外部图片或数据源 URL |
| 落盘策略 | 内存里的修改什么时候真的写进磁盘 | src/officecli/Core/ResidentFlushPolicy.cs、src/officecli/ResidentServer.cs | 另一个程序要读同一个文件 |
顺带说一句仓库规模，方便你判断读代码的成本。这些数字任何人 ls 一下就能复现：全仓 1201 个受版本控制的文件，src/officecli/ 下 469 个（其中 353 个 .cs），schemas/ 153 个（152 份 json），examples/ 381 个，assets/ 37 个，sdk/ 下 node 与 python 两套，根目录四个语言版本的 README（en/zh/ja/ko）外加一份根级 SKILL.md。三个格式的处理器体量按目录数文件是：src/officecli/Handlers/Pptx 65 个、Handlers/Word 54 个、Handlers/Excel 47 个。CommandBuilder 被拆成十几个 CommandBuilder.*.cs——C# 的分部类允许同一个类的代码分散在多个文件里，编译时合成一个，所以这些文件里的动词其实同属一个命令根。
还有一件事得说清。仓库 README 开头把自己称为 “the world’s first and the best Office suite designed for AI agents”，这是项目自己的说法，不是本文的判断；README 里那张跟 Microsoft Office、LibreOffice、python-docx / openpyxl 的对比表同样出自维护者之手，你要拿它当选型依据的话，最好自己跑一遍再说。
五、边界与代价：它放弃了什么
**放弃了逐命令的 schema。**只有一个 command 参数，好处是 CLI 的每一个开关自动可用，不会因为手写映射漏掉参数，坏处也很直接：模型拿不到分动词的结构化参数约束，写错了只能靠回传的错误加用法块自纠。这套设计把「参数正确性」从协议层挪到了运行时反馈层，代价是多几轮往返。这跟工具返回值该怎么设计里讲的取舍是同一类问题。
**它改的是原文件，不是副本。**没有任何一处自动备份。create 之外的动词直接落在你给的那条路径上。MCP 会话启动时会把 OFFICECLI_NO_AUTO_RESIDENT 默认设成 1，注释解释得很细：这只是「不主动派生常驻进程」，不是「绕过已有常驻」。两种后果不同——没有常驻持有该文件时，命令打开、应用、立即保存，响应返回时改动已经在磁盘上；已经有别的 officecli 常驻持有该文件时，命令会路由过去，跟随那个常驻的延迟落盘节奏，也就是等它 save、close 或空闲自动保存（自适应区间的两个常量写在 src/officecli/Core/ResidentFlushPolicy.cs 里，是 2 秒到 10 秒，按文档实测的保存开销缩放，README 也是这个说法）。所以「MCP 里改完就一定在盘上」这个假设只在前一种情况成立。工具描述把 save 列为交付门第四步，正是为这个准备的。
**批量操作中途失败会留下什么，取决于开关。**README 说明 batch 默认原子，任何一项失败整批回滚；--best-effort 保留已成功的部分；--stop-on-error 在第一个失败处停下，但除非同时加 --best-effort，仍然回滚。默认值是安全的那个，但你一旦为了”别全白干”加上 --best-effort，就得自己承担半应用状态。
拉外部资源的暴露面是真实存在的。SsrfGuard.cs 的注释说得很清楚：picture=、data=、model3d=、media= 这些属性都接受调用方给的 URL，而在 Agent 场景里，这个 URL 可能来自不可信输入——批处理脚本、工具调用参数，甚至是嵌在文档里的一句指令。守卫的做法是在 ConnectCallback 里校验真实连接地址而不是提前解析主机名，从而堵上 DNS 重绑定的时间窗，并且每一跳重定向都校验（最多 10 跳），拒绝回环、RFC1918 私网、169.254 链路本地（云元数据端点）、100.64 运营商级 NAT、IPv6 的 fc00::/7 与组播地址；单次抓取上限是 MaxRemoteBytes，写死 100 MB。这道守卫挡的是内网探测和元数据窃取，挡不住「往公网某个地址发一次请求」本身。如果你的 Agent 会处理来路不明的文档，这条得算进威胁模型，参考给 Agent 划安全边界。
它是长驻进程，且自己会联网检查升级。RunPeriodicUpgradeCheckAsync 在服务器启动时跑一次 UpdateChecker.CheckInBackground()，之后每小时唤醒一次。注释说明了必要性：Program.cs 里 mcp 分支在常规的每次调用更新检查之前就返回了，不加这个钩子，一个启动后挂几周的 MCP 实例永远看不到新版本。下载、校验和替换文件放在 stdio 被重定向的子进程里做，不会污染 stdout 的 JSON-RPC 流；去抖靠 ~/.officecli/config.json 里同一个 24 小时时间戳，所以 24 次唤醒里有 23 次什么都不干。要点在于：这意味着你机器上那个能直接改文档的二进制，可能在你不知情时被换掉。README 给的关闭方式是 officecli config autoUpdate false，这条开关对常驻 MCP 进程这条后台路径是不是同样拦得住，得去读 UpdateChecker 才能下结论，别想当然。
**它明确不管的事。**不管版本管理与冲突合并，不管权限与审批，不管你把哪个文件交给了谁。它也不试图理解文档语义——所有”这份稿子写得好不好”的判断都在模型那边，工具只负责让改动落到 OOXML 里（OOXML 就是 .docx/.xlsx/.pptx 的内部格式，本质是一个 zip 包，里面装着描述内容与样式的 XML 分部件）。
六、上手与避坑清单
**先决定注册哪个目标，再决定用不用 CLI 那条路。**为什么会踩：Core/Installer.cs 里的 McpTargets 表把 vscode 与 lms 标为没有技能等价物，也就是这两个客户端只会拿到 MCP 注册，不会像 Claude Code、Cursor 那样另外装技能文件。怎么避：如果你的客户端在这张表的后两类里，别指望技能自动到位，靠 MCP 工具描述里那行触发语加 load_skill 现取。
**Claude Code 用户别去改 ~/.claude/settings.json。**为什么会踩：这个文件看起来才像”设置”，但源码注释明确指出它没有 mcpServers 键，写进去会被静默忽略，claude mcp list 里根本不出现。怎么避：让 officecli mcp claude 自己去写，它优先调官方 CLI 落到 ~/.claude.json；要手改也只改这个文件的顶层 mcpServers。
**换了安装方式就重跑一次注册。**为什么会踩：注册时写死的是当时解析出的那条二进制路径。从手动下载改成 Homebrew，或者反过来，旧配置里那条路径可能已经指不到东西了。怎么避：重跑 officecli mcp <target>——InstallClaude 是幂等的，会先删旧条目再按当前解析结果重建；然后用 officecli mcp list 确认四个目标的勾选状态。
**别把已有配置文件当成安全的。**为什么会踩：InstallJson 读取现有配置时，如果 JsonDocument.Parse 抛异常，catch 块的注释是”解析失败就从头开始”，随后写出的文件只包含它自己重建的内容。也就是说一个尾逗号或注释导致的解析失败，可能让你原有的其它配置在这次写入中消失。怎么避：注册前把目标配置文件备份一份，或者先确认它是严格合法的 JSON。
**参数带空格和引号时用数组形式。**为什么会踩：字符串形式要过 Tokenize，多层引号很容易切出你不想要的结果。怎么避：command 本来就接受预切分的字符串数组，工具描述里也明说了”参数含空格或引号时用数组形式”。另外注意数组形式会保留空字符串元素，这是刻意的——它正是”把某个属性值清空”的表达方式。
**交还文件之前显式刷盘。**为什么会踩：如果这台机器上正好有个常驻进程持有同一个文件，你的修改要等它自己落盘。python-docx、openpyxl、Word 本身或者上传脚本读到的会是旧内容。怎么避：按工具描述的第四步，以 save <file> 收尾；如果是每条命令后都有别的程序读，README 给的做法是设 OFFICECLI_RESIDENT_FLUSH=each。
**排障从退出码语义看起。**为什么会踩：SurfaceCliResult 会把退出码 2 且有 stdout 的情况判成”应用成功但有保留”，isError 是 false。你在 Agent 侧看到成功，实际可能有个属性被丢了。怎么避：把返回文本完整读进日志，别只看 isError 这个布尔量。
收个尾
接入本身很短：装二进制，跑一条 officecli mcp <target>，重启客户端。真正需要你花时间的是搞清楚它的能力面长什么样——一个工具、一个字符串参数、一段把交付门和技能触发写死在里面的描述文本。
上线前过三个问题：这台机器上的文档改动有没有副本或版本兜底；Agent 可能收到的外部 URL 有没有进你的威胁模型；那个能直接写你磁盘的二进制会不会在后台被换掉，以及你接不接受。
想再往下读，按这个顺序：src/officecli/McpServer.cs 看协议层与结果封装，src/officecli/McpInstaller.cs 看注册落到哪，src/officecli/Core/SkillInstaller.cs 看技能是怎么被发现和加载的，src/officecli/Core/UpdateChecker.cs 看后台升级到底会做什么。
本篇属于一个把开源Office 文档读写套件 OfficeCLI逐层拆开讲的系列，整体地图见 OfficeCLI 是什么：给 AI Agent 用的开源文档读写套件；沿着这条线往下，还可以看 OfficeCLI 开源项目上手：三种装法怎么选，第一次跑前先懂这件事 和 开源项目 OfficeCLI 的命令面全景：一套动词打通三种文档。