README - docwriter-mcp-server by cyanheads

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

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 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

Clone the repository:

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

Install dependencies:
```
npm install
```
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 file for details.

Built with ❤️ and the Model Context Protocol