# docwriter-mcp-server 📄✍️

[![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
[![Version](https://img.shields.io/badge/Version-1.0.3-blue.svg)](./CHANGELOG.md)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Status](https://img.shields.io/badge/Status-Beta-orange.svg)](https://github.com/cyanheads/docwriter-mcp-server/issues)
[![GitHub](https://img.shields.io/github/stars/cyanheads/docwriter-mcp-server?style=social)](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>