docwriter-mcp-server 📄✍️

A Model Context Protocol (MCP) server for programmatic creation, modification, and compilation of structured LaTeX documents.

This server provides a suite of tools for an AI agent or other MCP client to manage the lifecycle of a document on the local filesystem, from bootstrapping from a template to applying structured updates and compiling the final PDF output. It is built on the robust cyanheads/mcp-ts-template.

This project is in beta - some things may be broken. Please report any issues or feature requests on GitHub.

🚀 Core Capabilities: Document Tools 🛠️

This server equips your AI with specialized tools to create and manage LaTeX documents:

Tool Name	Description	Key Features
docwriter_create_latex_document	Creates a new .tex file from a template.	- Bootstrap from simple_report, ieee_article, or research_report templates.<br/>- Populates title and author metadata.
docwriter_update_document_block	Updates one or more named content blocks within a document.	- Atomically updates multiple sections (e.g., abstract, introduction).<br/>- Preserves document structure.<br/>- Securely sanitizes all input content.
docwriter_search_and_replace	Performs a simple, global search and replace for text.	- Useful for quick, non-structural text changes.<br/>- Sanitizes replacement text.
docwriter_compile_latex_to_pdf	Compiles a .tex document into a PDF.	- Uses lualatex with multiple passes to resolve cross-references.<br/>- Automatically runs biber for bibliography processing.<br/>- Returns compilation logs for debugging.
docwriter_list_latex_documents	Retrieves a list of all available documents.	- Scans the data directory for all .tex files.

---

Table of Contents

Overview	Features	Installation
Configuration	Project Structure	Development
License

Overview

The docwriter-mcp-server acts as a specialized backend, allowing MCP-compatible clients—such as AI agents, IDE extensions, or automated workflows—to programmatically generate and manage professional-quality LaTeX documents.

Instead of manual document preparation, your tools can leverage this server to:

• Automate Report Generation: Create consistent, templated reports, articles, or papers.
• Dynamically Insert Content: Populate documents with data, analysis, or text generated by an AI.
• Ensure Document Quality: Compile and verify documents as part of a CI/CD pipeline.
• Integrate with AI Workflows: Enable LLMs to create and edit complex documents as part of a larger task.

Developer Note: This repository includes a .clinerules file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets.

Features

Core Utilities

Leverages the robust utilities provided by the mcp-ts-template:

• Logging: Structured, configurable logging with sensitive data redaction.
• Error Handling: Centralized error processing and standardized error types (McpError).
• Configuration: Type-safe environment variable loading with Zod validation.
• Input Sanitization: Strong security focus with utilities for sanitizing LaTeX, HTML, and file paths.
• HTTP Transport: High-performance HTTP server using Hono, featuring session management, CORS, and rate limiting.
• Authentication: Robust authentication layer supporting JWT and OAuth 2.1.

Document Generation

• Template-Based Creation: Start documents from simple_report, ieee_article, or research_report templates.
• Structured Updates: Safely modify content within %% -- BLOCK: ... -- %% markers.
• Secure Compilation: Executes lualatex with multiple passes, automatically running biber for bibliographies and cleaning up auxiliary files.
• Filesystem Backend: All documents and outputs are stored and managed on the local filesystem in a configurable data directory.

Installation

Prerequisites

• Node.js (>=20.0.0)
• npm (comes with Node.js)
• A full TeX Live distribution (or equivalent like MiKTeX). The lualatex and biber commands must be in the system's PATH.

Install from Source

1. Clone the repository:

   git clone https://github.com/cyanheads/docwriter-mcp-server.git
   cd docwriter-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

Configure the server using environment variables in a .env file.

Variable	Description	Default
DOCWRITER_DATA_PATH	Required. The root directory for storing .tex files and compiled PDFs.	./data
MCP_TRANSPORT_TYPE	Server transport: stdio or http.	stdio
MCP_LOG_LEVEL	Logging level (debug, info, warning, error).	debug
MCP_HTTP_PORT	Port for the HTTP server.	3010
MCP_AUTH_MODE	Authentication mode for HTTP: jwt or oauth.	jwt
MCP_AUTH_SECRET_KEY	Required for jwt mode. Secret key (min. 32 chars) for signing tokens.	(none)
OAUTH_ISSUER_URL	Required for oauth mode. The issuer URL of your OAuth 2.1 provider.	(none)
OAUTH_AUDIENCE	Required for oauth mode. The audience identifier for this server.	(none)

Project Structure

The codebase follows a modular structure within the src/ directory:

src/
├── index.ts              # Entry point: Initializes and starts the server
├── config/               # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/           # Core MCP server logic and capability registration
│   ├── server.ts         # Server setup, tool registration
│   ├── transports/       # Transport handling (stdio, http)
│   └── tools/            # MCP Tool implementations (subdirs per tool)
├── types-global/         # Shared TypeScript type definitions
└── utils/                # Common utility functions (logger, error handler, etc.)

For a detailed file tree, run npm run tree.

Development

Build and Test

# Build the project (compile TS to JS and make executable)
npm run build

# Test the server locally using the MCP inspector tool (stdio transport)
npm run inspector

# Clean build artifacts
npm run clean

# Clean build artifacts and then rebuild the project
npm run rebuild

# Format code with Prettier
npm run format

# Start the server using stdio (default)
npm start

# Start the server using HTTP transport
npm run start:http

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

<div align="center"> Built with ❤️ and the <a href="https://modelcontextprotocol.io/">Model Context Protocol</a> </div>