Skip to content

server.md

Latest commit

 

History

History
78 lines (53 loc) · 3.88 KB

server.md

File metadata and controls

78 lines (53 loc) · 3.88 KB
Raw

MCP server

The MCP face exposes the engine to any MCP client (Claude Desktop, Claude Code, IDEs, gateways) as a file-first surface: every tool takes a document path, edits persist to that file automatically, and there is no in-memory handle to manage. It is a thin translation layer over the core (algorithms.md §26).

Transports

Transport When Notes
stdio (default) Local clients — Claude Desktop, Claude Code, editors Run the binary; no auth surface, no ports
Streamable HTTP Hosted/multi-user deployments Current MCP standard (2025-03-26 spec): single endpoint, Mcp-Session-Id header, gateway/load-balancer friendly

Legacy HTTP+SSE is not supported.

docxengine-mcp                      # stdio
docxengine-mcp --http --port 8080   # Streamable HTTP

Claude Code

claude mcp add docx -- docxengine-mcp

Then ask Claude to work on a file by path: "open report.docx and change the term to three years." A relative path resolves against the directory you launched claude in.

Claude Desktop config

{
  "mcpServers": {
    "docx": { "command": "docxengine-mcp" }
  }
}

Sandboxing

By default a relative path resolves against the server's working directory and any absolute path is allowed. Set DOCXENGINE_ROOT to confine every path to one directory — paths that escape it are refused with path_denied:

{
  "mcpServers": {
    "docx": { "command": "docxengine-mcp", "env": { "DOCXENGINE_ROOT": "/srv/documents" } }
  }
}

Tools

Every tool takes a file path instead of an in-memory handle: each call opens the file, runs the tool, and — when the edit changed it — validates and saves it back atomically. There is no doc_id and no separate save step; docx_create writes its file immediately. tools/list is generated by transforming the same JSON Schemas in spec/ (doc_id → path, docx_save dropped — 23 tools), never hand-maintained.

Internally the engine addresses documents by an in-memory doc_id/bytes handle; the path surface is the server's projection of that contract. See the tool reference.

Resources

Document views are rendered from a file path on demand, so clients can surface them without a tool call. resources/list is empty (the filesystem is not enumerated); the server advertises URI templates via resources/templates/list:

docx://{path}/outline       # heading tree + table list
docx://{path}/projection    # the full token-efficient projection

resources/read opens the file at {path} and returns text/markdown.

Response discipline

  • The whole document is never returned; reads paginate under the ~25k-token cap.
  • convert/render write to an output_path (pdf/png) or return content inline (md/html), never large inline blobs.
  • Every edit persists to its file on success — no batch-then-save step to forget. The validate gate refuses a write that would corrupt the package, leaving the file on disk untouched.

Concurrency

  • Per-path write lock: the open→edit→save-back sequence for one file is serialized, so two HTTP sessions editing the same file cannot lose an update.
  • Atomic writes (temp file + rename) mean a reader always sees a complete document, never a half-written one.
  • Idempotent edit semantics make client retries safe (a retried accept_all no-ops).

State, sessions, and horizontal scaling: state-and-scaling.md.