Skip to content

Commit 6efd99e

Browse files
alothaloth
committed
feat: git remote helper, docs restructure, v0.7.0
- Add git-remote-overleaf binary (import/export protocol, mark-based tracking) - Extract MCP docs to docs/MCP.md, git remote docs to docs/GIT-REMOTE.md - Update landing page with dynamic badges, git remote & MCP sections - Update SKILL.md with decision table and new features - Bump version to 0.7.0 Closes #36 Originally proposed in #15 by @bicheTortue
1 parent e287301 commit 6efd99e

11 files changed

Lines changed: 1121 additions & 519 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 128 additions & 36 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 91 additions & 441 deletions
Large diffs are not rendered by default.

‎SKILL.md‎

Lines changed: 90 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,24 @@ description: Sync and manage Overleaf LaTeX projects from the command line. Pull
44
license: MIT
55
metadata:
66
author: aloth
7-
version: "1.2"
7+
version: "1.3"
88
cli: olcli
99
install: brew tap aloth/tap && brew install olcli
1010
---
1111

1212
# Overleaf Skill
1313

14-
Manage Overleaf LaTeX projects via the `olcli` CLI.
14+
Manage Overleaf LaTeX projects via the `olcli` CLI, native git remote, or MCP server.
15+
16+
## When to Use Which Mode
17+
18+
| Mode | Best for | How |
19+
|------|----------|-----|
20+
| **CLI** (`olcli`) | Interactive workflows, sync, compile, arXiv prep | `olcli pull/push/sync/pdf` |
21+
| **Git remote** | Version control, commits, diffs, CI/CD pipelines | `git clone overleaf::…` then standard git |
22+
| **MCP server** | AI agents with MCP support (Claude, Cursor, Windsurf) | Connect via `olcli-mcp` stdio transport |
23+
24+
Use **CLI** when you need bidirectional sync with conflict detection, compilation, or comment management. Use **Git remote** when you want proper git history, branches, and standard `git push/pull`. Use **MCP** when an AI agent has native MCP support and doesn't need to shell out.
1525

1626
## Installation
1727

@@ -50,6 +60,59 @@ Clear stored credentials:
5060
olcli logout
5161
```
5262

63+
### Self-hosted Overleaf
64+
65+
```bash
66+
olcli config set-url https://overleaf.yourcompany.com
67+
olcli config set-cookie-name overleaf.sid # if different from default
68+
olcli auth --cookie "YOUR_COOKIE"
69+
```
70+
71+
Or pass per-command: `olcli --base-url https://overleaf.yourcompany.com list`
72+
73+
## Git Remote Helper
74+
75+
Use Overleaf projects as native git remotes. No wrapper scripts needed.
76+
77+
```bash
78+
# Clone
79+
git clone overleaf::https://www.overleaf.com/project/<id>
80+
cd <project>
81+
82+
# Edit, commit, push — standard git workflow
83+
vim main.tex
84+
git add . && git commit -m "update introduction"
85+
git push
86+
87+
# Pull latest from Overleaf
88+
git pull
89+
```
90+
91+
Authentication: reads `OVERLEAF_SESSION` env var, `~/.olauth` file, or stored config (same as CLI).
92+
93+
For self-hosted instances, just use your instance URL:
94+
```bash
95+
git clone overleaf::https://overleaf.yourcompany.com/project/<id>
96+
```
97+
98+
Debug with: `GIT_REMOTE_OVERLEAF_DEBUG=1 git push`
99+
100+
## MCP Server
101+
102+
Built-in Model Context Protocol server for AI assistant integration.
103+
104+
```bash
105+
# Run standalone
106+
olcli-mcp
107+
108+
# Or via npx
109+
npx @aloth/olcli-mcp
110+
```
111+
112+
Available MCP tools: `list_projects`, `get_project_info`, `pull_project`, `push_file`, `compile`, `download_pdf`, `list_comments`, `get_entities`, `download_file`, `add_comment`, `reply_to_comment`, `resolve_comment`, `delete_entity`, `rename_entity`, `compile_with_outputs`.
113+
114+
Auth: set `OVERLEAF_SESSION` env var in MCP config, or use stored credentials from `olcli auth`.
115+
53116
## Common Workflows
54117

55118
### Pull a project to work locally
@@ -115,6 +178,19 @@ olcli download main.tex "My Paper" # Download single file
115178
olcli zip "My Paper" # Download entire project as zip
116179
```
117180

181+
### Review comments
182+
183+
```bash
184+
olcli comments list # List all comments (current project)
185+
olcli comments list --status open # Filter by status (open/resolved/all)
186+
olcli comments list --context # Include surrounding text
187+
olcli comments add main.tex "Fix this citation" --from 10 --to 15 # Add comment
188+
olcli comments reply <thread-id> "Done!" # Reply to thread
189+
olcli comments resolve <thread-id> # Mark as resolved
190+
olcli comments reopen <thread-id> # Reopen a resolved thread
191+
olcli comments delete <thread-id> # Delete entire thread
192+
```
193+
118194
## arXiv Submission Workflow
119195

120196
Complete workflow for preparing an arXiv submission:
@@ -145,6 +221,7 @@ zip arxiv.zip *.tex main.bbl figures/*.pdf
145221
| Command | Description |
146222
|---------|-------------|
147223
| `olcli auth --cookie <value>` | Authenticate with session cookie |
224+
| `olcli auth --email <e> --password <p>` | Authenticate with password (self-hosted) |
148225
| `olcli whoami` | Check authentication status |
149226
| `olcli logout` | Clear stored credentials |
150227
| `olcli check` | Show config paths and credential sources |
@@ -155,13 +232,22 @@ zip arxiv.zip *.tex main.bbl figures/*.pdf
155232
| `olcli sync [dir]` | Bidirectional sync |
156233
| `olcli upload <file> [project]` | Upload a single file |
157234
| `olcli download <file> [project]` | Download a single file |
158-
| `olcli delete <file> [project]` | Delete a remote file or folder by path (alias: `rm`) |
235+
| `olcli delete <file> [project]` | Delete a remote file or folder (alias: `rm`) |
159236
| `olcli rename <old> <new> [project]` | Rename a remote file or folder (alias: `mv`) |
160237
| `olcli ignored [dir]` | List active ignore patterns |
161238
| `olcli zip [project]` | Download as zip archive |
162239
| `olcli compile [project]` | Trigger compilation |
163240
| `olcli pdf [project]` | Compile and download PDF |
164241
| `olcli output [type]` | Download compile outputs |
242+
| `olcli comments list [project]` | List review comments |
243+
| `olcli comments add <file> <msg>` | Add a comment |
244+
| `olcli comments reply <id> <body>` | Reply to a thread |
245+
| `olcli comments resolve <id>` | Resolve a thread |
246+
| `olcli comments reopen <id>` | Reopen a thread |
247+
| `olcli comments delete <id>` | Delete a thread |
248+
| `olcli config set-url <url>` | Set self-hosted base URL |
249+
| `olcli config set-cookie-name <name>` | Set cookie name |
250+
| `olcli config set-timeout <ms>` | Set HTTP timeout |
165251

166252
## Tips
167253

@@ -173,3 +259,4 @@ zip arxiv.zip *.tex main.bbl figures/*.pdf
173259
- **PDF rule**: `thesis.pdf` next to `thesis.tex` is auto-ignored; standalone `figures/diagram.pdf` is preserved
174260
- **Project ID**: You can use project ID instead of name (24-char hex from URL)
175261
- **Debug auth**: Run `olcli check` to see where credentials are loaded from
262+
- **Timeout**: `olcli --timeout 60000 pull "Big Project"` or `olcli config set-timeout 60000`

‎docs/GIT-REMOTE.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Git Remote Helper
2+
3+
Use Overleaf projects as native git remotes. Clone, pull, and push with standard git commands — no wrapper scripts needed.
4+
5+
## Quick Start
6+
7+
```bash
8+
# Clone an Overleaf project
9+
git clone overleaf::https://www.overleaf.com/project/<id>
10+
11+
# Work normally
12+
cd <project>
13+
vim main.tex
14+
git add . && git commit -m "update introduction"
15+
16+
# Push changes to Overleaf
17+
git push
18+
```
19+
20+
## How It Works
21+
22+
`git-remote-overleaf` implements git's `fast-import`/`fast-export` protocol with mark-based tracking:
23+
24+
- **Clone/fetch:** Downloads the project zip, emits a fast-import stream with one commit containing the full tree.
25+
- **Push:** Parses the fast-export stream to determine file modifications and deletions, then calls the Overleaf API to upload/delete only what changed.
26+
- **Pull:** Compares marks to detect if the remote has new content; skips download when up-to-date.
27+
28+
State is stored in `.git/overleaf/` (marks file + manifest).
29+
30+
## Authentication
31+
32+
The helper reads credentials in this order:
33+
34+
1. **`OVERLEAF_SESSION` environment variable** (recommended for scripting)
35+
2. **`~/.olauth` file** — written by `olcli auth`
36+
3. **Stored config** — written by `olcli auth`
37+
38+
```bash
39+
# Option A: environment variable
40+
export OVERLEAF_SESSION="s%3A..."
41+
git clone overleaf::https://www.overleaf.com/project/abc123
42+
43+
# Option B: authenticate once with olcli
44+
olcli auth --cookie "s%3A..."
45+
git clone overleaf::https://www.overleaf.com/project/abc123
46+
```
47+
48+
## Custom Instances
49+
50+
For self-hosted Overleaf, just use your instance URL:
51+
52+
```bash
53+
git clone overleaf::https://overleaf.yourcompany.com/project/<id>
54+
```
55+
56+
Set `OVERLEAF_BASE_URL` for the helper to resolve project IDs without the full URL:
57+
58+
```bash
59+
export OVERLEAF_BASE_URL=https://overleaf.yourcompany.com
60+
```
61+
62+
## Debugging
63+
64+
Enable verbose logging:
65+
66+
```bash
67+
GIT_REMOTE_OVERLEAF_DEBUG=1 git push origin main
68+
```
69+
70+
## Limitations
71+
72+
- Overleaf has no native revision history exposed via API, so each clone creates a single "Import from Overleaf" commit (no history replay).
73+
- Concurrent edits on Overleaf between your fetch and push may cause conflicts — push uploads your version of changed files.
74+
- Binary files are supported but large files may be slow (uploaded individually via the Overleaf API).

‎docs/MCP.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# MCP Server
2+
3+
`@aloth/olcli` ships an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server so AI assistants like **Claude Desktop**, **Cursor**, and **Windsurf** can interact with your Overleaf projects directly.
4+
5+
## MCP Tools
6+
7+
| Tool | Description |
8+
|------|-------------|
9+
| `list_projects` | List all Overleaf projects |
10+
| `get_project_info` | Get file tree and metadata for a project |
11+
| `pull_project` | Download and extract a project to a local directory |
12+
| `push_file` | Upload a local file to a project |
13+
| `compile` | Compile a project and get the PDF URL |
14+
| `download_pdf` | Compile a project and save the PDF locally |
15+
| `list_comments` | List review comments (filter: all / open / resolved) |
16+
| `get_entities` | Get a flat list of all files in a project |
17+
| `download_file` | Download a specific file by its remote path |
18+
| `add_comment` | Add a review comment to a document |
19+
| `reply_to_comment` | Reply to an existing comment thread |
20+
| `resolve_comment` | Mark a comment thread as resolved |
21+
| `delete_entity` | Delete a file or document by path |
22+
| `rename_entity` | Rename a file or document |
23+
| `compile_with_outputs` | Compile and return all output files (PDF, BBL, logs…) |
24+
25+
## Authentication
26+
27+
The MCP server reads credentials in this order:
28+
29+
1. **`OVERLEAF_SESSION` environment variable** — set in your MCP config (recommended)
30+
2. **`OVERLEAF_EMAIL` + `OVERLEAF_PASSWORD` environment variables** — for password login (self-hosted)
31+
3. **`.olauth` file in cwd** — written by `olcli auth`
32+
4. **Stored config** — written by `olcli auth` (including saved password credentials)
33+
34+
When a session cookie expires and password credentials are available, the MCP server automatically re-authenticates.
35+
36+
## Claude Desktop
37+
38+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
39+
40+
```json
41+
{
42+
"mcpServers": {
43+
"overleaf": {
44+
"command": "npx",
45+
"args": ["-y", "@aloth/olcli-mcp"],
46+
"env": {
47+
"OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
48+
}
49+
}
50+
}
51+
}
52+
```
53+
54+
Or if you have olcli installed globally (`npm install -g @aloth/olcli`):
55+
56+
```json
57+
{
58+
"mcpServers": {
59+
"overleaf": {
60+
"command": "olcli-mcp",
61+
"env": {
62+
"OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
63+
}
64+
}
65+
}
66+
}
67+
```
68+
69+
## Cursor
70+
71+
Add to your Cursor MCP settings (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
72+
73+
```json
74+
{
75+
"mcpServers": {
76+
"overleaf": {
77+
"command": "npx",
78+
"args": ["-y", "@aloth/olcli-mcp"],
79+
"env": {
80+
"OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
81+
}
82+
}
83+
}
84+
}
85+
```
86+
87+
## Windsurf
88+
89+
Add to `~/.codeium/windsurf/mcp_config.json`:
90+
91+
```json
92+
{
93+
"mcpServers": {
94+
"overleaf": {
95+
"command": "npx",
96+
"args": ["-y", "@aloth/olcli-mcp"],
97+
"env": {
98+
"OVERLEAF_SESSION": "<your-overleaf-session-cookie>"
99+
}
100+
}
101+
}
102+
}
103+
```
104+
105+
## Getting Your Session Cookie
106+
107+
1. Open Overleaf in your browser and log in
108+
2. Open DevTools → Application (Chrome) or Storage (Firefox) → Cookies
109+
3. Find `overleaf_session2` (or `sharelatex.sid` for self-hosted)
110+
4. Copy the value — that's your `OVERLEAF_SESSION`
111+
112+
Or run `olcli auth` and then the MCP server will pick it up automatically.
113+
114+
## Self-hosted Overleaf
115+
116+
Set `OVERLEAF_BASE_URL` in your MCP env:
117+
118+
```json
119+
"env": {
120+
"OVERLEAF_SESSION": "<cookie>",
121+
"OVERLEAF_BASE_URL": "https://overleaf.yourcompany.com"
122+
}
123+
```

0 commit comments

Comments
 (0)