{"_id":"@augustinkr/overleaf-mcp-plusplus","_rev":"2-390edbb28ddb56e08138577c1373f051","name":"@augustinkr/overleaf-mcp-plusplus","dist-tags":{"latest":"2.0.1"},"versions":{"2.0.0":{"name":"@augustinkr/overleaf-mcp-plusplus","version":"2.0.0","keywords":["mcp","mcp-server","model-context-protocol","overleaf","latex","codex","claude","claude-desktop","anthropic","ai-tools"],"author":{"url":"https://github.com/augustinkrause","name":"Augustin Krause"},"license":"MIT","_id":"@augustinkr/overleaf-mcp-plusplus@2.0.0","maintainers":[{"name":"augustinkr","email":"augustinkr@proton.me"}],"contributors":[{"url":"https://github.com/mjyoo2","name":"Minjong Yoo"}],"homepage":"https://github.com/augustinkrause/OverleafMCPlusPlus#readme","bugs":{"url":"https://github.com/augustinkrause/OverleafMCPlusPlus/issues"},"bin":{"overleaf-mcp-plusplus":"overleaf-mcp-server.js"},"dist":{"shasum":"68309faef13a6c3530e0aa728af5262e221aacbf","tarball":"https://registry.npmjs.org/@augustinkr/overleaf-mcp-plusplus/-/overleaf-mcp-plusplus-2.0.0.tgz","fileCount":9,"integrity":"sha512-z1kh2dur0EtW8C+VZwXDP/PgcaF92FFb6+KDZ2+Mo/hWhxKBRhWLCZgUyHmxn9ougUDzx+9VlAYXpD25Eiokuw==","signatures":[{"sig":"MEYCIQC6R0/C59h1bT/uLoX+5+Rc95KOV8Nsmhme1W6c9qe1+AIhAI+eVQM3E3vI1MMPV3rZQ+1tcm6Wc/TKlPXSWhZL/oi8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":65834},"main":"overleaf-mcp-server.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"974c87c0b196288126fb8006a27ecf55ff41db9b","scripts":{"test":"node --test","check":"node --check overleaf-mcp-server.js && node --check src/*.js","start":"node overleaf-mcp-server.js"},"_npmUser":{"name":"augustinkr","email":"augustinkr@proton.me"},"overrides":{"ajv":"8.20.0","fast-uri":"3.1.5"},"repository":{"url":"git+https://github.com/augustinkrause/OverleafMCPlusPlus.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for revision-safe, targeted reading and editing of Overleaf projects.","directories":{},"_nodeVersion":"20.19.1","dependencies":{"@modelcontextprotocol/sdk":"1.26.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/overleaf-mcp-plusplus_2.0.0_1785940798821_0.5745865797650898","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@augustinkr/overleaf-mcp-plusplus","version":"2.0.1","description":"MCP server for revision-safe, targeted reading and editing of Overleaf projects.","type":"module","main":"overleaf-mcp-server.js","bin":{"overleaf-mcp-plusplus":"overleaf-mcp-server.js"},"scripts":{"start":"node overleaf-mcp-server.js","test":"node --test","check":"node --check overleaf-mcp-server.js && node --check src/*.js"},"dependencies":{"@modelcontextprotocol/sdk":"1.26.0"},"overrides":{"ajv":"8.20.0","fast-uri":"3.1.5"},"engines":{"node":">=18.0.0"},"author":{"name":"Augustin Krause","url":"https://github.com/augustinkrause"},"contributors":[{"name":"Minjong Yoo","url":"https://github.com/mjyoo2"}],"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/augustinkrause/OverleafMCPlusPlus.git"},"bugs":{"url":"https://github.com/augustinkrause/OverleafMCPlusPlus/issues"},"homepage":"https://github.com/augustinkrause/OverleafMCPlusPlus#readme","keywords":["mcp","mcp-server","model-context-protocol","overleaf","latex","codex","claude","claude-desktop","anthropic","ai-tools"],"license":"MIT","_id":"@augustinkr/overleaf-mcp-plusplus@2.0.1","gitHead":"d80c4d4f71f638233484d9d258ca3a557faa45af","_nodeVersion":"20.19.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-kJtbmcFL+KjQRTm64IF4LhuIvQNdk0HPJdeP79U9556TJwyfrOBHqU8L15YaTiaB/TOPuZUpnGtUhjePfVo0fA==","shasum":"ec50a072fcf78fc984e1501d32d54b08206af1e0","tarball":"https://registry.npmjs.org/@augustinkr/overleaf-mcp-plusplus/-/overleaf-mcp-plusplus-2.0.1.tgz","fileCount":9,"unpackedSize":67830,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDMJm85s+zE9SPW6vzWVcYEQOQzBe47qqR/7eBaF1YAcQIgJncAucSRcAemrJPuAkI01RnZERoTq5VcNm4WZcnZ+4E="}]},"_npmUser":{"name":"augustinkr","email":"augustinkr@proton.me"},"directories":{},"maintainers":[{"name":"augustinkr","email":"augustinkr@proton.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/overleaf-mcp-plusplus_2.0.1_1785943280404_0.6551531368541086"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-05T14:39:58.637Z","modified":"2026-08-05T15:21:20.716Z","2.0.0":"2026-08-05T14:39:58.972Z","2.0.1":"2026-08-05T15:21:20.549Z"},"bugs":{"url":"https://github.com/augustinkrause/OverleafMCPlusPlus/issues"},"author":{"name":"Augustin Krause","url":"https://github.com/augustinkrause"},"license":"MIT","homepage":"https://github.com/augustinkrause/OverleafMCPlusPlus#readme","keywords":["mcp","mcp-server","model-context-protocol","overleaf","latex","codex","claude","claude-desktop","anthropic","ai-tools"],"repository":{"type":"git","url":"git+https://github.com/augustinkrause/OverleafMCPlusPlus.git"},"description":"MCP server for revision-safe, targeted reading and editing of Overleaf projects.","contributors":[{"name":"Minjong Yoo","url":"https://github.com/mjyoo2"}],"maintainers":[{"name":"augustinkr","email":"augustinkr@proton.me"}],"readme":"# Overleaf MCP PlusPlus\n\nAn MCP server that gives agents revision-safe, targeted access to Overleaf projects through Overleaf Git. Agents can inspect small line ranges, search literal text, follow LaTeX document structure across `\\input` and `\\include`, and commit precise edits without rewriting complete files.\n\n## Requirements\n\n- Node.js 18 or newer\n- An Overleaf plan with Git integration\n- An Overleaf project ID and Git token\n\n## Install in Claude\n\nClaude Desktop, Claude Code CLI, and the Claude Code VS Code extension can all run the published package through `npx`. They use different configuration files, described below.\n\n### Choose how to provide the Overleaf token\n\nEvery configuration needs `OVERLEAF_PROJECT_ID` and exactly one of the following token variables.\n\nStore the token directly in the MCP configuration:\n\n```json\n\"env\": {\n  \"OVERLEAF_PROJECT_ID\": \"YOUR_OVERLEAF_PROJECT_ID\",\n  \"OVERLEAF_GIT_TOKEN\": \"YOUR_OVERLEAF_GIT_TOKEN\"\n}\n```\n\nOr, preferably, put only the token in a separate text file and provide its absolute path:\n\n```json\n\"env\": {\n  \"OVERLEAF_PROJECT_ID\": \"YOUR_OVERLEAF_PROJECT_ID\",\n  \"OVERLEAF_GIT_TOKEN_FILE\": \"/absolute/path/to/overleaf-token.txt\"\n}\n```\n\nThe token file may end with a newline; surrounding whitespace is removed when it is read. Do not commit the token or its file. Use an absolute path rather than `~` so the configuration works consistently when launched by a graphical client.\n\n### Claude Desktop\n\nEdit the Claude Desktop configuration at:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nMerge this server into the existing `mcpServers` object:\n\n```json\n{\n  \"mcpServers\": {\n    \"overleaf-mcp-plusplus\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@augustinkr/overleaf-mcp-plusplus@2\"],\n      \"env\": {\n        \"OVERLEAF_PROJECT_ID\": \"YOUR_OVERLEAF_PROJECT_ID\",\n        \"OVERLEAF_GIT_TOKEN_FILE\": \"/absolute/path/to/overleaf-token.txt\"\n      }\n    }\n  }\n}\n```\n\nOn Windows, if Claude cannot launch `npx` directly, use this command form instead:\n\n```json\n\"command\": \"cmd\",\n\"args\": [\"/c\", \"npx\", \"-y\", \"@augustinkr/overleaf-mcp-plusplus@2\"]\n```\n\nCompletely quit and reopen Claude Desktop after saving the file.\n\n### Claude Code CLI and VS Code extension\n\nClaude Code CLI and the Claude Code VS Code extension use the same MCP configuration. For a personal server available in all projects, edit:\n\n- macOS/Linux: `~/.claude.json`\n- Windows: `%USERPROFILE%\\.claude.json`\n\nMerge this top-level entry into that file:\n\n```json\n{\n  \"mcpServers\": {\n    \"overleaf-mcp-plusplus\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@augustinkr/overleaf-mcp-plusplus@2\"],\n      \"env\": {\n        \"OVERLEAF_PROJECT_ID\": \"YOUR_OVERLEAF_PROJECT_ID\",\n        \"OVERLEAF_GIT_TOKEN_FILE\": \"/absolute/path/to/overleaf-token.txt\"\n      }\n    }\n  }\n}\n```\n\n## Install in Codex\n\nCodex CLI and the Codex IDE extension share `~/.codex/config.toml` on the same host:\n\n```toml\n[mcp_servers.overleaf-mcp-plusplus]\ncommand = \"npx\"\nargs = [\"-y\", \"@augustinkr/overleaf-mcp-plusplus@2\"]\nstartup_timeout_sec = 30\ntool_timeout_sec = 120\ndefault_tools_approval_mode = \"writes\"\n\n[mcp_servers.overleaf-mcp-plusplus.env]\nOVERLEAF_PROJECT_ID = \"YOUR_OVERLEAF_PROJECT_ID\"\nOVERLEAF_GIT_TOKEN_FILE = \"/absolute/path/to/overleaf-token.txt\"\n```\n\nRestart the Codex client after changing the configuration. `OVERLEAF_GIT_TOKEN` can be used instead of the token file, but the token-file form avoids storing the secret directly in `config.toml`.\n\n## Run a local checkout\n\n```bash\nnpm install\n```\n\nPoint the MCP client directly at the entry point:\n\n```json\n{\n  \"mcpServers\": {\n    \"overleaf-mcp-plusplus-local\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/OverleafMCPlusPlus/overleaf-mcp-server.js\"],\n      \"env\": {\n        \"OVERLEAF_PROJECT_ID\": \"YOUR_OVERLEAF_PROJECT_ID\",\n        \"OVERLEAF_GIT_TOKEN_FILE\": \"/absolute/path/to/overleaf-token.txt\"\n      }\n    }\n  }\n}\n```\n\n## Configuration\n\nThe first matching source wins:\n\n1. `OVERLEAF_PROJECT_ID` plus `OVERLEAF_GIT_TOKEN` or `OVERLEAF_GIT_TOKEN_FILE`\n2. `OVERLEAF_PROJECTS_CONFIG=/absolute/path/to/projects.json`\n3. The user configuration file:\n   - Windows: `%APPDATA%\\overleaf-mcp-plusplus\\projects.json`\n   - macOS/Linux: `$XDG_CONFIG_HOME/overleaf-mcp-plusplus/projects.json`, defaulting to `~/.config/overleaf-mcp-plusplus/projects.json`\n4. `projects.json` in the current working directory\n5. `projects.json` beside the installed entry point\n\nMulti-project configuration uses this shape:\n\n```json\n{\n  \"projects\": {\n    \"default\": {\n      \"name\": \"Main Paper\",\n      \"projectId\": \"...\",\n      \"gitToken\": \"olp_...\"\n    },\n    \"thesis\": {\n      \"name\": \"Thesis\",\n      \"projectId\": \"...\",\n      \"gitToken\": \"olp_...\"\n    }\n  }\n}\n```\n\nPass `projectName` to a tool to select a non-default project.\n\n## Recommended agent workflow\n\n1. Use `list_files` to locate the root document and component files.\n2. Use compact `get_outline`, `find_text`, or `read_file_range` to locate the relevant content.\n3. For an outline node, request `detail: \"editable\"` with only its selected `occurrenceId`. Pass returned spans unchanged to `apply_edits` or `insert_text`.\n4. Use `append_text` with a fresh revision for end-of-file or pre-`\\end{document}` insertion.\n5. If a mutation returns `STALE_REVISION`, inspect the affected file again and build a new edit. Never reuse stale spans.\n\nSpans contain opaque offsets, a content hash, the source file, and a revision derived from the exact file content. Agents should not calculate or modify offsets. A mutation is rejected if any target file changed after inspection.\n\n## Tools\n\n### Project discovery\n\n- `list_projects` — list configured projects.\n- `list_files` — list synchronized project files, defaulting to `.tex`.\n- `status_summary` — return a compact file and document-outline summary.\n\n### Targeted inspection\n\n- `read_file_range` — read at most 400 exact, unnumbered lines and receive a reusable span.\n- `find_text` — find literal text with bounded context and match spans.\n- `get_outline` — extract headings, hierarchy, labels, source files, and line locations. It follows literal braced `\\input` and `\\include` directives by default; pass `followIncludes: false` for one file. Responses are compact by default. To obtain edit spans, call it again with `detail: \"editable\"` and up to 20 selected `occurrenceIds` from the compact response.\n\nRecursive outlines return partial results with warnings when an include is missing, dynamic, ambiguous, cyclic, inaccessible, outside the project, or beyond traversal limits. Logical headings can span several source files, so every outline node identifies its physical source. If one source file is included repeatedly, editing it changes every occurrence.\n\n### Mutations\n\n- `apply_edits` — replace one or more non-overlapping spans, across one or several files, in one commit.\n- `insert_text` — insert verbatim text immediately before or after an inspected anchor span.\n- `append_text` — append at EOF or before the single active `\\end{document}`.\n- `create_file` — create a new path and fail if it already exists.\n\nAll mutation tools synchronize first, validate before writing, and push at most one commit. No tool silently normalizes whitespace or line endings.\n\n## Examples\n\nTo revise one paragraph without reading its complete file:\n\n1. Call `find_text` with a distinctive phrase.\n2. Select the desired match and, if necessary, call `read_file_range` around its reported lines.\n3. Call `apply_edits` with the returned span and replacement text.\n\nTo inspect a split document, call `get_outline` on `main.tex`. A heading in `sections/methods.tex` reports that physical source file even when its logical parent is declared in `main.tex`. The compact result deliberately omits hashes and offsets. When editing a heading, label, or complete local section, call `get_outline` again with `detail: \"editable\"` and only its selected `occurrenceId`; this returns `headingSpan`, `labelSpan`, and `localSectionSpan` for that node.\n\nTo add material before the document terminator, first call `read_file_range` to obtain the current revision, then call `append_text` with `destination: \"before_end_document\"`.\n\n## Migration from v1\n\nVersion 2 removes the coarse and ambiguous content tools:\n\n| Removed capability | Replacement |\n|---|---|\n| Whole-file read | `read_file_range` and `find_text` |\n| Title-only section listing/read | `get_outline` plus targeted reads |\n| Whole-file overwrite | `apply_edits`, `insert_text`, or `append_text` |\n| Title-based section overwrite | Compact `get_outline`, then selected editable outline spans plus `apply_edits` |\n\nThere are no deprecated aliases. Clients discover the new tool list after restarting the MCP server.\n\n## Development\n\n```bash\nnpm test\nnpm run check\nnpm pack\n```\n\nAll MCP protocol output is written to stdout. Diagnostics are written to stderr, and credential-bearing Git URLs are masked from surfaced errors.\n\n## Security\n\n- The Overleaf Git token grants project read/write access; treat it as a password.\n- Prefer `OVERLEAF_GIT_TOKEN_FILE` where practical.\n- Never commit `projects.json` or token files.\n- Tool paths are restricted to the cloned project directory.\n- Mutations are marked destructive so supporting MCP clients can request approval.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}