MCP word (mcp-word)

MCP Word--MCP服务器+办公外接程序

版本: 0.1.0\ 日期: 2025-08-13 语言：仅限英语

使用本地MCP服务器（stdio）通过Socket桥接到Office.js任务窗格，对Microsoft Word进行AI驱动的文档编辑。通过HTTPS进行IO。此项目构建MCP服务器(node server.js)与Office.js Word插件客户端一起使用，以启用AI驱动的文档编辑工作流。

建筑

flowchart LR
  A[Codex CLI] -->|stdio| B[MCP Server]
  B -->|WebSocket| C[Office.js]

组件

MCP服务器(server.js)

1. 进口 McpServer 从 @modelcontextprotocol/sdk/server/mcp.js
2. 进口 StdioServerTransport 从 @modelcontextprotocol/sdk/server/stdio.js
3. 通过以下方式动态加载工具 registerTools 从任一 tool.js （默认）或 tool_simple.js （当 --simple)
4. 工具模式如下 schema.json 使用简单枚举（否 anyOf)
5. 将MCP工具有效载荷（JSON）转发到Socket。IO客户端
6. 发射 io.emit(toolName, toolParams) 到Office加载项

Office加载项(public/)

• manifest.xml：定义外接程序ID、版本、提供程序、显示名称、描述。主持人：文件；权限：读写文档
• taskpane.html：加载Office.js和Socket.io客户端，包括 taskpane.js，呈现按钮或自动启动行为
• taskpane.js：用途 Office.onReady() 对于Word主机检测，使用以下命令建立WebSocket io()，监听MCP工具事件，通过调用Word函数 Word.run()，实现错误处理
• taskpane.yaml：用于使用包括Socket.io在内的库导入脚本实验室代码段

片段上传

通过package.json脚本上传到gist：

npm run snippet  # Runs: cd public && gh gist edit 5b44e6ba1c99baae62ebc0783e1469da --add taskpane.yaml

工作流程

1. 安装MCP服务器: npm install
2. 启动服务器：使用Codex CLI中的stdio或伪master，使用unix管道提供输入
3. 侧载外接程序：在Word中加载清单
4. 发送编辑任务请求：通过Codex CLI或其他服务，例如。 { content: '...' }
5. 实时编辑：插件客户端实时接收编辑并将其应用于文档

先决条件

• Node.js 18.17+
• 启用侧载的Microsoft Word（台式机）
• 您的OS/Office信任的本地HTTPS证书（对于开发人员来说，自签名是可以的）

安装

npm install

运行服务器（需要HTTPS）

服务器需要TLS。从PEM密钥/证书或PFX捆绑包开始。

# PEM key/cert
node server.js --key path/to/key.pem --cert path/to/cert.pem --port 3000

# or PFX/P12
node server.js --pfx path/to/cert.pfx --passphrase "your-passphrase" --port 3000

# optional verbose logging
node server.js --key key.pem --cert cert.pem --port 3000 --debug

# simple mode (hooks tool_simple.js for flow testing)
node server.js --key key.pem --cert cert.pem --port 3000 --simple

提示：

• 为开发人员使用自签名证书并将其标记为受信任，以便Office/Browser接受 https://localhost:3000.
• 静态文件从以下位置提供 public/.
• 终点：

- 健康： GET https://localhost:3000/healthz

创建本地开发人员证书

openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -nodes \
  -keyout key.pem -out cert.pem \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

# Optional PFX/P12 bundle
openssl pkcs12 -export -out cert.pfx -inkey key.pem -in cert.pem -passout pass:your-passphrase

信任操作系统密钥链中的证书，以便Word和浏览器接受它。

配置MCP客户端

指示您的MCP客户端运行 server.js 通过Node。

Codex CLI (.codex/config.toml):

# Place in ./.codex/config.toml (project) or ~/.codex/config.toml (user)
[mcp_servers.mcp_word]
command = "node"
args = [
  "/absolute/path/to/server.js",
  "--key", "/abs/path/to/key.pem",
  "--cert", "/abs/path/to/cert.pem",
  "--port", "3000"
]
cwd = "/absolute/path/to/project"
# Optional: env vars
env = { NODE_ENV = "production" }

笔记：

• 使用绝对路径以获得可靠性。
• 如果使用PFX/P12捆绑包：更换 --key/--cert 随着 --pfx /abs/cert.pfx --passphrase "your-passphrase".
• 保存配置后重新启动Codex客户端；工具 ping 和 editTask 应该出现。

克劳德桌面 （设置摘录）：

{
  "mcpServers": {
    "mcp-word": {
      "command": "node",
      "args": ["/absolute/path/to/server.js", "--key", "/abs/key.pem", "--cert", "/abs/cert.pem", "--port", "3000"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

Claude CLI:

claude mcp add mcp-word -- node /absolute/path/to/server.js --key /abs/key.pem --cert /abs/cert.pem --port 3000

Office加载项

将Word连接到服务器的两种方法：

1） 侧载清单

• 打开Word→ 加载项→ 侧向载荷 public/manifest.xml
• 清单指向 public/taskpane.html
• 确保相同的主机/端口和受信任的证书

2） 脚本实验室（备选）

• 选项A（粘贴JS）：安装Script Lab，创建新脚本并粘贴 public/taskpane.js，并添加库 https://cdn.socket.io/4.7.5/socket.io.min.js.
• 选项B（导入YAML）：在Script Lab中，从以下位置导入https://gist.github.com/WangChengYeh/5b44e6ba1c99baae62ebc0783e1469da

工具

editTask

• 目的：通过Socket向外接程序发送编辑指令。IO（事件名称 editTask)
• 模式：如下 schema.json 带有简单枚举的规则（否 anyOf 图案）
• 参数:

- content （字符串，必填）：要插入/替换的文本 - action （“插入”|“替换”|“附加”，默认为“插入”） - target （“光标”|“选择”|“文档”，默认为“选择”） - taskId （字符串，可选） - meta （对象，可选）

JSON-RPC示例（MCP标准输入帧）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "editTask",
    "arguments": {
      "content": "Hello from MCP",
      "action": "insert",
      "target": "selection"
    }
  }
}

拼

• 目的：健康检查；回声 message 或返回 "pong"
• 模式：简单的工具注册，没有复杂的模式

调试

• --debug：将详细日志和错误转储到 debug.log
• 将stdio流输入/输出记录到 debug.log
• 如果启用了调试，则在stdin之后和stdout之前添加管道以进行记录和转发
• 在Socket之前记录JSON字符串。IO发送和Socket之后。IO接收 debug.log
• 健康终点： GET https://localhost:3000/healthz 显示已连接的客户端
• 流记录 debug.log:

- [time][stdin] json string：收到原始MCP stdio帧 - [time][stdout] json string：原始MCP stdio响应 - [time][socket:send] json string：将工具调用转发到Socket。国际组织 - [time][socket.recv] json string：从外接程序接收回来（例如。， edit-complete)

测试

测试模式

• 简单模式： server.js --simple 钩子 tool_simple.js （流量测试）

- 单位： npm run test:simple - 集成： npm run test:int:simple

• 正常模式： server.js （没有 --simple)钩子 tool.js （常规使用）

- 单位： npm test - 集成： npm run test:int

单元测试

• test.sh：使用伪造的stdio对MCP客户端和Office的套接字连接进行单元测试
• 使用shell管道提供输入
• 生成测试JavaScript作为套接字客户端
• 准备 package.json 测试前
• 默认测试端口：3100（3000预留正常使用）
• test_simple.sh：测试 server.js --simple 模式使用 tool_simple.js

通过npm命令运行：

# Simple mode unit test
npm run test:simple

# Full unit test
npm test

集成测试

• test.js：结合MCP客户端+MCP服务器的集成测试(server.js)
• 用途 Client 从 @modelcontextprotocol/sdk/client/index.js
• 列出工具并调用工具（例如。， ping, editTask)
• test_simple.js：测试 server.js --simple 模式

通过npm命令运行：

# Simple mode integration test
npm run test:int:simple

# Full integration test
npm run test:int

端到端测试

使用提供的脚本验证端到端行为。它自动生成开发证书，启动服务器，打开Socket。IO客户端，并通过stdio发送MCP帧。

# Default smoke test
./test.sh

# Pipe custom MCP JSONL (one JSON object per line)
echo '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"editTask","arguments":{"content":"PipeMsg","action":"insert","target":"selection"}}}' | ./test.sh

# Multiple lines
cat <<'EOF' | ./test.sh
{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"ping","arguments":{"message":"hello"}}}
{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"editTask","arguments":{"content":"FromSTDIN","action":"insert","target":"selection"}}}
EOF

笔记：

• 代理发出Socket。MCP工具命名的IO事件。对于 editTask，事件是 editTask 有效载荷是工具参数对象。
• 脚本从第一个脚本中提取预期内容 editTask 线。
• 接受自签名证书以方便测试。

可扩展性

• 支持更多 EditTask 类型（表格、图像、格式）
• 添加WebSocket身份验证、日志记录和错误跟踪

项目结构

mcp_word/
├── server.js          # MCP stdio + Socket.IO bridge (HTTPS)
├── tool.js            # MCP tool registration + Socket.IO forwarding
├── tool_simple.js     # Simplified tool set for flow tests (--simple)
├── public/
│   ├── manifest.xml   # Office add-in manifest
│   ├── taskpane.html  # Minimal task pane
│   ├── taskpane.js    # Applies edit commands via Office.js
│   └── taskpane.yaml  # Script Lab snippet for import
├── test.sh            # E2E test runner (JSONL over stdio)
├── test_simple.sh     # Unit test runner for --simple
├── test.js            # Integration test (normal mode)
├── test_simple.js     # Integration test (simple mode)
├── SPEC.md            # Refined spec
└── README.md

文件要求

本自述遵循SPEC要求，包括（按顺序）：

• 先决条件：Node.js版本、Microsoft Word和受信任的HTTPS证书说明
• 安装： npm install
• 运行服务器：HTTPS启动示例（PEM和PFX），以及 --debug
• 创建本地开发证书：OpenSSL命令生成PEM和PFX
• 配置MCP客户端：通过Codex客户端设置 .codex/config.toml
• Office加载项：两个选项（侧载清单或脚本实验室代码段）
• 工具：文档 editTask 和 ping 带有参数和示例的工具
• 调试： --debug 以及debug.log详细信息
• 测试：如何通过npm命令运行测试
• 项目结构和许可证

许可证

请参阅许可证。