# mcp-overleaf

Secure, transactional MCP server for editing Overleaf projects through AI coding agents.

`mcp-overleaf` combines the programmatic API from [`@aloth/olcli`](https://github.com/aloth/olcli) with a constrained local workspace, Git history, three-way conflict detection, resumable publication, and structured MCP tools. It is designed for agents that should not be trusted to remember a fragile sequence of shell commands.

## Why this server exists

The upstream `olcli` project already provides a CLI, a library, and a general MCP server. This project adds a deliberately narrower workflow:

- one configured Overleaf project per server instance;
- a mandatory edit session before report files can be accessed;
- SHA-256 preconditions for text writes;
- a persisted local/remote synchronization baseline;
- preview tokens and revalidation before publication;
- blocking three-way conflicts and all deletions;
- Git commits before Overleaf uploads;
- optional private GitHub mirrors;
- structured results with explicit next actions;
- no delete or rename tools.

Overleaf is the collaborative editor and compiler. Git is the recoverable history. The MCP server is the policy boundary presented to the agent.

## Requirements

- Node.js 22 or 24 LTS
- Git
- An Overleaf account with access to the target project
- Optional: GitHub CLI (`gh`) for a private GitHub mirror

Linux, macOS, and native Windows are supported. Continuous integration runs on all three systems.

## Install

```bash
git clone https://github.com/GomFal/mcp-overleaf.git
cd mcp-overleaf
npm ci
npm run build
```

Open the target Overleaf project in your browser and obtain the value of its session cookie from the browser developer tools. Do not put that value in chat, Git, a command argument, or an MCP configuration file.

Configure a project:

```bash
node dist/cli.js configure \
  --project-url https://www.overleaf.com/project/PROJECT_ID \
  --workspace /absolute/path/to/report-workspace
```

The command prompts for the cookie without echoing it. To use a private GitHub mirror, add:

```bash
--github OWNER/REPOSITORY --create-github
```

`--create-github` is required before the setup command may create a missing repository. Existing report mirrors must be private.

PowerShell example:

```powershell
node dist/cli.js configure `
  --project-url https://www.overleaf.com/project/PROJECT_ID `
  --workspace 'C:\Users\YOU\Documents\Overleaf\MyReport'
```

Run a health check after setup:

```bash
node dist/cli.js doctor
```

## Register the MCP server

Use absolute paths in client configuration.

Codex project configuration (`.codex/config.toml`):

```toml
[mcp_servers.overleaf]
command = "node"
args = ["/absolute/path/to/mcp-overleaf/dist/server.js"]
enabled = true
default_tools_approval_mode = "writes"
```

On Windows, TOML literal strings avoid backslash escaping:

```toml
[mcp_servers.overleaf]
command = "node"
args = ['C:\Users\YOU\src\mcp-overleaf\dist\server.js']
enabled = true
default_tools_approval_mode = "writes"
```

Clients using the common JSON configuration shape can register the same STDIO process:

```json
{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-overleaf/dist/server.js"]
    }
  }
}
```

If `configure` used a non-default config path, set `MCP_OVERLEAF_CONFIG` in the server environment. Never set the session cookie in a committed client configuration.

## Agent workflow

The server enforces this order and returns `nextActions` after every call:

```text
connector_status
    -> begin_edit_session
    -> list_report_files / read_report_file / write_report_file
    -> preview_publish
    -> confirm_publish
    -> compile_report
```

1. `begin_edit_session` synchronizes Git and Overleaf and returns `sessionId`.
2. `read_report_file` returns the file content and SHA-256 digest.
3. `write_report_file` requires the session and that digest. Any write invalidates an older preview.
4. `preview_publish` compares the session baseline, local workspace, and a fresh Overleaf snapshot. It returns `previewToken` only when publication is safe.
5. `confirm_publish` rechecks the preview, commits and pushes Git first, uploads only planned files, and verifies Overleaf afterward.
6. `compile_report` compiles remotely and saves the resulting PDF locally.

If the same file changed locally and remotely, publication stops. Remote conflict copies are preserved in the connector state directory. The server never resolves a conflict by timestamp and never propagates a deletion.

## Available tools

| Tool | Purpose |
|---|---|
| `connector_status` | Configuration, authentication, Git, and active session health |
| `workflow_status` | Current state, conflict paths, journal, and permitted next steps |
| `begin_edit_session` | Establish a synchronized editing baseline |
| `list_report_files` | List files and hashes within an active session |
| `read_report_file` | Read an allowed UTF-8 source file |
| `write_report_file` | Perform an atomic, hash-checked source update |
| `preview_publish` | Perform the three-way safety check |
| `confirm_publish` | Publish the exact preview and verify it |
| `abort_edit_session` | Close only an unchanged session |
| `compile_report` | Compile on Overleaf and download the PDF |

See [Architecture](docs/architecture.md), [Security model](docs/security.md), [client setup](docs/client-setup.md), and the [Spanish guide](docs/README.es.md).

## Development

```bash
npm ci
npm run check
```

The server uses the current MCP TypeScript SDK, typed input and output schemas, and STDIO negotiation for legacy and current MCP clients.

## Important limitation

`olcli` communicates with browser-session-backed internal Overleaf endpoints. The cookie can expire, and Overleaf may change those endpoints. Reauthentication or a dependency update may therefore be required. Overleaf also provides no project-wide transaction lock, so the connector verifies immediately before and after upload but cannot eliminate a collaborator edit that occurs after the final verification.

## License

MIT © 2026 Javier Gómez. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).