document-mcp

MCP（模型上下文协议）服务器公开 documents.js文档转换, .odb、元数据和字体工具 document-compute.js作为MCP工具，所以说MCP的代理可以转换、检查、编辑和计算docx/pptx/odt/odp/ods/odg/odf/pdf/odb/xlsx/markdown文档，而无需直接针对任何一个库编写TypeScript。

document-mcp 不添加任何转换或编辑逻辑-每个工具都是薄的 registerOperation() 包装器(src/register-operation.ts)在…周围 document-operations DocumentOperation该包包含实际的发送 documents.js的转换函数， DocumentConverter 港口, .odb/PDF阅读器，作为一个Zod模式和一个传输不可知的 run() 每个操作，与（最终）REST服务器共享 document-cli第二次解析自己的标志，而不是在这里定义。 document-cli 是基于相同底层操作的兄弟前端——终端CLI/TUI而不是MCP服务器——因此两者是一个共享实现的独立消费者，可以公开它的不同子集。一个 convert_document 这就是所谓的忠诚 (source, targetFormat) 对往返无损，这是一个尽最大努力重建，为什么-是到底是什么 documents.js自己的Fidelity部分 文件，表格包含；这里就不重述了。

graph TD
    schema("document-schema.js")
    ooxml("ooxml.js")
    odf("odf.js")
    pdfcodec("pdf-codec")
    mdcodec("markdown-codec")
    bytecodec("byte-codec")
    documents("documents.js")
    outline("document-outline.js")
    compute("document-compute.js")
    operations("document-operations")
    mcp("document-mcp")
    cli("document-cli")

    schema --> outline
    schema --> compute
    schema --> mcp
    schema --> ooxml
    schema --> odf
    schema --> pdfcodec
    schema --> mdcodec
    schema --> documents
    ooxml --> documents
    odf --> documents
    pdfcodec --> documents
    mdcodec --> documents
    bytecodec --> pdfcodec
    bytecodec --> documents
    documents --> operations
    outline --> operations
    compute --> operations
    operations --> mcp
    documents --> cli
    odf --> cli
    pdfcodec --> cli

    click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
    click ooxml "https://github.com/ExaDev/documents.js/tree/main/packages/ooxml.js" "ooxml.js"
    click odf "https://github.com/ExaDev/documents.js/tree/main/packages/odf.js" "odf.js"
    click pdfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-codec" "pdf-codec"
    click mdcodec "https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec" "markdown-codec"
    click bytecodec "https://github.com/ExaDev/documents.js/tree/main/packages/byte-codec" "byte-codec"
    click documents "https://github.com/ExaDev/documents.js" "documents.js"
    click outline "https://github.com/ExaDev/documents.js/tree/main/packages/document-outline.js" "document-outline.js"
    click compute "https://github.com/ExaDev/documents.js/tree/main/packages/document-compute.js" "document-compute.js"
    click operations "https://github.com/ExaDev/documents.js/tree/main/packages/document-operations" "document-operations"
    click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
    click cli "https://github.com/ExaDev/documents.js/tree/main/packages/document-cli" "document-cli"

    style mcp fill:#f9a825,stroke:#333,stroke-width:3px

开始

直接运行服务器-不需要安装步骤：

npx document-mcp

服务器使用 它的交通 （作为本地进程运行）。这由Claude Code， Claude Desktop, Codex CLI， Codex Desktop和OpenCode直接支持。克劳德·韦伯(克劳德。ai)、Claude Mobile和ChatGPT都需要一个 远程HTTP MCP服务器-参见 远程传输 下面。

兼容性

从Claude Code连接

一行（直接添加MCP服务器）：

claude mcp add --transport stdio document-mcp — npx -y document-mcp

或者作为Claude Code插件安装（这个repo是一个插件市场-包括新版本的自动更新）：

从终端：

claude plugin marketplace add ExaDev/document-mcp
claude plugin install document-mcp@exadev

或者从正在运行的Claude Code会话中：

/plugin marketplace add ExaDev/document-mcp
/plugin install document-mcp@exadev

运行 /reload-plugins 在已经运行的会话中激活。在Claude Desktop或Claude .ai上： 自定义→插件→浏览插件，搜索 document-mcp，并安装。

从Codex CLI连接

codex mcp add document-mcp — npx -y document-mcp

或者通过Codex桌面应用程序： 设置→MCP服务器→+添加。

或者加上 ~/.codex/config.toml 手动:

[mcp_servers.document-mcp]
command = "npx"
args = ["-y", "document-mcp"]

从OpenCode连接

将......添加到...... opencode.json：

{
  "mcp": {
    "document-mcp": {
      "type": "local",
      "command": ["npx", "-y", "document-mcp"]
    }
  }
}

从Claude Desktop连接

添加到 mcpServers 在Claude Desktop的配置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS):

{
  "mcpServers": {
    "document-mcp": {
      "command": "npx",
      "args": ["-y", "document-mcp"]
    }
  }
}

或者，对于针对此存储库而不是发布包的签出的本地开发，点 command 直接在构建的二进制文件中：

{
  "mcpServers": {
    "document-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/document-mcp/dist/bin.js"]
    }
  }
}

从Claude团队/企业（组织）连接

组织管理员可以通过以下方式集中部署MCP服务器配置 服务器托管的设置 管理设置→克劳德代码→克劳德中的管理设置。人工智能控制台)。一个 managed-settings.json document-mcp条目强制组织中所有Claude Code用户之间的连接-不需要每个用户设置。管理员还可以允许/阻止特定的MCP服务器通过 allowedMcpServers/blockedMcpServers 在同一个文件中。

远程传输（HTTP）

Claude Web， Claude Mobile和ChatGPT只接受 远程 （HTTP/SSE） MCP服务器-本地工作室进程无法从浏览器或电话访问。要在这些平台上使用document-mcp，请在HTTP传输后运行它：

npx document-mcp --transport http --port 3000

这就开始了真正的 Streamable HTTP 监听器绑定到 127.0.0.1 （仅环回） --port (默认 3000)，服务于相同的工具集演播室传输寄存器-每个请求一个MCP服务器实例，从相同的构建 createServer() 工厂。 --port 0 向操作系统请求一个空闲端口；在服务请求之前，服务器报告它在stderr上实际绑定的端口。答案是 /mcp 其他地方都是404；来自旧的HTTP+ sse时代的客户机的请求与同一端点上的当前客户机一起透明地提供服务，因此没有分离 --transport sse 选择。

然后添加服务器URL(例如： https://your-host:3000/mcp)作为Claude Web (claude.ai /定制/连接器)或ChatGPT (设置→连接器→高级→启用开发人员模式→创建）. 使用隧道（Cloudflare隧道，ngrok）或使用TLS部署到服务器-这两个平台都需要HTTPS；仅限环回绑定意味着隧道或反向代理必须运行在相同的主机上 document-mcp 本身。

安全注意事项: 这个HTTP监听器没有身份验证，也没有自己的Host/Origin允许列表——任何可以访问它的人都可以调用任何工具，包括读写任意文件系统路径的工具。默认情况下，它是安全的，因为它绑定了环回；无论它为远程访问（隧道、反向代理）做什么，都负责在流量到达此进程之前对调用者进行身份验证。

独立的二进制

每个版本还附加一个Node 单一可执行文件的应用程序 构建Linux (x64和arm64), Windows （x64和arm64）和macOS （Apple Silicon和Intel）到该版本自己的GitHub发布资产-整个服务器及其依赖项嵌入在一个文件中，不需要Node.js安装或 npx 在所有。两者都支持 stdio 和 --transport http 如上所述；点MCP客户的 command 直接下载二进制文件，而不是 npx/node． 从包的标签中下载与您的平台匹配的资源 发布页面 并直接运行它(chmod +x 首先在Linux/macOS上)。

集装箱图片

每个版本还发布了一个多arch (linux/amd64 + linux/arm64)容器映像到GitHub容器注册表，包装相同的独立 --transport http 在最小值上的二进制 distroless base而不是Node安装：

docker run -p 3000:3000 ghcr.io/exadev/document-mcp:VERSION --port 3000

图像总是出现 --transport http 模式- stdio mode是由MCP客户端作为子进程直接执行的，容器在子进程中没有任何作用，并且绑定到子进程 0.0.0.0 在容器内不管 --port,所以 -p <host>:<container> 到达 /mcp 直接。取代 VERSION 使用软件包自己的确切发布版本； latest 还跟踪最新的版本，匹配 document-rest相同的图像。看到 远程传输 此侦听器本身缺乏身份验证。

发展

需要node . js >=20 和规划 11.6.0 (固定通过 packageManager 在 package.json）.

pnpm install
pnpm build         # turbo -> tsdown -> dist/ (ESM + CJS + .d.ts)
pnpm typecheck     # turbo -> tsc --noEmit
pnpm lint          # turbo -> eslint . --fix --cache --max-warnings 0
pnpm test          # turbo -> vitest run --project unit
pnpm test:workers  # turbo -> vitest under the real Cloudflare Workers runtime (workerd) via @cloudflare/vitest-pool-workers, driving createServer() through an in-memory JSON-RPC pair
pnpm test:smoke    # turbo -> tsdown then vitest --project smoke — spawns dist/bin.js as a real subprocess driven over genuine MCP stdio

I / O文档

每个获取或产生文档字节的工具都会经过相同的两个混合形状，这里记录一次，而不是下面每个工具重复记录一次。

输入 （DocumentInput)是一个union：一个文件系统 path (格式是从文件扩展名-推断出来的 docx， pptx， xlsx， odt， odp， ods， odg， odf， md/markdown， pdf)，或内联 bytesBase64 加上一个显式 format （必需的，因为内联字节不携带文件名来进行推断）。每个ODF/OOXML模板和支持宏的变体也读取为其基本格式： .ott/.ots/.otp/.otg/.otf 作为 odt/ods/odp/odg/odf, .dotx/.potx/.xltx (模板)或 .docm/.xlsm/.pptm （宏启用）作为它们的OOXML基——模板与 -template 而启用宏的文件携带 vbaProject 部分此库读取过去而不执行或重新发出。 .odb 工具是唯一的例外 .odb 没有单一的 DocumentFormat 它自己（它是一个数据库前端，而不是文档——表、保存的查询和报告是三个不相关的输出形状），所以它们的 source.path/source.bytesBase64 直接读取字节而不进行格式推断。

输出 （DocumentOutput)，在生成文档的每个工具上都是单个可选项 outputPath：提供它以使工具将结果写入该文件系统路径（然后报告响应） { path, byteLength }）; 省略它以接收内联字节({ bytesBase64, byteLength },标记 large: true 大于5mb（仅供参考，字节永远不会被截断或拒绝）。

工具

参考文献

• documents.js -该服务器公开的库。
• document-outline.js -在document-schema.js的树状结构上使用artifacts -utilities包 DocumentTree 谁的 buildOutline 权力 outline_document。
• document-compute.js -单位类型 MathExpression 评估者的 evaluate() 权力 compute_formula。
• document-cli -同一库上的兄弟CLI/TUI，其工具链被此存储库的scaffold镜像。
• 模型上下文协议 -该服务器实现的协议，通过 @modelcontextprotocol/server。

陷阱

• 运行时依赖项包括 document-operations + documents.js + @modelcontextprotocol/server + @modelcontextprotocol/node + zod 只有; pdf-codec， odf.js, document-schema.js 是devDependencies（仅支持测试）。 @modelcontextprotocol/node 是Node适配器(toNodeHandler) --transport http 监听器用于架桥 @modelcontextprotocol/serverweb标准的 createMcpHandler 在平原上 node:http 服务器-参见 远程传输 以上。每个工具的实际实现——转换/编辑/检查/.odb 中直接定义的逻辑 src/tools/*.ts，包括自己的范围 document-outline.js的 buildOutline/outlineLeafText 和 document-compute.js的 evaluate() -现在住在 document-operations 作为一个 DocumentOperation;这个包自己的 src/tools/*.ts 是薄的 registerOperation() 包装器(src/register-operation.ts)，将每个操作注册为MCP工具，对于其自身错误需要MCP特定浓缩的两个操作(odb_render_report的 OdbReportNotSpecifiedError， odm_to_pdf的 OdmUnresolvedSectionError),一个 mapError 钩。每次运行时到达 pdf-codec/odf.js - - - - - - ProvidedFont/FontSubstitution/describeFontFace/ WinAnsi 取代形状-通过 documents.js中国自己的再出口(通过 document-operations)，因此发布的安装不会直接拉入 pdf-codec/odf.js 依赖。 odf.js 和 document-schema.js 生存在 devDependencies 仅适用于本包自己的测试装置和 compute_formula自己的测试断言(document-schema.js的 assembleTree/ContentDocument); src/test-support/ 被排除在 tsdown 仅构建 src/index.ts 和 src/bin.ts 有没有入口点，所以这些东西都不会运进来 dist/。

贡献

发布、CI和提交消息约定都是工作空间范围的，而不是包本地的——请参阅 monorepo root README 对于释放机制和 CONTRIBUTING.md 对于共享的git钩子和历史约定。工作内 packages/document-mcp/。

许可证

麻省理工学院