InkPaw 🐾

English | 简体中文

A tiny, meticulous DOCX toolkit for AI agents. Models write; InkPaw keeps the document correct.

InkPaw is a Word document generation, editing, validation, and rendering toolkit for AI agents. It provides an MCP server, a protocol-independent renderer, and a local web Playground for trying the complete agent workflow.

The design principle is simple: the model owns content and structure; deterministic code owns numbering, styles, references, OOXML correctness, and output validation.

Try the Playground

The fastest way to experience InkPaw is the local experimental Playground:

git clone https://github.com/syouro/InkPaw.git
cd InkPaw
npm install
npm run playground

Open http://127.0.0.1:8766, enter an OpenAI-compatible base URL, model name, and API key, then ask the agent to create a document.

The Playground shows streaming reasoning and tool activity, renders page previews, supports follow-up edits and templates, and provides DOCX/PDF downloads. It binds to localhost by default and is intended for local evaluation—not direct public deployment. Full page preview requires LibreOffice and poppler-utils. See Playground guide.

DeepSeek support

InkPaw includes explicit compatibility for DeepSeek thinking-mode Agent Loops: it sends the thinking control, streams reasoning_content into a separate UI panel, and preserves that reasoning across tool-call continuations as required by the DeepSeek API. The recommended starting model for the Playground is deepseek-v4-flash, which is prefilled with the official https://api.deepseek.com endpoint.

See the DeepSeek integration guide for setup, protocol details, and troubleshooting.

Why InkPaw?

LLMs can write strong content, but asking a model to control Word layout details directly often causes broken numbering, drifting styles, invalid references, or documents that fail to open. InkPaw separates those concerns with a persistent structured document model (def JSON):

• Agents create headings, paragraphs, tables, images, equations, footnotes, comments, and sections.
• InkPaw generates numbering, captions, cross-references, tables of contents, styles, and OOXML.
• Stable node IDs allow precise query, update, move, and delete operations across agent turns.
• Structured validation issues include locations, repair guidance, and authoritative examples for self-correction.

Features

• Structured document creation and Markdown import.
• Node-level insert, update, move, and delete with SQLite persistence.
• Automatic numbering, captions, cross-references, and static or native TOCs.
• Three-layer styling: preset → style profile → document overrides.
• Table spans, headers/footers, footnotes, comments, checkboxes, equations, floating images, and multiple sections.
• DOCX, PDF, and per-page PNG output.
• Three validation layers: OPC integrity, ECMA-376 Schema, and Word compatibility checks.
• MCP over stdio or stateless Streamable HTTP.
• HTTP Bearer authentication and optional per-user storage scopes.
• Local BYOK Playground with streaming Agent Loop, MCP tools, previews, and downloads.

Requirements

• Node.js 18+
• npm
• LibreOffice Writer + Math for the complete test suite and PDF/PNG previews
• Optional: poppler-utils for per-page PNG conversion
• Optional: xmllint + xsltproc for complete OOXML Schema validation

Core DOCX generation does not require LibreOffice.

MCP quick start

InkPaw starts with stdio transport by default:

npm start

Example MCP client configuration:

{
  "mcpServers": {
    "inkpaw": {
      "command": "node",
      "args": ["/absolute/path/to/InkPaw/src/server.js"]
    }
  }
}

Streamable HTTP

npm run start:http

The default endpoint is http://127.0.0.1:8765/mcp and requires Bearer authentication. On first start, InkPaw creates data/mcp-token; you may also set DOCX_MCP_TOKEN explicitly.

Do not expose this local compatibility mode directly to the internet. InkPaw also includes OAuth 2.1 authorization code + PKCE, discovery, refresh/revocation, health checks, and reverse-proxy or native TLS support. See the public HTTPS + OAuth deployment guide.

Renderer only

The renderer does not depend on MCP or SQLite:

npm run demo
node src/docxUtil.js render examples/demo-report.js

Validation

npm test
npm run validate -- path/to/file.docx
scripts/docx2png.sh path/to/file.docx
npm run visual

Visual baselines depend on LibreOffice and installed fonts. Update them only after manually reviewing the rendered pages.

Architecture

MCP client or local Playground
              │
              ▼
MCP transport (stdio / HTTP)
              │
              ▼
Service + validator + SQLite store
              │
              ▼
Transform (numbering / refs / captions)
              │
              ▼
Protocol-independent DOCX renderer
              │
              ▼
DOCX / PDF / PNG + validation feedback

See Architecture for the module boundaries and invariants.

Repository layout

src/          core renderer, MCP server, service, storage, and validation
playground/   experimental local web Agent experience
scripts/      launch, validation, rendering, and visual-regression tools
test/         unit and integration tests
presets/      reusable style presets
schemas/      OOXML validation assets
docs/         architecture, specifications, compatibility, and release policy

Documentation

• Playground
• DeepSeek integration
• Architecture
• Document node specification
• Viewer compatibility
• Upstream docx issues
• Source snapshot and sync rules
• Open-source release policy
• Contributing
• Security

Project status

The core DOCX/MCP toolkit is the primary project. The Playground is marked experimental because its API and interface may change and its default security boundary is localhost. It is tested, but it is not a turnkey multi-tenant public SaaS deployment.

License

MIT © 2026 syouro. Third-party notices are listed in THIRD_PARTY_NOTICES.md.