overleaf-mcp-integration 0.1.0__py3-none-any.whl

overleaf_mcp/__init__.py

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

overleaf_mcp/client.py

@@ -0,0 +1,384 @@
+import base64
+import os
+import shutil
+import tempfile
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+
+import git
+from filelock import FileLock, Timeout
+
+from .config import config
+from .constants import IDENTITY, MAX_READ_BYTES, MAX_READ_LINES, MAX_WRITE_BYTES
+
+GIT_NET_TIMEOUT = 60
+GIT_CLONE_TIMEOUT = 600
+PROJECT_LOCK_TIMEOUT = 120
+
+
+class OverleafClient:
+    def __init__(
+        self,
+        repo_dir: str | os.PathLike[str] | None = None,
+        token: str | None = None,
+        default_project_id: str | None = None,
+        remote_base: str = "https://git.overleaf.com",
+        sync_ttl: float = 5.0,
+    ):
+        if shutil.which("git") is None:
+            raise RuntimeError("Git executable not found; install Git before starting the server.")
+        self.repo_dir = os.path.abspath(os.fspath(repo_dir or config.OVERLEAF_REPO_DIR))
+        self._token = token if token is not None else config.OVERLEAF_TOKEN.get_secret_value()
+        self._default_project_id = (
+            default_project_id if default_project_id is not None else config.PROJECT_ID
+        )
+        self._remote_base = remote_base.rstrip("/")
+        self._sync_ttl = sync_ttl
+        if not self._token and self._remote_base.startswith("http"):
+            raise ValueError("OVERLEAF_TOKEN is required")
+        repo_dir_created = not os.path.exists(self.repo_dir)
+        os.makedirs(self.repo_dir, mode=0o700, exist_ok=True)
+        if repo_dir_created:
+            os.chmod(self.repo_dir, 0o700)
+
+        self._project_locks: dict[str, threading.Lock] = {}
+        self._locks_lock = threading.Lock()
+        self._last_sync: dict[str, float] = {}
+
+    def _get_thread_lock(self, project_id: str) -> threading.Lock:
+        with self._locks_lock:
+            return self._project_locks.setdefault(project_id, threading.Lock())
+
+    def _resolve_project_id(self, project_id: str | None) -> str:
+        resolved = self._default_project_id if project_id is None else project_id
+        if not resolved:
+            raise ValueError("project_id is required")
+        if not config.PROJECT_ID_RE.fullmatch(resolved):
+            raise ValueError("Invalid project_id (expected 24 hex characters).")
+        configured_projects = {
+            item.strip() for item in config.OVERLEAF_ALLOWED_PROJECTS.split(",") if item.strip()
+        }
+        allowed_projects = configured_projects or {self._default_project_id}
+        if resolved not in allowed_projects:
+            raise ValueError(f"Project '{resolved}' is not in the allowed project list.")
+        return resolved
+
+    def _project_path(self, project_id: str) -> str:
+        return os.path.join(self.repo_dir, project_id)
+
+    @contextmanager
+    def _project_lock(self, project_id: str) -> Iterator[None]:
+        with self._get_thread_lock(project_id):
+            try:
+                with FileLock(
+                    f"{self._project_path(project_id)}.lock", timeout=PROJECT_LOCK_TIMEOUT
+                ):
+                    yield
+            except Timeout:
+                raise RuntimeError(
+                    "Another process is using this project; retry shortly."
+                ) from None
+
+    def _remote_url(self, project_id: str) -> str:
+        return f"{self._remote_base}/{project_id}"
+
+    @staticmethod
+    def _branch(repo: git.Repo) -> str:
+        try:
+            branch = repo.active_branch.name
+        except TypeError:
+            try:
+                ref = str(repo.git.symbolic_ref("--short", "refs/remotes/origin/HEAD"))
+                branch = ref.removeprefix("origin/")
+            except git.GitCommandError:
+                branch = "master"
+        try:
+            repo.git.rev_parse("--verify", f"refs/remotes/origin/{branch}")
+        except git.GitCommandError:
+            raise RuntimeError(f"Remote branch 'origin/{branch}' was not found.") from None
+        return branch
+
+    def _git_env(self) -> dict[str, str]:
+        entries = [("core.hooksPath", os.devnull)]
+        if self._token:
+            cred = base64.b64encode(f"git:{self._token}".encode()).decode()
+            entries.append(("http.extraHeader", f"Authorization: Basic {cred}"))
+        env = {
+            "GIT_TERMINAL_PROMPT": "0",
+            "GIT_HTTP_LOW_SPEED_LIMIT": "1000",
+            "GIT_HTTP_LOW_SPEED_TIME": "30",
+            "GIT_CONFIG_GLOBAL": os.devnull,
+            "GIT_CONFIG_NOSYSTEM": "1",
+            "GIT_AUTHOR_NAME": IDENTITY[0],
+            "GIT_AUTHOR_EMAIL": IDENTITY[1],
+            "GIT_COMMITTER_NAME": IDENTITY[0],
+            "GIT_COMMITTER_EMAIL": IDENTITY[1],
+            "GIT_CONFIG_COUNT": str(len(entries)),
+        }
+        for i, (key, value) in enumerate(entries):
+            env[f"GIT_CONFIG_KEY_{i}"] = key
+            env[f"GIT_CONFIG_VALUE_{i}"] = value
+        return env
+
+    def scrub(self, text: str) -> str:
+        if self._token:
+            text = text.replace(self._token, "***")
+            cred = base64.b64encode(f"git:{self._token}".encode()).decode()
+            text = text.replace(cred, "***")
+        return text
+
+    @contextmanager
+    def _scrubbed(self) -> Iterator[None]:
+        try:
+            yield
+        except git.GitCommandError as e:
+            raise RuntimeError(self.scrub(str(e))) from None
+
+    @staticmethod
+    def _safe_path(project_path: str, file_path: str) -> tuple[str, str]:
+        if not file_path or "\x00" in file_path:
+            raise ValueError("Invalid file path.")
+        root = os.path.realpath(project_path)
+        full = os.path.realpath(os.path.join(root, file_path))
+        try:
+            inside = os.path.commonpath([root, full]) == root
+        except ValueError:
+            inside = False
+        if not inside or full == root:
+            raise ValueError(f"Path '{file_path}' is outside the project directory.")
+        rel = os.path.relpath(full, root)
+        if any(part.lower() == ".git" for part in rel.split(os.sep)):
+            raise ValueError("Access to the .git directory is not allowed.")
+        return full, rel
+
+    @staticmethod
+    def _atomic_write(full_path: str, data: bytes) -> None:
+        directory = os.path.dirname(full_path)
+        os.makedirs(directory, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=directory, prefix=".tmp-")
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(data)
+            if os.path.exists(full_path):
+                shutil.copymode(full_path, tmp)
+            os.replace(tmp, full_path)
+        except BaseException:
+            if os.path.exists(tmp):
+                os.remove(tmp)
+            raise
+
+    def _sync_unlocked(self, project_id: str, force: bool) -> str:
+        path = self._project_path(project_id)
+        env = self._git_env()
+
+        if not os.path.isdir(os.path.join(path, ".git")):
+            try:
+                with self._scrubbed():
+                    git.Repo.clone_from(
+                        self._remote_url(project_id),
+                        path,
+                        env=env,
+                        kill_after_timeout=GIT_CLONE_TIMEOUT,
+                    )
+                    repo = git.Repo(path)
+                    with self._scrubbed(), repo.git.custom_environment(**env):
+                        repo.git.remote("set-url", "origin", self._remote_url(project_id))
+                        repo.git.config(
+                            "--replace-all",
+                            "remote.origin.fetch",
+                            "+refs/heads/*:refs/remotes/origin/*",
+                        )
+                        with suppress(git.GitCommandError):
+                            repo.git.remote("set-head", "origin", "--auto")
+            except BaseException:
+                self._remove_cache(path)
+                raise
+        else:
+            age = time.monotonic() - self._last_sync.get(project_id, float("-inf"))
+            if not force and age < self._sync_ttl:
+                return path
+            try:
+                repo = git.Repo(path)
+            except (git.InvalidGitRepositoryError, git.NoSuchPathError):
+                self._remove_cache(path)
+                return self._sync_unlocked(project_id, force=True)
+            try:
+                with self._scrubbed(), repo.git.custom_environment(**env):
+                    repo.git.fetch("origin", kill_after_timeout=GIT_NET_TIMEOUT)
+                    branch = self._branch(repo)
+                    repo.git.reset("--hard", f"origin/{branch}")
+                    repo.git.clean("-fd")
+            except RuntimeError as exc:
+                if str(exc).startswith("Remote branch"):
+                    raise
+                self._remove_cache(path)
+                return self._sync_unlocked(project_id, force=True)
+
+        self._last_sync[project_id] = time.monotonic()
+        return path
+
+    @staticmethod
+    def _remove_cache(path: str) -> None:
+        if os.path.isdir(path):
+            shutil.rmtree(path, ignore_errors=True)
+        elif os.path.exists(path):
+            os.remove(path)
+
+    def ensure_repo(self, project_id: str | None = None) -> str:
+        pid = self._resolve_project_id(project_id)
+        with self._project_lock(pid):
+            return self._sync_unlocked(pid, force=True)
+
+    def list_files(self, project_id: str | None = None) -> list[str]:
+        pid = self._resolve_project_id(project_id)
+        with self._project_lock(pid):
+            root = self._sync_unlocked(pid, force=False)
+            files = []
+            for current, dirs, filenames in os.walk(root):
+                dirs[:] = [d for d in dirs if d != ".git" and not d.startswith(".tmp-")]
+                for name in filenames:
+                    if name != ".git" and not name.startswith(".tmp-"):
+                        rel = os.path.relpath(os.path.join(current, name), root)
+                        files.append(rel.replace(os.sep, "/"))
+            return sorted(files)
+
+    def read_file(
+        self,
+        file_path: str,
+        project_id: str | None = None,
+        offset: int = 0,
+        limit: int | None = None,
+    ) -> str:
+        if offset < 0:
+            raise ValueError("offset must be non-negative.")
+        if limit is not None and not 0 < limit <= MAX_READ_LINES:
+            raise ValueError(f"limit must be between 1 and {MAX_READ_LINES}.")
+        pid = self._resolve_project_id(project_id)
+        with self._project_lock(pid):
+            root = self._sync_unlocked(pid, force=False)
+            full, rel = self._safe_path(root, file_path)
+            if not os.path.isfile(full):
+                raise FileNotFoundError(f"File '{file_path}' not found.")
+            try:
+                with open(full, encoding="utf-8", newline="") as f:
+                    chunks: list[str] = []
+                    total_bytes = 0
+                    for _ in range(offset):
+                        skipped = f.readline(MAX_READ_BYTES + 1)
+                        if not skipped:
+                            return ""
+                        if len(skipped.encode("utf-8")) > MAX_READ_BYTES:
+                            raise ValueError(
+                                f"Content exceeds {MAX_READ_BYTES} bytes; "
+                                "use offset/limit to read in chunks."
+                            )
+                    lines_read = 0
+                    while limit is None or lines_read < limit:
+                        line = f.readline(MAX_READ_BYTES + 1)
+                        if not line:
+                            break
+                        total_bytes += len(line.encode("utf-8"))
+                        if total_bytes > MAX_READ_BYTES:
+                            raise ValueError(
+                                f"Content exceeds {MAX_READ_BYTES} bytes; "
+                                "use offset/limit to read in chunks."
+                            )
+                        chunks.append(line)
+                        lines_read += 1
+                    return "".join(chunks)
+            except UnicodeDecodeError:
+                raise ValueError(f"'{rel}' is not a UTF-8 text file.") from None
+
+    def _write_synced_file(self, pid: str, root: str, full: str, git_rel: str, data: bytes) -> str:
+        self._atomic_write(full, data)
+        repo = git.Repo(root)
+        with self._scrubbed(), repo.git.custom_environment(**self._git_env()):
+            if not repo.git.status("--porcelain", "--", git_rel).strip():
+                return f"No changes: '{git_rel}' already has this content."
+
+            repo.git.add("--", git_rel)
+            repo.git.commit("-m", f"Update {git_rel} via Overleaf MCP")
+            branch = self._branch(repo)
+            try:
+                repo.git.push(
+                    "origin",
+                    f"HEAD:refs/heads/{branch}",
+                    kill_after_timeout=GIT_NET_TIMEOUT,
+                )
+            except git.GitCommandError as e:
+                msg = self.scrub(str(e))
+                self._last_sync.pop(pid, None)
+                try:
+                    repo.git.fetch("origin", kill_after_timeout=GIT_NET_TIMEOUT)
+                    ahead = int(repo.git.rev_list("--count", f"origin/{branch}..HEAD"))
+                    behind = int(repo.git.rev_list("--count", f"HEAD..origin/{branch}"))
+                except (git.GitCommandError, ValueError):
+                    raise RuntimeError(
+                        "Push result unknown; re-read the file before retrying. " + msg
+                    ) from None
+
+                if ahead == 0:
+                    return f"Pushed '{git_rel}' (confirmed after error)."
+                repo.git.reset("--hard", f"origin/{branch}")
+                if behind:
+                    raise RuntimeError(
+                        "Push rejected: the remote changed. Re-read and retry. " + msg
+                    ) from None
+                raise RuntimeError("Push failed; your change was discarded. " + msg) from None
+            sha = repo.head.commit.hexsha[:8]
+        return f"Updated '{git_rel}' and pushed to Overleaf ({sha})"
+
+    def write_file(self, file_path: str, content: str, project_id: str | None = None) -> str:
+        pid = self._resolve_project_id(project_id)
+        data = content.encode("utf-8")
+        if len(data) > MAX_WRITE_BYTES:
+            raise ValueError(f"Content is larger than {MAX_WRITE_BYTES} bytes.")
+
+        with self._project_lock(pid):
+            root = self._sync_unlocked(pid, force=True)
+            full, rel = self._safe_path(root, file_path)
+            git_rel = rel.replace(os.sep, "/")
+            if os.path.isfile(full):
+                try:
+                    with open(full, "rb") as existing:
+                        existing_text = existing.read().decode("utf-8")
+                    if "\x00" in existing_text:
+                        raise ValueError(f"'{git_rel}' is not a UTF-8 text file.")
+                except UnicodeDecodeError:
+                    raise ValueError(f"'{git_rel}' is not a UTF-8 text file.") from None
+            return self._write_synced_file(pid, root, full, git_rel, data)
+
+    def edit_file(
+        self,
+        file_path: str,
+        old_text: str,
+        new_text: str,
+        project_id: str | None = None,
+    ) -> str:
+        """Replace exactly one occurrence of old_text and push the complete file."""
+        if not old_text:
+            raise ValueError("old_text must not be empty.")
+        pid = self._resolve_project_id(project_id)
+        with self._project_lock(pid):
+            root = self._sync_unlocked(pid, force=True)
+            full, rel = self._safe_path(root, file_path)
+            if not os.path.isfile(full):
+                raise FileNotFoundError(f"File '{file_path}' not found.")
+            try:
+                with open(full, encoding="utf-8", newline="") as existing:
+                    current = existing.read()
+            except UnicodeDecodeError:
+                raise ValueError(f"'{rel}' is not a UTF-8 text file.") from None
+            matches = current.count(old_text)
+            if matches == 0:
+                raise ValueError(
+                    "old_text was not found in the file; check whitespace and indentation."
+                )
+            if matches > 1:
+                raise ValueError(f"old_text matched {matches} times; it must match exactly once.")
+            data = current.replace(old_text, new_text, 1).encode("utf-8")
+            if len(data) > MAX_WRITE_BYTES:
+                raise ValueError(f"Content is larger than {MAX_WRITE_BYTES} bytes.")
+            return self._write_synced_file(pid, root, full, rel.replace(os.sep, "/"), data)

overleaf_mcp/config.py

@@ -0,0 +1,27 @@
+import os
+import re
+from pathlib import Path
+from typing import ClassVar
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_PACKAGE_ENV_FILE = Path(__file__).resolve().parent.parent / ".env"
+_ENV_FILE = (
+    Path(os.environ["OVERLEAF_ENV_FILE"])
+    if os.environ.get("OVERLEAF_ENV_FILE")
+    else (_PACKAGE_ENV_FILE if _PACKAGE_ENV_FILE.exists() else None)
+)
+
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(env_file=_ENV_FILE, extra="ignore")
+
+    OVERLEAF_TOKEN: SecretStr = Field(...)
+    PROJECT_ID: str = Field(...)
+    OVERLEAF_ALLOWED_PROJECTS: str = ""
+    OVERLEAF_REPO_DIR: Path = Path.home() / ".cache" / "overleaf-mcp"
+    PROJECT_ID_RE: ClassVar[re.Pattern[str]] = re.compile(r"^[0-9a-f]{24}$")
+
+
+config = Config()

overleaf_mcp/constants.py

@@ -0,0 +1,4 @@
+MAX_READ_BYTES = 100_000
+MAX_READ_LINES = 10_000
+MAX_WRITE_BYTES = 2_000_000
+IDENTITY = ("Overleaf MCP", "overleaf-mcp@localhost")

overleaf_mcp/server.py

@@ -0,0 +1,115 @@
+import asyncio
+import json
+import sys
+from collections.abc import Callable
+from functools import lru_cache
+from typing import TYPE_CHECKING, Annotated
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field, ValidationError
+
+from .constants import MAX_READ_LINES
+
+if TYPE_CHECKING:
+    from .client import OverleafClient
+
+mcp = FastMCP("overleaf-mcp-server")
+
+
+@lru_cache(maxsize=1)
+def get_client() -> "OverleafClient":
+    from .client import OverleafClient
+
+    return OverleafClient()
+
+
+READ_ONLY = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
+WRITE = ToolAnnotations(
+    readOnlyHint=False,
+    destructiveHint=True,
+    idempotentHint=True,
+    openWorldHint=True,
+)
+EDIT = ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=True)
+SYNC = ToolAnnotations(
+    readOnlyHint=False,
+    destructiveHint=False,
+    idempotentHint=True,
+    openWorldHint=True,
+)
+
+
+async def _run[**P, T](fn: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
+    try:
+        return await asyncio.to_thread(fn, *args, **kwargs)
+    except RuntimeError as e:
+        text = str(e)
+    except Exception as e:
+        text = f"{type(e).__name__}: {e}"
+    raise RuntimeError(get_client().scrub(text)) from None
+
+
+@mcp.tool(annotations=READ_ONLY)
+async def list_files(project_id: str | None = None) -> str:
+    """Synchronize and list visible files in an Overleaf project."""
+    files = await _run(get_client().list_files, project_id)
+    return json.dumps(files, indent=2)
+
+
+@mcp.tool(annotations=READ_ONLY)
+async def read_file(
+    file_path: str,
+    project_id: str | None = None,
+    offset: Annotated[int, Field(ge=0)] = 0,
+    limit: Annotated[int | None, Field(ge=1, le=MAX_READ_LINES)] = None,
+) -> str:
+    """Read a UTF-8 text file, optionally selecting a bounded range of lines."""
+    return await _run(get_client().read_file, file_path, project_id, offset, limit)
+
+
+@mcp.tool(annotations=WRITE)
+async def write_file(file_path: str, content: str, project_id: str | None = None) -> str:
+    """Overwrite the complete UTF-8 text file, commit the change, and push it to Overleaf."""
+    return await _run(get_client().write_file, file_path, content, project_id)
+
+
+@mcp.tool(annotations=EDIT)
+async def edit_file(
+    file_path: str,
+    old_text: str,
+    new_text: str,
+    project_id: str | None = None,
+) -> str:
+    """Replace exactly one matching text range in a UTF-8 file and push the result."""
+    return await _run(get_client().edit_file, file_path, old_text, new_text, project_id)
+
+
+@mcp.tool(annotations=SYNC)
+async def sync_project(project_id: str | None = None) -> str:
+    """Refresh the local project cache from Overleaf without changing the remote."""
+    await _run(get_client().ensure_repo, project_id)
+    return "Synchronized Overleaf project"
+
+
+def main() -> None:
+    """Run the Overleaf MCP server over stdio."""
+    try:
+        get_client()
+    except ValidationError as error:
+        missing = [
+            ".".join(str(part) for part in detail["loc"])
+            for detail in error.errors()
+            if detail["type"] == "missing"
+        ]
+        message = "Missing configuration: " + ", ".join(missing or ["invalid values"])
+        print(message, file=sys.stderr)
+        sys.exit(1)
+    except Exception as error:
+        print(f"Failed to initialize Overleaf client: {type(error).__name__}", file=sys.stderr)
+        sys.exit(1)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

overleaf_mcp_integration-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+overleaf_mcp/__init__.py,sha256=EiOxZeok9fzVftcs2zW6X3PlwPe9FhX-91_h38lGg_Q,96
+overleaf_mcp/client.py,sha256=TZOko5oInQnKodqZrSBfPu8B_u70v77EpCjfIw6Shmg,16671
+overleaf_mcp/config.py,sha256=eDuGiQmqDYwIOnHwB5OonxaowzZXiM_ielLt5OUv7Fs,802
+overleaf_mcp/constants.py,sha256=uFKqxMk0gZD_FYX4hFARLQt9DknQwWtlLCNVuvpUqSA,131
+overleaf_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+overleaf_mcp/server.py,sha256=e_aC8t0Bbi4U2-MJs4JdeYl-vGvaFiWZu3jYeWCmh0Q,3502
+overleaf_mcp_integration-0.1.0.dist-info/METADATA,sha256=jEqLKDjqfkMM0rEq3ipZaNtu8WvXJf3f1iRBFHkyY5o,5800
+overleaf_mcp_integration-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+overleaf_mcp_integration-0.1.0.dist-info/entry_points.txt,sha256=Ipu52AKgkhFbIfteHiOfsGvPltk8KIc7AkyX1pEKKHc,58
+overleaf_mcp_integration-0.1.0.dist-info/licenses/LICENSE,sha256=mhfylnkk-rj_wws_EMCOUMn14k6iHUlvpKQ_cNX2j18,1072
+overleaf_mcp_integration-0.1.0.dist-info/RECORD,,

overleaf_mcp_integration-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

overleaf_mcp_integration-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+overleaf-mcp = overleaf_mcp.server:main

overleaf_mcp_integration-0.1.0.dist-info/licenses/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.