MCP Doc Processor

01What do I need before I start?

Node 20 or newer, git, about 750 MB of disk, and five minutes. No API key, no account, no LeanZero anything — the server is MIT-licensed and runs entirely on your machine.

MCP Doc Processor is a Node.js program that speaks the Model Context Protocol over stdin/stdout. Your AI client (Claude Code, Claude Desktop, LM Studio, Cursor, Cline, Qwen Code — anything that reads an mcp.json) launches it as a child process and talks JSON-RPC to it. That is the whole deployment model for the local case: there is no daemon to install, no port to open, and nothing listening on the network.

Requirements

Windows, macOS and Linux all work. The examples below use macOS/Linux paths; on Windows use the same commands in PowerShell and write paths as C:\\Users\\you\\... with doubled backslashes inside JSON.

02How do I install it?

Clone, install, note the path — then prove it works before you touch a client config.

The five minutes

1. 1Clone the repo. git clone https://github.com/leanzero-srl/leanzero-mcp-doc-processor.git then cd leanzero-mcp-doc-processor. The repository is public, so no GitHub account or token is needed.
2. 2Install the dependencies. npm install. This pulls @modelcontextprotocol/sdk, docx, xlsx-js-style, pdf-parse, mammoth, pptxgenjs, marked, jszip and puppeteer. Puppeteer downloads Chrome into ~/.cache/puppeteer on install — that is the slow part and roughly 565 MB of the total, and it is what renders create-pdf output.
3. 3Note the absolute path. Run pwd (macOS/Linux) or cd (Windows) and copy the result. Every client config below needs the absolute path to src/index.js; a relative path will not work because the client launches the process from its own working directory.
4. 4Prove the server starts. Run the handshake in the next section. Do not skip it — a client that silently fails to launch the server looks exactly like a client that has no tools.

The whole install

git clone https://github.com/leanzero-srl/leanzero-mcp-doc-processor.git
cd leanzero-mcp-doc-processor
npm install
pwd    # copy this — you need the absolute path below

There is no build step. The server is plain ESM JavaScript and runs from source — src/index.js is the entry point for the stdio transport, src/server.js for the HTTP one. Nothing is transpiled or bundled, which means you can read and edit any file in the repo and restart your client to pick it up.

03How do I prove the install actually works?

Send a real MCP handshake down the pipe and count the tools. If you get 17 back, the server is genuinely working — before any client is involved.

MCP over stdio is line-delimited JSON-RPC. That means you can drive the server from a shell with echo and a pipe, with no client in the loop. This is the single most useful debugging trick with this server, and it is worth doing once now so you know what a healthy response looks like.

Handshake and list the tools

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node src/index.js 2>/dev/null \
  | tail -1 | python3 -c 'import json,sys; print(len(json.load(sys.stdin)["result"]["tools"]), "tools")'

What each failure means

• `Cannot find module` — you ran the probe from the wrong directory, or npm install did not finish. cd into the repo root and re-run npm install.
• `SyntaxError: Unexpected token` / `await is only valid` — your Node is older than 20. Check with node --version and upgrade.
• Nothing at all, hangs forever — the server is waiting for more input, which is correct behaviour. The printf above closes the pipe; if you typed the JSON by hand, press Ctrl-D.
• Output is empty but exit code is 0 — you redirected the wrong stream. The protocol is on stdout, logs are on stderr; 2>/dev/null above is what keeps them apart.

04Where do the files it creates actually land?

By default, in the working directory the client launched the server from — which for a coding agent is your open project. DOC_OUTPUT_DIR pins it somewhere fixed instead.

This is the question people get wrong most often, so it is worth being precise. src/tools/utils.js resolves the output root in three steps, first match wins:

1. 1A per-request override (X-Output-Dir header) — only exists on the HTTP transport, and it is sandboxed under a server-side base directory. A remote tenant can organise files into subfolders but cannot write anywhere it likes on the host.
2. 2The `DOC_OUTPUT_DIR` environment variable — your own machine, your own choice, not sandboxed. Set this in the env block of your client config.
3. 3`process.cwd()` — the default. For a stdio server launched by a coding agent, that is the workspace you opened the agent in, so generated documents appear right next to the code you are working on.

Inside the output root, the server enforces a docs/ folder and sorts documents into one of six category subfolders (contracts, technical, business, legal, meeting, research) chosen by the auto-categoriser in src/utils/categorizer.js. Pass enforceDocsFolder: false on a create call to opt out and write exactly where you asked.

Pin the output directory

{
  "mcpServers": {
    "doc-processor": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js"],
      "env": {
        "DOC_OUTPUT_DIR": "/Users/you/Documents/ai-documents"
      }
    }
  }
}

05How do I turn on OCR for scanned PDFs?

One environment variable, and you choose the provider: a cloud vision model, or a local one in LM Studio so no page image ever leaves your machine.

A PDF that was produced by a word processor contains a text layer, and pdf-parse reads it with no AI and no network. A PDF that was produced by a scanner is a bag of images: there is nothing to extract, and the only way to read it is to look at it. That is what the vision path in src/services/vision-service.js is for, and it is the only part of this server that ever calls out to a model.

Vision environment variables

Run OCR locally, with no cloud key at all

The vision client posts an OpenAI-shaped chat/completions request to Z_AI_BASE_URL. Any server that speaks that shape works — including LM Studio on your own machine. Load a vision-capable model in LM Studio, start its local server, and point the MCP at it. Page images then never leave the machine.

Local vision via LM Studio

{
  "mcpServers": {
    "doc-processor": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://localhost:1234/v1/",
        "Z_AI_VISION_MODEL": "<the model id LM Studio shows>",
        "Z_AI_API_KEY": "lm-studio"
      }
    }
  }
}

To be precise about what leaves the machine: OCR never touches the web-search MCP, but it is not automatically local either — its one outbound call goes to Z_AI_BASE_URL, which is a cloud endpoint unless you point it at LM Studio as shown above. The other outbound path is fact-check, which calls the sibling web-search MCP — see the tools part.

06How do I add it to Claude Code?

One command. Pick the scope deliberately — that choice decides whether the server follows you between projects or stays with this one.

Add it

claude mcp add doc-processor --scope user -- node /ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js

Everything after -- is the command Claude Code will run. The -- is required: without it the CLI tries to parse node as its own argument.

Which scope?

With environment variables

claude mcp add doc-processor --scope user \
  -e DOC_OUTPUT_DIR=/Users/you/Documents/ai-documents \
  -e Z_AI_API_KEY=sk-... \
  -- node /ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js

Verify it, do not assume it

• Run claude mcp list — the server should be listed and marked connected.
• In a session, ask for the tool list, or just say "read this PDF" with a real path. A server that registered but crashes on launch shows up as connected-then-gone.
• claude mcp remove doc-processor undoes it; re-add with a corrected path.

07How do I add it to Claude Desktop?

Edit one JSON file and restart the app. The file location differs per OS, and "restart" means quit, not close the window.

Where the config lives

claude_desktop_config.json

{
  "mcpServers": {
    "doc-processor": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js"],
      "env": {
        "DOC_OUTPUT_DIR": "/Users/you/Documents/ai-documents"
      }
    }
  }
}

1. 1Create the file if it does not exist. If it does, merge your entry into the existing mcpServers object rather than replacing the file — you will otherwise silently remove every other server you had.
2. 2Use the absolute path to src/index.js. Claude Desktop launches from its own working directory, so ./src/index.js resolves to somewhere inside the app bundle.
3. 3Fully quit Claude Desktop (Cmd-Q on macOS, right-click → Quit in the tray on Windows) and reopen it. Closing the window does not reload the config.
4. 4Open the MCP/tools indicator in the composer. The doc-processor tools should be listed.

08How do I add it to LM Studio?

LM Studio reads the same mcp.json shape. This is also the path CogniRunner and any other Forge app depend on, so get it right once and it serves both.

1. 1In LM Studio, open Program → Edit mcp.json (in older builds: the plugin/integrations panel).
2. 2Add the doc-processor entry below, with the absolute path to src/index.js.
3. 3Save. LM Studio reloads MCP servers on save — no restart needed.
4. 4Load a model that supports tool calling, then ask it to read a file. If the model has no tool support, the server is connected but nothing will ever call it.

LM Studio mcp.json

{
  "mcpServers": {
    "doc-processor": {
      "command": "/usr/local/bin/node",
      "args": ["/ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js"],
      "env": {
        "DOC_OUTPUT_DIR": "/Users/you/Documents/ai-documents",
        "MCP_CLIENT_TYPE": "interactive"
      }
    }
  }
}

MCP_CLIENT_TYPE=interactive is worth setting here. It makes the create tools answer with a single line (Created: <path>) instead of the full metadata envelope. A human reading the model's reply wants the former; an agent parsing it wants the latter. See the clientHint section in the tools part for the per-call override.

09How do I add it to Cursor, Cline, Roo Code, or Qwen Code?

They all read the same mcpServers object. Only the file path differs, and none of them need anything the others do not.

The block, unchanged, for all of them

{
  "mcpServers": {
    "doc-processor": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js"],
      "env": {}
    }
  }
}

10The server does not show up. What now?

Five causes account for almost every case, and each has a test that distinguishes it from the others in one command.

Work down this list — do not skip step 1

1. 1Does the server start at all? Run the handshake probe from "How do I prove the install actually works?". If that fails, the problem is the install, not the client, and no amount of config editing will help.
2. 2Is `node` findable by the client? Replace "command": "node" with the absolute path from which node. GUI apps do not inherit your shell PATH. This is the top cause on macOS.
3. 3Is the path to `index.js` absolute and correct? node /the/exact/path/from/your/config should hang (waiting for input), not print Cannot find module. Ctrl-C to exit.
4. 4Is the JSON valid? A trailing comma silently disables the whole config in most clients. python3 -m json.tool < your-config.json will tell you in one line.
5. 5Did you actually restart? Claude Desktop and Cursor need a full quit. LM Studio reloads on save. Claude Code re-reads on the next session.

Read the server's own logs

# The server writes logs/server.log into the directory it was LAUNCHED from
# (process.cwd()) — for a stdio server that is your client's working directory,
# NOT the repo. For a coding agent it is the project you opened.
tail -f /THE/DIRECTORY/YOUR/CLIENT/LAUNCHED/FROM/logs/server.log

# Claude Desktop keeps per-server logs of its own:
tail -f ~/Library/Logs/Claude/mcp-server-doc-processor.log   # macOS

11Do I want stdio or HTTP?

stdio if the AI runs on the same machine as your files. HTTP if something remote — a Forge app, a phone, claude.ai — needs to reach it. Most people want stdio and stop reading here.

The rest of this part is the real, working recipe from the Mac Studio that serves the hosted demo on this site: a launchd job, secrets in a mode-0600 env file outside the repo, and one Tailscale Funnel publishing both MCP servers on path prefixes. Nothing here is aspirational — it is the running configuration, with the secrets removed.

12How do I start the HTTP transport?

node src/server.js, bound to localhost, with a handful of environment variables. Confirm it with /healthz before you put anything in front of it.

Start it by hand first

cd /path/to/leanzero-mcp-doc-processor
PORT=10000 \
BIND_HOST=127.0.0.1 \
DATA_DIR="$HOME/Library/Application Support/mcp-doc-processor" \
DOC_PROCESSOR_ADMIN_TOKEN="$(openssl rand -base64 32)" \
node src/server.js

# In another terminal:
curl -s localhost:10000/healthz     # -> {"ok":true,...}

Server environment variables

Endpoints it exposes

Three request headers are accepted alongside Authorization: X-ZAI-Key (the caller's own vision key, used for that request only and never stored), X-Output-Dir (a sandboxed subfolder name under CLIENT_OUTPUT_BASE), and the standard Mcp-Session-Id / Mcp-Protocol-Version. Each also has a query-string form (?zai_key=, ?output_dir=) for clients that cannot set headers.

13How do I keep it running on macOS? (launchd)

A LaunchAgent that runs a wrapper script, which sources a mode-0600 env file and execs node. Three files — and the reason for three rather than one is that secrets must not live in the plist.

The repo ships a plist template at deploy/com.leanzero.docprocessor.plist that puts the environment inline. That works, but it means secrets sit in a file launchd reads and launchctl print can echo. The setup actually running on our Mac Studio splits it in three, and that is the version worth copying.

The three files

1. 1`~/Library/Application Support/mcp-doc-processor/server.env` — every variable, KEY=value, one per line. chmod 600. This is the only file that holds secrets, and it lives outside the repo so it can never be committed.
2. 2`~/Library/Application Support/mcp-doc-processor/run-http-server.sh` — sources that env file with set -a, then execs node. chmod +x. The exec matters: it keeps node as the job's own PID so launchd's KeepAlive supervises the real process rather than a shell that has already exited.
3. 3`~/Library/LaunchAgents/com.user.mcp-doc-processor.plist` — points at the wrapper, sets RunAtLoad and KeepAlive, and sends both streams to one log file. No secrets in it at all.

run-http-server.sh

#!/bin/bash
# Sources server.env so secrets stay out of the launchd plist, then execs node.
# launchd's KeepAlive restarts this on crash; `exec` keeps node as the job's PID.
set -euo pipefail

APP_DIR="$HOME/Library/Application Support/mcp-doc-processor"
REPO="/Users/you/Projects/leanzero-mcp-doc-processor"

set -a
# shellcheck disable=SC1091
source "$APP_DIR/server.env"
set +a

exec /usr/local/bin/node "$REPO/src/server.js"

~/Library/LaunchAgents/com.user.mcp-doc-processor.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.mcp-doc-processor</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/you/Library/Application Support/mcp-doc-processor/run-http-server.sh</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/Users/you/Projects/leanzero-mcp-doc-processor</string>

    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/you/Library/Logs/mcp-doc-processor.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/you/Library/Logs/mcp-doc-processor.log</string>
</dict>
</plist>

server.env

PORT=10000
BIND_HOST=127.0.0.1
PUBLIC_HOST=your-host.tailXXXX.ts.net:10000
ALLOWED_HOSTS=your-host.tailXXXX.ts.net,your-host.tailXXXX.ts.net:443
DATA_DIR="/Users/you/Library/Application Support/mcp-doc-processor"
TENANT_RATE_LIMIT=60
Z_AI_MODE=ZAI
DOC_PROCESSOR_ADMIN_TOKEN=<openssl rand -base64 32>

Install, start, watch

# The directory does not exist yet — create it before writing the two files into it.
mkdir -p ~/Library/Application\ Support/mcp-doc-processor

chmod 600 ~/Library/Application\ Support/mcp-doc-processor/server.env
chmod +x  ~/Library/Application\ Support/mcp-doc-processor/run-http-server.sh

launchctl load -w ~/Library/LaunchAgents/com.user.mcp-doc-processor.plist
launchctl list | grep mcp-doc-processor      # PID, then 0 = running clean
curl -s localhost:10000/healthz

tail -f ~/Library/Logs/mcp-doc-processor.log

14How do I keep it running on Linux? (systemd)

The same three-file shape: a unit, an EnvironmentFile at mode 0600, and a hardened service section.

~/.config/systemd/user/mcp-doc-processor.service

[Unit]
Description=MCP Doc Processor (HTTP transport)
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/Projects/leanzero-mcp-doc-processor
EnvironmentFile=%h/.config/mcp-doc-processor/server.env
ExecStart=/usr/bin/node %h/Projects/leanzero-mcp-doc-processor/src/server.js
Restart=always
RestartSec=3

# Hardening. ReadWritePaths must cover EVERY directory the server writes:
#   1. DATA_DIR            — tenants.json, OAuth stores, client output
#   2. <WorkingDirectory>/logs — the server writes logs/server.log into its cwd
#   3. DOC_OUTPUT_DIR      — set it explicitly in server.env, or created
#                            documents land in the repo's docs/ folder
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=%h/.local/share/mcp-doc-processor
ReadWritePaths=%h/Projects/leanzero-mcp-doc-processor/logs

[Install]
WantedBy=default.target

Install and verify

# Create EVERY directory the unit references, including the repo's logs/ —
# systemd refuses to start a unit whose ReadWritePaths target does not exist.
# And set a LINUX DATA_DIR in server.env: the macOS example above uses an
# "Application Support" path, and left unset DATA_DIR falls back to the working
# directory, putting tenants.json in the repo where a git clean can delete it.
#   DATA_DIR=/home/you/.local/share/mcp-doc-processor
#   DOC_OUTPUT_DIR=/home/you/.local/share/mcp-doc-processor
mkdir -p ~/.config/mcp-doc-processor \
         ~/.local/share/mcp-doc-processor \
         ~/Projects/leanzero-mcp-doc-processor/logs

# ...write server.env into ~/.config/mcp-doc-processor/ first, then:
chmod 600 ~/.config/mcp-doc-processor/server.env
systemctl --user daemon-reload
systemctl --user enable --now mcp-doc-processor
systemctl --user status mcp-doc-processor
journalctl --user -u mcp-doc-processor -f

curl -s localhost:10000/healthz

15How do I publish it over HTTPS without opening a port?

Tailscale Funnel. It gives you a real certificate on a real hostname with no port forwarding, no dynamic DNS and no router configuration — and one funnel can carry both MCP servers on path prefixes.

The server binds to 127.0.0.1. Funnel terminates TLS at Tailscale's edge and proxies to that loopback port. Your firewall stays closed, your home IP stays unpublished, and the certificate is issued and renewed for you.

Set it up

1. 1Install and join. brew install tailscale (or your distro's package), sudo tailscale up. Then tailscale status and note the MagicDNS name, e.g. your-host.tailXXXX.ts.net.
2. 2Enable MagicDNS and HTTPS certificates in the Tailscale admin console under DNS. Funnel cannot issue a certificate without them.
3. 3Grant the funnel attribute in Access Controls: "nodeAttrs": [{ "target": ["autogroup:member"], "attr": ["funnel"] }].
4. 4Publish the port. tailscale funnel --bg --set-path=/docproc 10000. The service is now reachable at https://your-host.tailXXXX.ts.net/docproc/mcp.
5. 5Set `PUBLIC_HOST` and `ALLOWED_HOSTS` to match and restart the service, or DNS-rebinding protection will reject every request with a Host mismatch.
6. 6Verify from off-network — a phone on cellular, not the LAN. curl -s https://your-host.tailXXXX.ts.net/docproc/healthz.

One funnel, both MCP servers

# This is the live routing on our Mac Studio.
tailscale funnel --bg --set-path=/docproc   10000   # doc-processor
tailscale funnel --bg --set-path=/websearch 8443    # web-search
tailscale funnel --bg --set-path=/lmstudio  1234    # LM Studio, for the Forge bridge

tailscale funnel status
# https://your-host.tailXXXX.ts.net (Funnel on)
# |-- /docproc   proxy http://127.0.0.1:10000
# |-- /lmstudio  proxy http://127.0.0.1:1234
# |-- /websearch proxy http://127.0.0.1:8443

16How do I issue and revoke access tokens?

One bearer per consumer, minted over a localhost-only admin API, stored as an argon2 hash. Shown once — there is no way to read one back.

Mint, list, rotate, revoke

ADMIN=<DOC_PROCESSOR_ADMIN_TOKEN>

# Mint — the bearer is returned ONCE and never stored in plaintext.
curl -s -X POST localhost:10000/v1/admin/tenants \
  -H "Authorization: Bearer $ADMIN" -H "Content-Type: application/json" \
  -d '{"displayName":"alice-laptop"}'

curl -s            localhost:10000/v1/admin/tenants                 -H "Authorization: Bearer $ADMIN"
curl -s -X POST    localhost:10000/v1/admin/tenants/<id>/rotate     -H "Authorization: Bearer $ADMIN"
curl -s -X DELETE  localhost:10000/v1/admin/tenants/<id>            -H "Authorization: Bearer $ADMIN"

How this is designed to fail safe

• The admin API refuses proxied requests. Anything arriving with an X-Forwarded-For header — i.e. through the funnel — gets a 404, even with a correct admin token. You mint tokens by being on the machine. ALLOW_ADMIN_OVER_FUNNEL=true lifts that, and you should not.
• Tokens are argon2 hashes in `tenants.json`. A stolen copy of that file does not yield working bearers.
• One token per consumer, not one shared token. Revoking a laptop then costs one DELETE instead of a rotation everybody has to chase.
• Rate limiting is per tenant (TENANT_RATE_LIMIT), so one noisy client cannot exhaust the server for the others.

17What must I check before this faces the internet?

Nine things. They take ten minutes together and every one of them has bitten somebody.

1. 1`BIND_HOST=127.0.0.1`. Confirm with lsof -nP -iTCP -sTCP:LISTEN | grep 10000 — you want 127.0.0.1:10000, not *:10000.
2. 2`PUBLIC_HOST` set, and matching what clients actually send. Test through the funnel, not from localhost.
3. 3A strong `DOC_PROCESSOR_ADMIN_TOKEN`. openssl rand -base64 32. Not a password you have used elsewhere.
4. 4`ALLOW_ADMIN_OVER_FUNNEL` unset. Verify: curl https://your-host…/docproc/v1/admin/tenants -H "Authorization: Bearer $ADMIN" must return 404.
5. 5`chmod 600` on `server.env`, `tenants.json`, and the OAuth stores. ls -l and read the mode; the server writes them 0600 but a hand-edit or a restore from backup can widen them.
6. 6`DATA_DIR` outside the repo. A git clean -xfd in the repo must not be able to delete your tenant database.
7. 7`TENANT_RATE_LIMIT` set to something you can actually serve. 60/min per tenant is our number for a Mac Studio.
8. 8Log rotation. KeepAlive plus an unrotated log file fills a disk eventually. newsyslog on macOS, logrotate on Linux.
9. 9Decide about OCR keys. Leaving Z_AI_API_KEY unset makes the server keyless — each caller brings their own via X-ZAI-Key, used for that request and never persisted. That is the posture we run, and it means a compromise of the host leaks no vision credential.

18Which tool do I call?

Seventeen tools, four jobs: read something, make something, change something, or keep track of what you made. This table is the whole decision.

19How do I read a document?

read-doc with the mode that matches the question. Using indepth when you needed summary burns context for nothing; using summary before an edit loses the structure the edit depends on.

The three modes

The three shapes

{ "filePath": "/path/to/contract.pdf", "mode": "summary" }

{ "filePath": "/path/to/contract.pdf", "mode": "indepth" }

{ "filePath": "/path/to/contract.pdf",
  "mode": "focused",
  "userQuery": "What are the payment terms and the notice period?" }

What it can open

• PDF — text layer via pdf-parse; image-only pages via the vision path when a key is configured. A scanned PDF with no vision key returns empty text, not an error, so check the result rather than assuming.
• DOCX — mammoth for text, plus direct XML reading for structure, headers and footers.
• XLSX / XLS — every sheet, with cell values and formulas.
• PPTX — a per-slide transcript: titles, bullets, and speaker notes, plus the slide count.

Reading a file that is not on this machine

read-doc also takes url + authHeader instead of filePath. The endpoint must return { data: <base64>, filename, mimeType, size } as JSON. The server decodes it into a per-call temp directory, runs the normal pipeline, and deletes the temp directory afterwards even if parsing throws. This is how CogniRunner hands a Jira attachment to the MCP without the file ever touching a shared disk — the wire contract is documented in the code part.

20How do I create a document that does not look AI-generated?

Write the body as markdown, pick a style preset, and let Document DNA supply the header, footer and house style. The difference between a usable deliverable and an obvious one is almost entirely here.

1. 1Let `detect-format` choose the format if the user did not name one. It weighs the verbs ("print", "sign", "send to the client" → PDF; "editable", "draft", "template" → DOCX; "README", "spec", "for the repo" → Markdown; "budget", "tracker", "dataset" → Excel) and returns { format, suggestedTool, stylePreset, category, docType, confidence, reason } that you pass straight through.
2. 2Write the body as markdown in `content`. Headings, bullets, numbered lists, blockquotes, links, code blocks and pipe tables are all parsed and rendered as native document features — real Word tables, real numbered lists. A wall of plain text renders as a wall of plain text.
3. 3Give it a specific title. The rejected set is literal: Untitled, Untitled Document, New Document, Document, Doc, File, Output, Temp, Tmp, New File, Unnamed, No Title. Anything else passes — Report is accepted, so a vague-but-unlisted title still gets through. The title becomes the H1 and the registry key.
4. 4Pick a `stylePreset` — or leave it and let DNA decide. The default is claude-like.
5. 5Use `dryRun: true` first on anything long. It returns the full preview and the formatting-quality score without writing a file.

A real create-doc call

{
  "title": "Q3 Platform Migration Readiness Review",
  "stylePreset": "professional",
  "category": "technical",
  "tags": ["migration", "q3"],
  "content": "## Summary\n\nThe migration is **on track** for the 14 November window.\n\n## Open risks\n\n| Risk | Owner | Status |\n|---|---|---|\n| Attachment volume | Platform | Mitigated |\n| SSO cutover | Identity | Open |\n\n## Next steps\n\n1. Freeze schema changes on 1 November\n2. Dry-run the cutover on staging\n3. Confirm the rollback window with Ops",
  "header": { "text": "Acme Corp — Internal" },
  "footer": { "text": "Confidential", "pageNumbers": true }
}

The eight style presets

Things worth knowing before you are surprised by them

• Duplicate titles are refused by default. You get { duplicate: true, existingPath } back and should switch to edit-doc. Pass preventDuplicates: false to override.
• Every response carries `formattingQuality` and sometimes `formatSuggestion`. If formatSuggestion is set, the content genuinely suits a different format — heed it rather than shipping a spreadsheet as a Word file.
• `create-excel` takes formulas. [["Month","Units","Price","Revenue"],["Apr",120,9.99,"=B2*C2"]] produces a live formula, not a string.
• `create-markdown` can emit a table of contents and YAML frontmatter. toc: true builds anchor links from the H2/H3s; frontmatter: { title, date, tags } feeds Hugo, Jekyll or Astro.
• `create-pptx` builds one slide per `## ` heading, with bullets, native slide tables, native charts and speaker notes. It opens in PowerPoint, Keynote and Google Slides.

21How do I edit a document without wrecking it?

edit-doc in append mode patches the DOCX XML directly, so fonts, headers, footers and images survive. replace does not — know which one you asked for.

The safe edit sequence

1. 1read-doc with mode: "indepth" — know exactly what is in there.
2. 2edit-doc with action: "append" and the smallest change that does the job.
3. 3read-doc again on the result if the edit mattered. The tools report success on a write; they do not assert that the document still reads correctly.

22How do I make every document look like ours?

Document DNA is a project-level file that supplies the company name, header, footer and style preset to every create call, so nobody has to remember them. It also learns.

1. 1Initialise once per project. dna with action: "init" and your company name, preferred preset, header and footer defaults. It writes .document-dna.json in the output root.
2. 2Then do nothing. Every create-doc / create-pdf / create-markdown / create-excel call reads DNA and fills in any field you did not pass explicitly. An explicit argument always wins.
3. 3Save preferences as memories. dna save-memory with something like "Always use 1-inch margins for contracts". Memories persist in the DNA file and are surfaced to the agent as context.
4. 4Let it evolve. dna evolve analyses what you have actually been producing and proposes mutations — "80% of your documents use the business preset". Pass apply: true to accept the top suggestion.

DNA inherits across three levels, each overriding the one before: hardcoded system defaults, then project DNA (.document-dna.json), then user DNA (.document-user.json). A field missing at one level falls through to the next, so a personal preference can override a project default without editing the shared file.

What DNA evolution also produces

23How do I fact-check a document against the live web?

fact-check extracts the document's claims, sends each one to the sibling web-search MCP, and reports what the live web says — with sources. It is the only tool whose core function is a call to another service.

This is a cross-MCP tool. src/services/web-search-client.js calls the MCP Web Search server per claim, gathers cited sources, and can write the whole verification out as a report document. It is the reason the two servers are documented as a pair rather than as two unrelated projects.

1. 1Set up MCP Web Search as a reachable HTTP instance. fact-check connects over Streamable HTTP only — src/services/web-search-client.js constructs no stdio transport at all, so a local stdio build of web-search cannot be used here.
2. 2Set all three of WEB_SEARCH_MCP_URL (its /mcp URL), WEB_SEARCH_BEARER (a tenant bearer for it) and SERPER_API_KEY (your own Serper key). The bearer and the Serper key are both mandatory — the tool returns webSearchBearer is required / serperKey is required and does nothing without them. Both can also be passed per call as webSearchBearer and serperKey. With WEB_SEARCH_MCP_URL unset the client falls back to LeanZero's hosted web-search endpoint.
3. 3Call fact-check with the document path. Each extracted claim is searched, and the result carries the sources it found.
4. 4Optionally have it write a verification report — it goes through the normal create pipeline, so it inherits your DNA and style.

24What is in the repo, file by file?

About 18,000 lines of plain ESM JavaScript in 59 files, with no build step. Two entry points share one tool registry; everything else is a leaf.

The tree

leanzero-mcp-doc-processor/
├─ src/
│  ├─ index.js            # ENTRY: stdio transport. ~35 lines.
│  ├─ server.js           # ENTRY: Express HTTP transport, auth, rate limit.
│  ├─ tool-registry.js    # The 17 schemas + the dispatch table. Start here.
│  ├─ auth.js             # argon2 tenant bearers, tenants.json
│  ├─ oauth/              # OAuth 2.1 (PKCE + dynamic client registration)
│  ├─ tools/              # One file per tool + shared helpers
│  ├─ services/           # Business logic: DNA, lineage, drift, OCR, routing
│  ├─ parsers/            # pdf / docx / excel / pptx readers
│  └─ utils/              # logger, registry, categoriser, request context
├─ test/                  # 14 suites, node:test
├─ deploy/                # launchd plist template + runbook
└─ docs/                  # Generated output + registry.json

The files that carry the weight

25What actually happens on one tool call?

Nine steps from JSON-RPC frame to file on disk. Knowing this sequence is what turns a confusing failure into an obvious one.

1. 1Transport receives the frame. stdio reads a line from stdin; HTTP takes a POST /mcp body after mcpAuth (in src/server.js) has resolved a tenant — trying an OAuth access token first when ISSUER_URL is set, then falling back to requireBearer in src/auth.js, which verifies the bearer against the argon2 hash in tenants.json — and the per-tenant rate limiter has allowed it.
2. 2Request context is established (HTTP only). X-ZAI-Key and X-Output-Dir are pulled off the request and stored in the AsyncLocalStorage in request-context.js, so nothing downstream needs them passed explicitly.
3. 3The SDK routes CallToolRequestSchema to the handler registered in tool-registry.js.
4. 4The client profile resolves. client-profile.js maps the clientInfo.name from the handshake to a cohort, which decides whether the response is chatty or terse when clientHint is auto.
5. 5Arguments are validated against the tool's JSON schema by the SDK; a mismatch comes back as a protocol error, not a crash.
6. 6Document DNA is merged in for create calls: system defaults, then .document-dna.json, then .document-user.json, with anything explicit in the call winning over all three.
7. 7The output path is resolved through getOutputRoot() — the three-step precedence described in the setup part — then run through the docs/<category>/ enforcement and the duplicate check.
8. 8The work happens. A parser reads, or docx / pptxgenjs / xlsx-js-style / headless Chromium writes.
9. 9The registry is updated, lineage is recorded, and the response is shaped by clientHint. If uploadUrl was supplied, the file is POSTed to it before the response is returned.

26How do the read and upload bridges work?

Two mirror-image HTTPS contracts that let the server read from, and write to, any authenticated endpoint you control. This is the extension point that makes it useful inside someone else's platform.

doc-processor does not know what CogniRunner is. It knows one JSON envelope in each direction. Anything that speaks that envelope — a Forge web trigger, a Cloudflare Worker, a Lambda, an Express route — plugs in. CogniRunner is the reference implementation, not a special case.

Reading: url + authHeader on read-doc

The remote path fires only when both url and authHeader are present and filePath is not. Existing local callers are completely unaffected. Your endpoint returns HTTP 200 application/json with { data: "<base64>", filename, mimeType, size }. The server decodes into a unique per-call temp directory under os.tmpdir(), runs the normal extraction pipeline, and removes the temp directory in a finally — including when the pipeline throws.

Uploading: uploadUrl + uploadAuthHeader on any create tool

POST <uploadUrl>
Authorization: <uploadAuthHeader>
Content-Type: application/json

{ "data": "<base64 file bytes>",
  "filename": "q3-review.docx",
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "size": 27834 }

--> 200 application/json
{ "success": true,
  "attachment": { "id": "...", "filename": "...", "size": 27834,
                  "mimeType": "...", "content": "<user-visible URL>" } }

Failure statuses, surfaced verbatim as uploadError

Guarantees the sender makes — worth knowing before you build a receiver

• HTTPS only. A non-https:// URL is rejected before fetch is called.
• No redirects. redirect: "error". Your receiver must answer directly — a 3xx aborts the call.
• No auto-retry on any 4xx or 5xx. Single-use capability semantics are honoured end to end, so a one-shot token really is one shot.
• The auth header is never logged, at any level, and the URL's ?t= token is redacted — only host and path reach the log.
• Nothing is cached. Bytes, URL and auth header live for the duration of one call.
• Sizes are bounded. READ_DOC_MAX_BYTES (default 50 MB) on the way in, WRITE_DOC_MAX_BYTES (default 25 MB) on the way out. The write cap is half the read cap because Forge web-trigger payload limits are tighter.
• Timeouts: 30 s on the remote read, 60 s on the upload.
• The local file survives a failed upload, so your caller can retry or fall back to the path.

27How do I add my own tool?

Six steps across four files, no framework. The hardest part is writing a description the model will actually route on correctly.

1. 1Write the handler. A new file in src/tools/, exporting one async function that takes the validated arguments object and returns a result object. Import helpers from src/tools/utils.js — getOutputRoot(), enforceDocsFolder() — rather than reimplementing path handling.
2. 2Import it in `src/tool-registry.js` alongside the others at the top.
3. 3Add the schema to the tools array: name, a long description, and an inputSchema with explicit enums wherever a value is constrained.
4. 4Add the dispatch case in the CallToolRequestSchema handler.
5. 5Add a test under test/ using node:test, and wire it into test:all in package.json.
6. 6Restart your MCP client. Servers are launched at client start; a running client will not see the new tool.

Conventions to keep

• Never `console.log`. Use log() from src/utils/logger.js, and run npm run lint:no-console-log before you commit — there is no CI in the repo to run it for you.
• Never write outside `getOutputRoot()`. It is what keeps a hosted tenant sandboxed.
• Register what you create via src/utils/registry.js, or list-documents, duplicate detection and lineage will not see your files.
• Return a result object, not a string. The registry shapes the response envelope according to clientHint; a raw string bypasses that.
• Accept `clientHint` if the tool produces something a human might read directly.

28How do I know I have not broken it?

Fourteen suites, one command, no external services required. Run them before and after any change — they take under a minute.

Run everything

npm run test:all              # all 14 suites in sequence
npm run lint:no-console-log   # fails if any src/ file has a console.log

# Or one at a time, when you know what you touched:
npm run test:read-doc         # read-doc URL-fetch path
npm run test:schemas          # MCP schema invariants + detect-format E2E
npm run test:render           # markdown -> DOCX round-trip
npm run test:upload           # the upload bridge
npm run test:http             # the HTTP transport
npm run test:auth             # tenant bearer auth
npm run test:oauth            # the OAuth 2.1 flow
npm run test:pdf              # PDF parsing
npm run test:create-pdf       # PDF rendering (needs Chromium)
npm run test:create-pptx      # deck generation
npm run test:fact-check       # the cross-MCP fact-check path
npm run test:format-router    # detect-format heuristics

What each suite is actually protecting

29What does CogniRunner do with this MCP?

It turns a Jira workflow rule into something that can read the issue's attachments and produce a real deliverable back onto the issue. That is the whole point of wiring the two together.

CogniRunner is LeanZero's AI workflow app for Jira — validators, conditions and post-functions on transitions. On its own, a rule can reason about field text. With doc-processor connected, the same rule can open the PDF somebody attached, decide whether it says what it needs to say, and attach a generated report back to the issue.

What the integration exposes

The security story is the reason it is built this way: CogniRunner brokers every call from inside Atlassian Forge. Your AI provider receives the tool's result, never the MCP's URL, never the bearer token, and never the raw attachment.

30Which connection path do I want?

Two, and they are not interchangeable. The hosted-bridge path works with every AI provider; the local path works only with LM Studio but keeps the documents on your own machine.

31How do I connect it over the hosted bridge?

Paste a URL and a bearer into the CogniRunner admin panel. The one thing that catches people is the port — Forge egress reaches 443 and nothing else.

1. 1Get a URL and a bearer. Either take a free demo key from the "Try it without installing anything" section on this page, or self-host and mint your own tenant token (see "How do I issue and revoke access tokens?").
2. 2Open CogniRunner's admin panel → Settings → MCP Integrations.
3. 3Find the doc-processor card and turn the integration on.
4. 4Paste the Service URL — it must start with https://. For the hosted demo that is https://worksmacstudio.tailfc4700.ts.net/docproc/mcp.
5. 5Paste the Tenant Bearer. It must be at least 16 characters. Once saved it is masked and never returned to the UI — you can edit the URL later without re-entering it.
6. 6Turn on the doc-writer sub-toggle if rules should also produce documents. It is off by default, and it needs the read toggle on.
7. 7Use the card's probe to confirm CogniRunner can actually reach the server before you build a rule on it.

32How do I connect it locally through LM Studio?

An ordinary mcp.json entry on the LM Studio host — with one non-obvious requirement: the entry has to be named doc-reader.

LM Studio mcp.json — local stdio

{
  "mcpServers": {
    "doc-reader": {
      "command": "/usr/local/bin/node",
      "args": ["/ABSOLUTE/PATH/TO/leanzero-mcp-doc-processor/src/index.js"],
      "timeout": 300000,
      "env": {
        "MCP_CLIENT_TYPE": "interactive"
      }
    }
  }
}

LM Studio mcp.json — remote HTTP (LM Studio 0.3.17+)

{
  "mcpServers": {
    "doc-reader": {
      "url": "https://your-host.tailXXXX.ts.net/docproc/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TENANT_BEARER"
      }
    }
  }
}

Then, on the CogniRunner side

1. 1Set the provider to LM Studio and give CogniRunner your LM Studio's Tailscale Funnel URL (https://…ts.net) — it must be HTTPS, on *.ts.net, and never localhost.
2. 2Turn on "Serve on Local Network" in LM Studio's developer settings, or the funnel relay cannot reach it.
3. 3In the doc-processor card, switch on "Run locally via LM Studio (mcp.json)".
4. 4Make sure every other enabled MCP is also set to local — see the mixing warning above.
5. 5Load a tool-capable model and run the card's probe.

33How does a rule read a Jira attachment?

CogniRunner mints a one-shot URL and bearer per attachment and hands them to the model. Nothing is copied to a shared disk, and the capability dies on first use.

1. 1The validator runs and sees the issue's attachments.
2. 2For each one, CogniRunner mints a single-use capability: a URL with a short-lived token, plus a bearer, both bound to this issue and this run.
3. 3Those values go into the model's prompt. The model calls read-doc with url + authHeader — exactly as given.
4. 4doc-processor fetches the JSON envelope, decodes the base64 into a per-call temp directory, parses it, and deletes the temp directory afterwards.
5. 5The extracted content goes back to the model. The capability is now spent.

And writing back

The write direction is the mirror image. When doc-writer is on, CogniRunner puts a bound uploadUrl and uploadAuthHeader in the prompt; the model passes them to whichever create tool it chose, and the finished file is POSTed straight onto the Jira issue as an attachment. The model is told to pass clientHint: "interactive" so what lands in the Jira comment is a clean one-liner and not a metadata dump.

34What rules are actually worth building?

Four that pay for themselves. Each is one validator or post-function with a plain-English prompt — no code.

Attachment actually says what the ticket claims

A validator on the transition into Review. Prompt: "Read the attached specification. Block this transition if it does not contain an explicit rollback plan, and quote the section you looked at." The user gets a specific reason, not a generic refusal.

Generate the deliverable on transition

A post-function on Done. Prompt: "Produce a PDF summarising this issue: the problem, what changed, and the verification steps. Attach it." With doc-writer on, create-pdf runs and the file lands on the issue.

Contract review before approval

A validator using read-doc in focused mode. Prompt: "Find the payment terms and notice period in the attached contract. Block if the notice period is under 30 days." One question, one answer, minimal context burned.

Fact-check what was submitted

A validator that calls fact-check. It needs the web-search MCP configured as well — the two servers work as a pair — and it returns the claims with sources rather than a verdict you have to take on trust.

35What is the hosted demo, and what is it not?

One instance of this exact repo, running on our Mac Studio behind a Tailscale Funnel. It exists so you can evaluate the tools in 60 seconds without installing anything — not so you can build on it.

The endpoint on this page is the server described in the "Run it as a server" part, with the configuration shown there and the secrets removed. There is nothing different about the code — the demo is a deployment, not a product tier.

36How do I connect to the hosted demo?

Request a key with your email, then add one entry to your client config. Three active keys per address; revoke or self-host past that.

1. 1Use the key form on this page. The site calls the server's provisioning endpoint, which mints a tenant bearer exactly as the admin API does.
2. 2The bearer is shown once and emailed to you. It is stored on our side only as an argon2 hash — we cannot read it back to you.
3. 3Add it to your MCP client with the endpoint below.
4. 4Confirm with a read-doc on a small local PDF before building anything on it.

Claude Code

claude mcp add --transport http doc-processor \
  https://worksmacstudio.tailfc4700.ts.net/docproc/mcp \
  --header "Authorization: Bearer YOUR_DEMO_KEY"

Any client that takes a remote MCP entry

{
  "mcpServers": {
    "doc-processor": {
      "url": "https://worksmacstudio.tailfc4700.ts.net/docproc/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DEMO_KEY",
        "X-ZAI-Key": "YOUR_OWN_VISION_KEY (optional — only for scanned-PDF OCR)",
        "X-Output-Dir": "my-folder (optional — a folder ON OUR SERVER)"
      }
    }
  }
}

37Troubleshooting

The failures that actually happen, with the one command that distinguishes each from its look-alike.

The three commands worth knowing

# 1. Does the server work at all, with no client involved?
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node src/index.js 2>/dev/null | tail -1

# 2. Is the HTTP service alive?
curl -s localhost:10000/healthz

# 3. Does the bearer work end to end, from outside?
curl -s -X POST https://your-host.tailXXXX.ts.net/docproc/mcp \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'