document-rest
一个普通的REST API服务器公开
document-operations文档转换,.odb、元数据和字体工具作为JSON-over-HTTPPOST对于没有MCP客户端和自己的Node运行时（Kotlin/JVM应用程序，Python脚本或任何其他具有HTTP客户端的语言）的调用者来说，路由。
document-rest 不添加自己的转换或编辑逻辑 document-mcp，它是一个调度层 document-operations，唯一的区别是运输方式：1 POST 每个操作路由，而不是一个MCP工具。 document-mcp现有的 --transport http 模式并不能替代它：它在一个单一的接口上使用MCP自己的JSON-RPC协议 /mcp 路径，它仍然需要一个MCP客户端库来调用——这个包是为那些想要普通的请求/响应JSON而没有自己的协议分层的调用者准备的。
开始
直接运行服务器-不需要安装步骤：
npx document-rest --port 3100
这就绑定了一个plain node:http 侦听器到 127.0.0.1 （仅环回） --port (默认 3100； --port 0 向操作系统请求一个空闲端口，绑定后在stderr上报告)。
安全注意事项: 这个监听器没有身份验证，也没有自己的Host/Origin允许列表——任何可以访问它的人都可以调用每个操作，包括读取和写入任意文件系统路径的操作。默认情况下，它是安全的，因为它绑定了环回；无论它为远程访问（隧道，反向代理）提供什么，都负责在流量到达此进程之前对调用者进行身份验证。匹配
document-mcp的自己的--transport http侦听器，因为同样的原因，它带有相同的音符。
独立的二进制
每个版本还附加一个Node 单一可执行文件的应用程序 构建Linux (x64和arm64), Windows （x64和arm64）和macOS （Apple Silicon和Intel）到该版本自己的GitHub发布资产-整个服务器及其依赖项嵌入在一个文件中，不需要Node.js安装或 npx 在所有。对于“没有自己的Node运行时的调用者”这种情况，这个包首先存在，这也删除了最后一个Node依赖：从包的标签上下载与您的平台匹配的资源 发布页面，直接运行(chmod +x 首先在Linux/macOS上)，并且它需要相同的 --port 国旗。
集装箱图片
每个版本还发布了一个多arch (linux/amd64 + linux/arm64)容器映像到GitHub容器注册表，包装相同的独立二进制以上的最小 distroless base而不是Node安装：
docker run -p 3100:3100 ghcr.io/exadev/documents.js:VERSION --port 3100
取代 VERSION 使用软件包自己的确切发布版本(例如。 1.2.0) -与此存储库中其他工件使用的版本固定约定相匹配，此映像永远不会在松散的主要/次要标签下发布，例如 1 或 1.2,虽然 latest 跟踪最新的版本。图像绑定到 0.0.0.0 在容器内不管 --port,所以 -p <host>:<container> 是到达它所需要的一切；请参阅上面关于此侦听器本身没有身份验证的安全说明-发布容器的端口使任何可以到达主机的东西都可以访问它，因此在将其公开到您自己的机器之外之前，请在其前面放置反向代理或防火墙。
API
GET / 列出所有可用的操作：
curl http://127.0.0.1:3100/
{ "operations": [{ "name": "convert_document", "title": "Convert document", "description": "..." }, ...] }
POST /<operationName> 运行一个操作：请求体是JSON，根据该操作自己的输入模式进行验证，响应是JSON { "result": ... } 在成功。每个操作 document-operations 定义可以通过这种方式访问-参见 该软件包自己的README 有关操作名称的完整列表以及每个操作的功能；请求/响应形状与等效MCP工具自己的形状相同 structuredContent，因为这两个调度到完全相同的 run() 函数。
curl -X POST http://127.0.0.1:3100/convert_document \
-H 'content-type: application/json' \
-d '{"source":{"path":"/tmp/report.docx"},"targetFormat":"markdown"}'
错误
| 状态 | 当 |
|---|---|
400 | 请求体不是有效的JSON，操作自己的输入模式失败({ error, issues }从佐德那里 treeifyError)，或者操作本身抛出({ error }抛出的消息)。 |
404 | 该名称不存在任何操作。 |
405 | 一种方法 POST 被用来对付已知的行动路线(GET / 是唯一的例外)。 |
两个操作丰富了他们的 400 身体超越赤裸 { error },反映 document-mcp的自己的 registerOperation mapError 用于相同的两个类型错误的钩子： odb_render_report的 OdbReportNotSpecifiedError 增加了 availableReports (每一个报告的名称 .odb 实际上声明)，和 odm_to_pdf的 OdmUnresolvedSectionError 增加了 hrefs （未能解决的每一章参考）。
入门（开发）
需要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, plus attw --pack
pnpm lint # turbo -> eslint . --fix --cache --max-warnings 0
pnpm test # turbo -> vitest run, driving a real ephemeral-port HTTP server through fetch()
陷阱
- 没有流媒体，没有块上传。
readJsonBody在解析为JSON之前，将整个请求体缓冲到内存中，匹配每个操作自己的混合bytesBase64或者,path输入约定（大型文档最好由filesystem提供）path（由操作本身读取一次，而不是在HTTP上使用base64填充）。 - 客户端断开连接时中止。 每个请求都有自己的请求
AbortSignal，连接到底层IncomingMessage的close事件（节点：http携带no）AbortSignal它自己的)-在转换过程中断开连接的客户端会导致操作自己的信号感知工作(例如；convert_document（如页面边界取消）停止在下一个检查点，而不是运行到不再侦听的调用者完成。
贡献
发布、CI和提交消息约定都是工作空间范围的，而不是包本地的——请参阅 monorepo root README 对于释放机制和 CONTRIBUTING.md 对于共享的git钩子和历史约定。工作内 packages/document-rest/。
许可证
麻省理工学院