docwriter-mcp-server
Version:
A Model Context Protocol (MCP) server for programmatic creation, modification, and compilation of structured LaTeX documents. Enables AI agents and automated workflows to generate reports, articles, and papers from templates, with secure, structured conte
168 lines (117 loc) • 9.63 kB
Markdown
# docwriter-mcp-server 📄✍️
[](https://www.typescriptlang.org/)
[](https://github.com/modelcontextprotocol/typescript-sdk)
[](./CHANGELOG.md)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/cyanheads/docwriter-mcp-server/issues)
[](https://github.com/cyanheads/docwriter-mcp-server)
**A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://github.com/cyanheads/docwriter-mcp-server/issues).**
## 🚀 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`](./src/mcp-server/tools/createLatexDocument/) | 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`](./src/mcp-server/tools/updateDocumentBlock/) | 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`](./src/mcp-server/tools/searchAndReplace/) | 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`](./src/mcp-server/tools/compileLatexToPdf/) | 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`](./src/mcp-server/tools/listLatexDocuments/) | Retrieves a list of all available documents. | - Scans the data directory for all `.tex` files. |
---
## Table of Contents
| [Overview](#overview) | [Features](#features) | [Installation](#installation) |
| :------------------------------ | :-------------------------------------- | :---------------------------- |
| [Configuration](#configuration) | [Project Structure](#project-structure) | [Development](#development) |
| [License](#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](.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)](https://nodejs.org/)
- [npm](https://www.npmjs.com/) (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:
```bash
git clone https://github.com/cyanheads/docwriter-mcp-server.git
cd docwriter-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
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
```bash
# 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](LICENSE) file for details.
---
<div align="center">
Built with ❤️ and the <a href="https://modelcontextprotocol.io/">Model Context Protocol</a>
</div>