Leanzero MCP Doc Processor

MCP文档处理器

用于读取、创建和管理PDF、DOCX和Excel文档的MCP（模型上下文协议）服务器。专为需要使用专业样式、自动分类和智能文档管理处理文档的AI代理而构建。

部分 LeanZero 生态系统。

特性

• 阅读任何文档 --PDF、DOCX和Excel，支持基于图像的PDF的OCR
• 创建精美的文档 --DOCX、Markdown和Excel，具有8种风格预设（包括“类似claude”的现代专业外观），正确呈现项目符号/编号列表、区块引用、超链接、代码块和嵌入在Markdown内容中的表格
• 通用读取和上传桥 --两者皆有 read-doc 并且创建工具接受HTTPS URL+承载身份验证，因此任何Forge应用程序、Cloudflare Worker、AWS Lambda、Express服务器或其他后端都可以插入.doc处理器；你可以随心所欲地构建接收器。CogniRunner的Jira连接桥是参考实现，但模式是通用的。 现有的本地文件调用者不受影响。
• 精简或冗长的输出 -- clientHint 参数允许宿主应用程序请求简洁的面向人类的消息或完整的代理元数据响应。
• 文件DNA --自动应用样式、页眉和页脚的项目级标识系统
• 自动分类 --将文档分为6类（合同、技术、业务、法律、会议、研究），并将其组织到子文件夹中
• 蓝图系统 --从现有文档中提取的结构模板或从重复模式中自动学习的结构模板
• 漂移检测 --通过基于指纹的比较来监控文档随时间的结构变化
• 族系跟踪 --自动来源链，记录哪些源文档通知了每个创建的文档
• 防止重复 --原子文件锁定和基于注册表的标题匹配以防止覆盖
• 文档注册库 --所有已创建文档的可搜索索引，包括类别、标签和标题过滤

工具

服务器通过MCP协议公开13个工具。每个工具都使用 action 或 mode 子操作参数（如适用）。

注： 以前版本的所有旧工具名称(get-doc-summary, get-doc-indepth, get-doc-focused, init-dna, get-dna, evolve-dna, save-memory, delete-memory, learn-blueprint, list-blueprints, watch-document, check-drift, search-registry)被接受为向后兼容的别名。

面向人类的用户界面输出精美(clientHint)

create-doc, create-markdown，以及 create-excel 接受可选 clientHint 参数：

• "interactive" → 响应消息是单行(`Created:

)；像这样健谈的田野 enforcement, styleConfig, lineage, memoriesApplied` 省略。当最终用户直接读取响应时使用此功能（例如CogniRunner在Jira注释中显示结果）。

• "agent" → 用于AI消费的所有元数据的详细响应。这是默认行为。
• "auto" → 对输入形状运行启发式，然后回退到 MCP_CLIENT_TYPE env var，然后 "agent".

集 MCP_CLIENT_TYPE=interactive 在MCP服务器的环境中进行 "auto" 决心在所有通话中进行互动。

通用远程读取桥——从任何经过身份验证的端点读取文件

read-doc 适用于本地文件或由Bearer标头保护的远程HTTPS URL。远程形状是 镜像 下面的上传桥——同样的接线合同，同样的安全保证，同样的通用理念。文档处理器不在乎另一边是什么；任何返回JSON信封的HTTPS端点都可以工作。

参考实施： CogniRunner --伪造web触发器，将Jira附件暴露给本地LM Studio推理，这是一种一次性功能。将其用作您自己桥梁的模板。

决策：何时启动？

远程读取路径发生火灾 if and only if两者都有 url 和 authHeader 通过（以及 filePath 不是）。否则 read-doc 像以前一样在本地路径上工作。 现有的本地文件调用者100%不受影响。

调用形状

{
  "url": "https://your-receiver.example/attachments/123?t=",
  "authHeader": "Bearer ",
  "mode": "summary"
}

电线合同

预期端点将返回HTTP 200 Content-Type: application/json 以及以下主体：

{
  "data":     "",
  "filename": "invoice.pdf",
  "mimeType": "application/pdf",
  "size":     256832
}

read-doc 解码base64有效载荷，将其写入下唯一的每次调用临时目录 os.tmpdir()，运行现有的PDF/DOCX/XLSX提取管道，并在之后清理temp-dir（即使管道抛出）。

安全保障

与上传桥相同——完整列表见下一节。简言之：

• 仅HTTPS，无重定向，4xx上无自动重试，从未记录身份验证标头，在日志中编辑URL令牌，30秒超时，有效载荷大小上限为 READ_DOC_MAX_BYTES （默认值为50 MB）。

构建自己的远程读取源

它与上传接收器相反，因此下一节中相同的Forge/Express框架也适用。对于Forge，而不是向 /rest/api/3/issue/{key}/attachments，从 /rest/api/3/attachment/content/{id} base64将响应编码为上述JSON信封形状。CogniRunner仓库具有完整的模式。

mcp.json 例子

{
  "mcpServers": {
    "doc-processor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-doc-processor/src/index.js"],
      "env": {
        "READ_DOC_MAX_BYTES": "52428800",
        "WRITE_DOC_MAX_BYTES": "26214400",
        "MCP_CLIENT_TYPE": "agent"
      }
    }
  }
}

承载模型的应用程序（CogniRunner、您自己的Forge应用程序、具有额外上下文的Claude Desktop、内部post函数等）注入每次调用 url/authHeader 用于阅读或 uploadUrl/uploadAuthHeader 用于写入模型的提示符。doc处理器永远看不到应用程序，它只是发出有线合约。

通用上传桥——将文件附加到任何经过身份验证的端点

create-doc, create-markdown，以及 create-excel 可以选择上传他们刚刚写入的文件 任何HTTPS端点 它实现了一个小的、定义明确的合同。使用此功能：

• 将生成的文档附加到Jira问题（Atlassian Forge）
• 通过Slack bot lambda将生成的工作簿放入Slack频道
• 通过微型代理将生成的markdown文件推送到GitHub issue
• 将生成的PDF发送到Cloudflare R2/S3签名的URL接收器
• 连接到您的内部文档管理系统

文档处理者不知道也不关心另一边是什么。它只说了一个定义明确的电汇合同；你可以随心所欲地构建接收器。

参考实施： CogniRunner --一个Forge应用程序，它公开了每个问题的一次性上传功能，因此LM Studio模型可以将生成的文档附加回Jira票证。CogniRunner网络触发器约为150行，如果你正在构建自己的接收器，值得一读。

决策：何时启动？

上传桥起火 if and only if两者都有 uploadUrl 和 uploadAuthHeader 他们出现在通话中。否则，该工具的行为与以前完全一样——在本地写入文件，返回路径，响应中没有与上传相关的字段。 现有呼叫者和“正常”代理流100%不受影响。

模型决定每次通话。如果你的应用程序将上传凭据注入模型的上下文（系统提示或每个工具的额外参数），模型就会使用它们。如果你不这样做，模型会忽略这些字段——没有什么可以填写的。

电线合同

请求（文档处理者→ 你的接收器）

POST 
Authorization: 
Content-Type: application/json
Accept: application/json

{
  "data":     "",
  "filename": "q1-2026-strategy.docx",
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "size":     27834
}

成功响应（您的接收器→ 文档处理器）

HTTP 200， Content-Type: application/json:

{
  "success": true,
  "attachment": {
    "id":       "",
    "filename": "q1-2026-strategy.docx",
    "size":     27834,
    "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "content":  ""
  }
}

这 attachment.content 字段是模型交互模式响应消息中显示的内容——它应该是一个可用的URL（例如Jira附件内容URL），以便最终用户获得一个工作链接。

doc处理器允许任何2xx JSON形状——如果 attachment 它使用了整个身体，但建议使用上述严格的形状。

故障响应

文档处理器将这些逐字显示为 uploadError 和 不自动重试:

接收器不得以3xx响应-- fetch 配置了 redirect: "error" 并在任何重定向时中止。

SENDER（文档处理器）提供的安全保证

• 仅限HTTPS。 无https:// URL之前被拒绝 fetch 被称为。
• 没有重定向。 redirect: "error" --接收器必须直接响应。
• 在任何4xx/5xx上都不会自动重试。 一次性语义是端到端的。
• uploadAuthHeader 从未记录 在任何级别。
• 统一资源定位符 ?t= 令牌已被编辑 在日志输出中，只发出主机+路径。
• 没有缓存。 字节、URL、auth标头仅在一次调用期间有效。
• 有效载荷大小有限。 上限由 WRITE_DOC_MAX_BYTES env-var（默认值为25 MB）。
• 60秒超时 在上传获取时。
• 上传失败时保留本地文件 --您的呼叫者可以重试或回退到本地路径。

您的收款人应提供什么

• 具有有效证书的HTTPS端点。
• 如果您使用URL+承载对（按请求造币、使用TTL存储、消费时删除、恒定时间承载比较），则具有一次性功能语义。
• 不要使用3xx——返回4xx/5xx和JSON正文。
• 在接收方验证文件扩展名；不要相信信封 mimeType 该领域具有权威性。
• 审核上传事件日志（调用者、目标、文件名、字节）。

构建自己的接收器

Atlassian Forge网络触发器（CogniRunner模式）

接收JSON信封，验证一次性功能，通过以下方式转发到Jira的附件端点 api.asApp().requestJira().骨架（~50行）：

import api, { route } from "@forge/api";
import storage from "@forge/kvs";
import FormData from "form-data";
import { timingSafeEqual } from "node:crypto";

export async function serveAttachmentUpload(request) {
  const token = request.queryParameters?.t?.[0];
  if (!token) return { statusCode: 404, body: "" };

  const auth = request.headers?.authorization?.[0] || "";
  if (!auth.startsWith("Bearer ")) return { statusCode: 401, body: "" };
  const bearer = auth.slice(7);

  const cap = await storage.get(`uploadcap:${token}`);
  await storage.delete(`uploadcap:${token}`);   // single-use: consume BEFORE any work
  if (!cap || cap.expiresAt  25 * 1024 * 1024) return { statusCode: 413, body: "" };

  const allowed = new Set([".pdf", ".docx", ".xlsx", ".md", ".txt", ".csv"]);
  const ext = (envelope.filename.match(/\.[^.]+$/) || [""])[0].toLowerCase();
  if (!allowed.has(ext)) return { statusCode: 415, body: "" };

  const form = new FormData();
  form.append("file", buf, { filename: envelope.filename, contentType: envelope.mimeType, knownLength: buf.length });

  const jiraResp = await api.asApp().requestJira(
    route`/rest/api/3/issue/${cap.issueKey}/attachments`,
    { method: "POST", body: form, headers: { Accept: "application/json", "X-Atlassian-Token": "no-check" } },
  );
  if (!jiraResp.ok) return { statusCode: 502, body: '{"error":"jira upstream failed"}' };

  const created = (await jiraResp.json())[0];
  return {
    statusCode: 200,
    headers: { "Content-Type": ["application/json"] },
    body: JSON.stringify({
      success: true,
      attachment: {
        id: created.id,
        filename: created.filename,
        size: created.size,
        mimeType: created.mimeType,
        content: created.content,
      },
    }),
  };
}

Express服务器（用于本地测试或非Forge用例）

import express from "express";
import { randomUUID } from "node:crypto";

const app = express();
app.use(express.json({ limit: "30mb" }));

const TOKEN = "test-token-123";
const BEARER = "Bearer test-bearer-456";

app.post("/upload", (req, res) => {
  if (req.query.t !== TOKEN) return res.status(404).end();
  if (req.headers.authorization !== BEARER) return res.status(401).end();

  const { data, filename, mimeType, size } = req.body;
  if (!data) return res.status(400).json({ error: "missing data" });

  const buf = Buffer.from(data, "base64");
  if (buf.length > 25 * 1024 * 1024) return res.status(413).end();

  // Persist the file or forward it somewhere — your call.
  console.log(`Received ${filename} (${mimeType}, ${size} bytes)`);

  res.json({
    success: true,
    attachment: {
      id: randomUUID(),
      filename,
      size: buf.length,
      mimeType,
      content: `https://your-storage.example/files/${filename}`,
    },
  });
});

app.listen(8443);

（对于生产，通过真正的cert-doc处理器在前面终止TLS，拒绝非HTTPS。）

调用shape（您在模型的工具参数中输入的内容）

{
  "title": "Q1 2026 Engineering Strategy",
  "paragraphs": ["..."],
  "uploadUrl": "https://your-receiver.example/upload?t=",
  "uploadAuthHeader": "Bearer ",
  "uploadFilename": "q1-2026-strategy.docx",
  "clientHint": "interactive"
}

这 uploadFilename 是可选的，并覆盖默认值（本地文件的基名）。当防重复自动为本地文件名添加后缀，并且您仍然希望接收器端有一个干净的名称时，这很有用。

响应形状（尝试上传时）

处理程序将四个字段附加到其正常响应中 仅当尝试上传时 （当提供了两个上传参数时）。对于没有上传参数的“正常”代理调用，这些字段都不会出现。

在 clientHint: "interactive" 模式下，响应消息折叠为一行：

• 成功： `Created and uploaded:

→ `

• 失败： `Created locally at

; upload failed: `

快速开始

安装

npm install

MCP配置

添加到您的MCP客户端配置中（例如。， mcp.json, cline_mcp_settings.json或同等）：

{
  "mcpServers": {
    "doc-processor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-doc-processor/src/index.js"],
      "env": {}
    }
  }
}

使用Vision OCR（云）

{
  "mcpServers": {
    "doc-processor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-doc-processor/src/index.js"],
      "env": {
        "Z_AI_API_KEY": "your-api-key"
      }
    }
  }
}

跑步

npm start

服务器使用MCP JSON-RPC协议通过stdio进行通信。它被设计为由MCP客户端启动，而不是交互式运行。

风格预设

八个内置预设控制文档排版、间距和表格格式。通用的默认设置 create-doc 呼叫是 claude-like.

当未指定任何预设时，类别会自动选择适当的预设：

增强型造型系统

增强的样式系统通过 src/tools/styling.js 模块：

颜色常量

该系统包括20多个命名颜色常数，以实现一致的样式：

页面布局辅助工具

标题助手

文本格式辅助工具

列出帮助者

桌子助手

页面设置助手

文件DNA

文件DNA(.document-dna.json)是一个项目级配置文件，它自动在此服务器创建的所有文档中应用一致的样式。

运作原理

1. 初始化 --快跑 dna 行动起来 init 使用您的公司名称、首选样式、页眉和页脚默认值创建DNA文件。
2. 自动应用 --每一个 create-doc 调用会检查DNA，并将其默认值应用于任何未明确提供的字段（页眉、页脚、样式预设）。
3. 使用跟踪 --每次文档创建都会记录类别、样式和任何替代，以构建使用情况配置文件。
4. 进化 --快跑 dna 行动起来 evolve 分析使用模式。当系统检测到强烈趋势时（例如，“80%的文档使用业务预设”），系统会建议突变。使用 apply: true 自动应用顶级建议。
5. 自动学习蓝图 --在演化过程中，会自动检测重复的文档结构并将其保存为蓝图。未来具有匹配模式的文档将获得 blueprintMatch 回复中的建议。

存储器系统

使用 dna 行动起来 save-memory 存储文档首选项（例如，“合同始终使用1英寸的边距”）。记忆保存在DNA文件中，可供AI代理用于上下文。

继承

DNA支持三级继承：系统默认值（硬编码）\<项目DNA(.document-dna.json)\<用户DNA(.document-user.json).缺失的字段会延伸到下一个级别。

环境变量

测试

npm test                    # Markdown format router (custom-assert)
npm run test:read-doc       # read-doc URL-fetch — 14 tests (node:test)
npm run test:schemas        # MCP schema invariants + detect-format E2E — 6 tests (node:test)
npm run test:render         # parseMarkdownToDocx + create-doc round-trip — 15 tests (node:test)
npm run test:upload         # uploadFileToTarget + create-doc upload integration — 18 tests (node:test)
npm run test:all            # Run all five suites in sequence
npm run lint:no-console-log # Fail if any src/ file uses console.log (corrupts MCP stdio)

生成的文件

服务器生成多个配置和数据文件：

.document-dna.json

记录DNA配置文件，其中存储：

• 项目级样式默认值（样式预设、类别、页眉/页脚）
• 使用统计（类别、样式、文档计数）
• 存储系统（保存的文档首选项）
• 自动学习文档结构

此文件由自动管理 dna 工具，不应手动编辑。

.document-blueprints.json

蓝图存储库，存储：

• 提取的文档结构
• 截面模式和要求
• 样式预设关联
• 创建时间戳

蓝图是通过以下方式创建的 blueprint action:'learn' 或在过程中自动学习 dna evolve.

docs/registry.json

文档注册表包含：

• 所有创建的带有元数据的文档
• 类别、标签和描述
• 血统追踪信息
• 创建和更新的时间戳

.document-user.json （可选）

从项目DNA继承的用户级DNA。允许在不影响团队设置的情况下进行个人覆盖。

建筑

mcp-doc-processor/
  src/
    index.js                 # MCP server entry, tool definitions, dispatch
    tools/                   # Tool handlers (one file per tool)
    services/                # Business logic (lineage, drift, blueprints, OCR)
    parsers/                 # File-type parsers (PDF, DOCX, Excel)
    utils/                   # Shared utilities (logger, registry, DNA, categorizer)
  docs/                      # Generated documents (organized by category)
  test/                      # Test suites
  logs/                      # Server logs
  .document-dna.json         # Document DNA configuration
  .document-blueprints.json  # Blueprint repository
  docs/registry.json         # Document registry
  .document-user.json        # Optional user-level DNA

依赖项

许可证

看 许可证 了解详情。