# Unofficial Overleaf MCP Server

An unofficial Model Context Protocol (MCP) server that provides AI agents with the ability to interact with Overleaf projects directly. This server allows agents to create projects, list files, read contents, manage files, and securely edit documents in real-time using Overleaf's native Operational Transformation (ShareJS) WebSocket protocol.

## Features

- **Project Management**: Create new Overleaf projects natively.
- **File System (CRUD)**: List, upload, create, move, and delete files or folders within an Overleaf project.
- **Real-Time Document Editing**: Edits files natively without full ZIP downloads. Utilizes a reverse-engineered Socket.IO 0.9 shim and the `diff-match-patch` library to translate semantic edits into precise ShareJS `text0` Operational Transformation (OT) updates.
- **Compilation**: Trigger server-side LaTeX compilation and download the resulting PDF.

## Prerequisites

- Node.js (v18+)
- An active Overleaf account.

## Configuration & Authentication

This MCP server authenticates to Overleaf using your session cookie (`overleaf_session2`).

### Option 1: Automated Login (Recommended)
You can let the AI or CLI handle login automatically:
* **Via AI**: Just ask the AI agent: *"Faça login no Overleaf"* (it will call the `overleaf_login` tool).
* **Via Terminal**: Run `npm run login`.

A browser window will open for you to log into your account. As soon as you log in, the cookie is automatically captured, saved to `.env`, and loaded into the server.

### Option 2: Manual Cookie in `mcp_config.json`
If you prefer manual configuration:
1. Log into your Overleaf account in your browser.
2. Open Developer Tools (F12) -> Application / Storage -> Cookies.
3. Copy `overleaf_session2` and set it in your MCP configuration.

### Adding to Antigravity IDE / Gemini

Add the following to `~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": [
        "/absolute/path/to/unofficial-overleaf-mcp-server/build/index.js"
      ]
    }
  }
}
```
*(Notice: You don't even need to manually define the `env` block if you let `overleaf_login` manage your `.env` file!)*

## Available MCP Tools

### Authentication
* `overleaf_login(timeoutSeconds?)`: Opens a browser window, captures the session cookie upon login, saves it to `.env`, and activates the session.

### Project Management
* `overleaf_list_projects(includeArchived?, search?)`: Lists all projects belonging to or shared with the user.
* `overleaf_create_project(projectName)`: Creates a new blank project.
* `overleaf_rename_project(projectId, newName)`: Renames an existing project.
* `overleaf_clone_project(projectId, projectName)`: Duplicates/clones a project.
* `overleaf_archive_project(projectId)`: Archives a project.

### File & Entity Operations
* `overleaf_list_files(projectId)`: Returns the complete directory tree.
* `overleaf_read_file(projectId, filePath)`: Reads the full text of a LaTeX document.
* `overleaf_edit_file(projectId, filePath, targetContent, replacementContent)`: Edits text in real-time via OT/WebSocket.
* `overleaf_create_doc(projectId, name, parentFolderPath?)`: Creates a new LaTeX document.
* `overleaf_create_folder(projectId, name, parentFolderPath?)`: Creates a new folder.
* `overleaf_rename_entity(projectId, path, newName)`: Renames a document, file, or folder.
* `overleaf_move_entity(projectId, path, newParentFolderPath)`: Moves an entity to a destination folder.
* `overleaf_delete_entity(projectId, path)`: Deletes an entity from the project.
* `overleaf_upload_file(projectId, filePath?, contentBase64?, fileName?, parentFolderPath?, folderId?)`: Uploads a file (text or binary such as images, PDFs, ZIPs) from disk or memory base64.
* `overleaf_upload_from_url(projectId, url, name, parentFolderPath?)`: Downloads and links a file directly from a public URL.

### Collaboration & Sharing
* `overleaf_share_project(projectId, email, privileges?)`: Invites a collaborator by email with read/write or read-only access.
* `overleaf_list_collaborators(projectId)`: Lists accepted members and pending invitations.
* `overleaf_revoke_collaborator(projectId, emailOrId)`: Revokes a pending invite or removes an accepted collaborator.

### Compilation
* `overleaf_compile_and_download(projectId, rootDocId, outputPath)`: Compiles the project and downloads the resulting PDF.

## Security Note

This server requires your Overleaf session cookie to operate. **Do not commit your session cookie or any specific project IDs into version control.**

## Build

```bash
npm install
npm run build
```

## Usage

```bash
npm start
```