Safe DOCX MCP 服务器

关键词

DOCX自动化编辑本地文档处理文档工作流AI 集成

使用说明（Markdown 格式）

  1. 项目简介
  • 该仓库实现了一个完整的 MCP 服务器，用于对 Microsoft Word DOCX 文档进行沉浸式后处理。服务器实现了资源管理、工具注册与执行、以及提示模板等 MCP 服务器核心能力，供 LLM 客户端以标准化的方式读取文档、执行工具（如 read_file、grep、replace_text、insert_paragraph、save 等）以及获取/渲染 Prompts。
  1. 主要功能点
  • 资源与数据访问：托管和管理 DOCX 相关资源，提供文档与会话的上下文信息。
  • 工具注册与执行：提供多组工具（如 read_file、grep、replace_text、insert_paragraph、save、format_layout、add_comment、get_comments、delete_comment、等），支持单工具调用及通过计划/合并执行的复杂工作流。
  • 会话管理：创建、追踪、过期、清理会话，维护会话的基线、变更记录和缓存。
  • Prompts/模板：定义与渲染提示模板，辅助 LLM 与工具的组合使用。
  • MCP JSON-RPC 通信：服务器端接收 JSON-RPC 请求，返回标准化的 JSON-RPC 响应，或发送通知。
  • 传输协议：当前实现通过 Stdio 传输，便于在本地、容器或管道中对接客户端；文档中也支持其他传输方案的概念。
  • 安全与合规：实现了路径策略、存档安全检查、非破坏性变更的追踪输出等，确保在本地执行且可控。
  1. 安装与运行步骤
  • 依赖安装与构建
    • 安装依赖：在仓库根目录执行 npm install
    • 构建：执行 npm run build（若有对应的构建脚本，见实际 package.json 配置）
  • 启动 MCP 服务器
    • 通过命令行启动：node dist/index.js（或等价的入口，取决于打包输出配置）
    • 运行前请确保 Node.js 版本符合项目要求（通常为 18+）
  • 客户端对接
    • MCP 客户端需要配置服务器信息，以便通过 MCP 协议进行通信。客户端配置通常包含服务器名称、启动命令及其参数等信息，用于在客户端侧启动与 MCP 服务器的对接。
    • 本仓库中提供的 manifest.json 示例中包含 server.type、server.entry_point、server.mcp_config 等字段，用于 MCP 客户端构建对接信息。
  1. 服务器配置（示例，MCP 客户端需要） 注意：以下为配置示例，描述服务器在 MCP 客户端侧的对接信息，实际使用时请按 MCP 客户端的格式载入。配置中的字段含义已在说明中给出。

{ "server": { "name": "Safe DOCX MCP Server", "type": "node", "entry_point": "dist/index.js", "mcp_config": { "command": "node", "args": ["${__dirname}/dist/index.js"] } // 备注: // - server.name：服务器的显示名称，供 MCP 客户端识别。 // - type：服务器实现类型，node 表示在 Node.js 环境中运行。 // - entry_point：打包产出的入口文件路径，供 MCP 客户端参考。 // - mcp_config：实际用于启动服务器的命令及参数（客户端需要的字段）。 } }

  1. 基本使用方法
  • 开始前提
    • 确保已正确构建并运行服务器，服务器通过 MCP JSON-RPC 与客户端通信。
  • 典型工作流
    • 客户端（LLM/工具链）通过 MCP 调用服务器提供的工具（如 read_file、grep、replace_text、insert_paragraph、save 等），并接收标准化的返回结果。
    • 服务器负责会话创建与管理、工具执行、结果组合、错误处理与安全检查。
    • 客户端可按需查询资源、执行工具计划、渲染 Prompts、并获取输出结果或下载文档等。
  • 常见注意点
    • 使用前请确认 MCP 客户端配置正确，尤其是启动命令与参数路径等字段。
    • 服务器实现包含完整的工具集、会话管理与安全策略，适用于本地 AI 工作流的文档编辑与审核。
  1. 参考与组件
  • 基于 MCP 服务器核心：请求/响应的 JSON-RPC、资源管理、工具执行、会话管理、Prompts 渲染、传输协议支持等。
  • MCP 服务器具体实现：Safe Docx 框架中的 docx-mcp 模块，包含工具集合、会话实现、以及与 DOCX 的交互逻辑。
  • 测试覆盖：包含多组端到端与单元测试，覆盖工具路径、会话生命周期、并发变更、文档 round-trip、严格事务等场景，确保服务器行为符合 MCP 规范。
  1. 其他
  • 如需查看具体工具及实现细节，请参考仓库中的 packages/docx-mcp 目录下的 server.ts、tools、session、cli、testing 等文件，以及相应的测试用例。

服务器信息

访问项目