overleaf-mcp-integration 0.1.0__tar.gz

overleaf_mcp_integration-0.1.0/.env.example

@@ -0,0 +1,17 @@
+# required
+OVERLEAF_TOKEN=your_overleaf_git_token
+
+# required
+PROJECT_ID=your_overleaf_project_id
+
+# Optional comma-separated project allowlist; defaults to PROJECT_ID
+# OVERLEAF_ALLOWED_PROJECTS=your_overleaf_project_id
+
+# Optional; defaults to ~/.cache/overleaf-mcp
+# OVERLEAF_REPO_DIR=/absolute/path/to/overleaf-mcp-cache
+
+# Optional when the server is installed as a wheel
+# OVERLEAF_ENV_FILE=/absolute/path/to/.env
+
+# Optional: Overleaf Git base URL (change for self-hosted instances)
+# OVERLEAF_BASE_URL=git.overleaf.com

overleaf_mcp_integration-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked
+      - run: uv run ruff check overleaf_mcp tests
+      - run: uv run ruff format --check overleaf_mcp tests
+      - run: uv run mypy overleaf_mcp tests
+      - name: Run tests
+        env:
+          OVERLEAF_TOKEN: ci-test-token
+          PROJECT_ID: 0123456789abcdef01234567
+        run: uv run pytest
+      - run: uv build
+      - name: Install and smoke-test wheel
+        shell: bash
+        run: |
+          rm -rf /tmp/overleaf-mcp-wheel-check
+          uv venv --python 3.13 /tmp/overleaf-mcp-wheel-check/.venv
+          uv pip install --python /tmp/overleaf-mcp-wheel-check/.venv/bin/python dist/*.whl
+          unzip -l dist/*.whl
+          printf '%s\n' \
+            '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ci","version":"1"}}}' \
+            '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
+            '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+            | OVERLEAF_TOKEN=ci-test PROJECT_ID=0123456789abcdef01234567 timeout 15 /tmp/overleaf-mcp-wheel-check/.venv/bin/overleaf-mcp \
+            | grep '"id":2'

overleaf_mcp_integration-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+__pycache__/
+*.py[codz]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.pyenv/
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json

overleaf_mcp_integration-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

overleaf_mcp_integration-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Younes Bensafia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overleaf_mcp_integration-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: overleaf-mcp-integration
+Version: 0.1.0
+Summary: MCP server for Overleaf projects via Git sync
+Project-URL: Homepage, https://github.com/younesbensafia/overleaf-mcp-server
+Project-URL: Repository, https://github.com/younesbensafia/overleaf-mcp-server
+Project-URL: Issues, https://github.com/younesbensafia/overleaf-mcp-server/issues
+Author: Younes Bensafia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: git,latex,mcp,overleaf,sharelatex
+Requires-Python: >=3.13
+Requires-Dist: filelock>=3.16.0
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: mcp<2.0.0,>=1.26.0
+Requires-Dist: pydantic-settings>=2.10.0
+Requires-Dist: pydantic>=2.11.0
+Description-Content-Type: text/markdown
+
+# Overleaf MCP Server
+<!-- mcp-name: io.github.YounesBensafia/overleaf-mcp-server -->
+
+An MCP server focused only on Overleaf projects (via Overleaf Git sync).
+
+## What This Server Does
+
+- Connects MCP-compatible clients to your Overleaf project through Git sync.
+- Exposes file-level tools to list, read, write, and sync project content.
+- Keeps workflow simple: pull latest files, edit, then push back to Overleaf.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  C[MCP Client\nClaude Desktop / other MCP host] -->|Tool Call| S[Overleaf MCP Server]
+  S -->|Git Sync| O[Overleaf Git Remote]
+  S -->|Read / Write| L[Local Repo Mirror]
+  L -->|Commit + Push| O
+  O -->|Pull / Fetch| L
+  S -->|Tool Result| C
+```
+
+## Tool Workflow
+
+```mermaid
+sequenceDiagram
+  participant Client as MCP Client
+  participant Server as Overleaf MCP Server
+  participant Local as Local Mirror
+  participant Overleaf as Overleaf Git
+
+  Client->>Server: list_files / read_file
+  Server->>Local: Ensure local clone
+  Server->>Overleaf: git pull
+  Overleaf-->>Server: latest content
+  Server-->>Client: file list / file content
+
+  Client->>Server: write_file(path, content)
+  Server->>Local: update file
+  Server->>Local: git commit
+  Server->>Overleaf: git push
+  Server-->>Client: success + metadata
+```
+
+## Requirements
+
+- Python 3.13+
+- `uv` package manager
+- An Overleaf plan with **Git integration** (individual, group, or institution license). Check if your institution provides free access at [Overleaf for Institutions](https://www.overleaf.com/for/institutions-using-overleaf)  - use your institutional email. If your institution is not listed, [upgrade your plan](https://www.overleaf.com/user/subscription).
+
+## Git Setup
+
+1. **Enable Git**  - open your project on Overleaf → **Menu** → enable **Git** under Integrations.
+2. **Copy project ID**  - from the browser URL (e.g. `https://www.overleaf.com/project/69a4f7cc4eaf13bd56de5b04` → `69a4f7cc4eaf13bd56de5b04`).
+3. **Generate a Git token**  - **Account Settings** → **Git integration authentication tokens** → **Generate new token**.
+4. **Configure `.env`**  - copy `.env.example` to `.env` and fill in:
+
+```env
+OVERLEAF_TOKEN=your_git_token
+PROJECT_ID=your_project_id
+```
+
+> `project_id` can also be passed per tool call, but `PROJECT_ID` is still required
+> by the server configuration.
+
+The Overleaf Git token is account-wide credential material. Store it only in
+the MCP client's environment or a protected `.env` file, and rotate it if it
+is exposed.
+
+## Safety Notes
+
+Files in an Overleaf project are untrusted input. A `.tex` file or project
+configuration can contain instructions aimed at the model; treat file contents
+as data, not as commands. Keep `OVERLEAF_ALLOWED_PROJECTS` restricted to the
+projects the server should be able to access:
+
+```env
+OVERLEAF_ALLOWED_PROJECTS=project_id_a,project_id_b
+```
+
+The default allowlist contains only `PROJECT_ID`.
+
+## Quick Start
+
+```bash
+git clone https://github.com/younesbensafia/overleaf-mcp-server.git
+cd overleaf-mcp-server
+uv sync
+cp .env.example .env   # then edit with your token/project id
+uv run overleaf-mcp
+```
+
+Without a checkout, run the Git version directly with:
+
+```bash
+uvx --from git+https://github.com/younesbensafia/overleaf-mcp-server overleaf-mcp
+```
+
+Plain `uvx overleaf-mcp` is appropriate only after the project is published to
+PyPI.
+
+The server listens on stdio  - connect your MCP client (Claude Desktop, etc.) to it.
+
+For a large project, call `sync_project` first. The initial Git clone can take
+longer than an MCP client's individual tool request timeout.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_files` | Pull and list files from Overleaf project |
+| `read_file` | Read file content |
+| `write_file` | Overwrite a complete text file, commit, and push to Overleaf |
+| `edit_file` | Replace one exact text match, commit, and push to Overleaf |
+| `sync_project` | Force a pull/sync from Overleaf |
+
+`read_file` accepts optional zero-based `offset` and bounded `limit` line
+parameters for reading large documents in chunks.
+
+## Claude Desktop Setup
+
+Add to `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/overleaf-mcp-server", "run", "overleaf-mcp"],
+      "env": {
+        "OVERLEAF_TOKEN": "your_git_token",
+        "PROJECT_ID": "your_project_id"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+- **403 Forbidden on git operations:**
+  - Your plan doesn't include Git integration  - follow the [Git Setup](#git-setup) section.
+  - Or the Git token is wrong  - regenerate it at **Account Settings** → **Git integration authentication tokens**.
+- **Wrong project content:**
+  - Set the correct `PROJECT_ID` in `.env`.
+  - Or pass `project_id` explicitly in tool calls.
+- **Sync conflicts:**
+  - Run `sync_project` before `write_file` if the remote changed.
+- **Server not starting:**
+  - Ensure dependencies are installed with `uv sync`.
+  - Verify Python 3.13+ is available.
+
+## License
+
+MIT - See [LICENSE](LICENSE)

overleaf_mcp_integration-0.1.0/README.md

@@ -0,0 +1,156 @@
+# Overleaf MCP Server
+<!-- mcp-name: io.github.YounesBensafia/overleaf-mcp-server -->
+
+An MCP server focused only on Overleaf projects (via Overleaf Git sync).
+
+## What This Server Does
+
+- Connects MCP-compatible clients to your Overleaf project through Git sync.
+- Exposes file-level tools to list, read, write, and sync project content.
+- Keeps workflow simple: pull latest files, edit, then push back to Overleaf.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  C[MCP Client\nClaude Desktop / other MCP host] -->|Tool Call| S[Overleaf MCP Server]
+  S -->|Git Sync| O[Overleaf Git Remote]
+  S -->|Read / Write| L[Local Repo Mirror]
+  L -->|Commit + Push| O
+  O -->|Pull / Fetch| L
+  S -->|Tool Result| C
+```
+
+## Tool Workflow
+
+```mermaid
+sequenceDiagram
+  participant Client as MCP Client
+  participant Server as Overleaf MCP Server
+  participant Local as Local Mirror
+  participant Overleaf as Overleaf Git
+
+  Client->>Server: list_files / read_file
+  Server->>Local: Ensure local clone
+  Server->>Overleaf: git pull
+  Overleaf-->>Server: latest content
+  Server-->>Client: file list / file content
+
+  Client->>Server: write_file(path, content)
+  Server->>Local: update file
+  Server->>Local: git commit
+  Server->>Overleaf: git push
+  Server-->>Client: success + metadata
+```
+
+## Requirements
+
+- Python 3.13+
+- `uv` package manager
+- An Overleaf plan with **Git integration** (individual, group, or institution license). Check if your institution provides free access at [Overleaf for Institutions](https://www.overleaf.com/for/institutions-using-overleaf)  - use your institutional email. If your institution is not listed, [upgrade your plan](https://www.overleaf.com/user/subscription).
+
+## Git Setup
+
+1. **Enable Git**  - open your project on Overleaf → **Menu** → enable **Git** under Integrations.
+2. **Copy project ID**  - from the browser URL (e.g. `https://www.overleaf.com/project/69a4f7cc4eaf13bd56de5b04` → `69a4f7cc4eaf13bd56de5b04`).
+3. **Generate a Git token**  - **Account Settings** → **Git integration authentication tokens** → **Generate new token**.
+4. **Configure `.env`**  - copy `.env.example` to `.env` and fill in:
+
+```env
+OVERLEAF_TOKEN=your_git_token
+PROJECT_ID=your_project_id
+```
+
+> `project_id` can also be passed per tool call, but `PROJECT_ID` is still required
+> by the server configuration.
+
+The Overleaf Git token is account-wide credential material. Store it only in
+the MCP client's environment or a protected `.env` file, and rotate it if it
+is exposed.
+
+## Safety Notes
+
+Files in an Overleaf project are untrusted input. A `.tex` file or project
+configuration can contain instructions aimed at the model; treat file contents
+as data, not as commands. Keep `OVERLEAF_ALLOWED_PROJECTS` restricted to the
+projects the server should be able to access:
+
+```env
+OVERLEAF_ALLOWED_PROJECTS=project_id_a,project_id_b
+```
+
+The default allowlist contains only `PROJECT_ID`.
+
+## Quick Start
+
+```bash
+git clone https://github.com/younesbensafia/overleaf-mcp-server.git
+cd overleaf-mcp-server
+uv sync
+cp .env.example .env   # then edit with your token/project id
+uv run overleaf-mcp
+```
+
+Without a checkout, run the Git version directly with:
+
+```bash
+uvx --from git+https://github.com/younesbensafia/overleaf-mcp-server overleaf-mcp
+```
+
+Plain `uvx overleaf-mcp` is appropriate only after the project is published to
+PyPI.
+
+The server listens on stdio  - connect your MCP client (Claude Desktop, etc.) to it.
+
+For a large project, call `sync_project` first. The initial Git clone can take
+longer than an MCP client's individual tool request timeout.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_files` | Pull and list files from Overleaf project |
+| `read_file` | Read file content |
+| `write_file` | Overwrite a complete text file, commit, and push to Overleaf |
+| `edit_file` | Replace one exact text match, commit, and push to Overleaf |
+| `sync_project` | Force a pull/sync from Overleaf |
+
+`read_file` accepts optional zero-based `offset` and bounded `limit` line
+parameters for reading large documents in chunks.
+
+## Claude Desktop Setup
+
+Add to `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/overleaf-mcp-server", "run", "overleaf-mcp"],
+      "env": {
+        "OVERLEAF_TOKEN": "your_git_token",
+        "PROJECT_ID": "your_project_id"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+- **403 Forbidden on git operations:**
+  - Your plan doesn't include Git integration  - follow the [Git Setup](#git-setup) section.
+  - Or the Git token is wrong  - regenerate it at **Account Settings** → **Git integration authentication tokens**.
+- **Wrong project content:**
+  - Set the correct `PROJECT_ID` in `.env`.
+  - Or pass `project_id` explicitly in tool calls.
+- **Sync conflicts:**
+  - Run `sync_project` before `write_file` if the remote changed.
+- **Server not starting:**
+  - Ensure dependencies are installed with `uv sync`.
+  - Verify Python 3.13+ is available.
+
+## License
+
+MIT - See [LICENSE](LICENSE)

overleaf_mcp_integration-0.1.0/config/config.py

@@ -0,0 +1,24 @@
+import re
+from pathlib import Path
+from typing import ClassVar
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_ENV_FILE = Path(__file__).resolve().parent.parent / ".env"
+
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(env_file=_ENV_FILE, extra="ignore")
+
+    OVERLEAF_TOKEN: SecretStr = Field(...)
+    PROJECT_ID: str = Field(...)
+    OVERLEAF_REPO_DIR: Path = Path.home() / ".cache" / "overleaf-mcp"
+    PROJECT_ID_RE: ClassVar[re.Pattern[str]] = re.compile(r"^[0-9a-f]{24}$")
+    MAX_READ_BYTES: ClassVar[int] = 100_000
+    MAX_READ_LINES: ClassVar[int] = 10_000
+    MAX_WRITE_BYTES: ClassVar[int] = 2_000_000
+    IDENTITY: ClassVar[tuple[str, str]] = ("Overleaf MCP", "overleaf-mcp@localhost")
+
+
+config = Config()

overleaf_mcp_integration-0.1.0/overleaf_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""Installable Overleaf MCP server package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"