olgitbridge + Overleaf MCP

This repository preserves the original Overleaf Git HTTP bridge and adds the MCP service used by the current deployment. The bridge talks to an Overleaf Community Edition or Pro instance through its web API, so it can run on a separate host.

The deployed code baseline is tagged deployed-20260801T090535Z. Site configuration, credentials, bearer tokens, project IDs, synchronized papers, runtime Git repositories, and auth-proxy state stay outside Git.

Capabilities

• Existing Git clone, pull, and push bridge on the configured Git HTTP port.
• Streamable HTTP MCP endpoint on loopback, with bearer authentication and Host/Origin checks.
• Server-side project allowlist addressed by stable projectName aliases.
• Project and file listing, bounded text reads, LaTeX section discovery, and status summaries.
• Revision-guarded file and section writes with Overleaf read-back verification.
• Per-project serialization, timeout propagation, atomic tree replacement, interrupted-sync recovery, path confinement, and credential permission checks.

The MCP backend deliberately accepts only allowlisted project aliases. Raw Overleaf project IDs and Overleaf account credentials never come from MCP callers.

Repository layout

src/core/                     Safe project, sync, credential, and Git services
src/transports/mcp-http.js    Streamable HTTP MCP transport and tool schemas
src/olops/                    Overleaf web operations
config/                       Checked-in, non-secret configuration examples
test/                         Unit and integration tests
docs/olgitbridge-mcp/         Design, implementation, and deployment notes
deploy/                       Sanitized templates matching the deployed layout

Development

Production is currently exercised with Node.js 22 and npm 10.

npm ci
npm test
npm run check

The traditional Git bridge still reads config.js. Keep the tracked file generic and apply the Overleaf URL and absolute persistent data directory only in a release copy or deployment overlay.

To enable MCP, copy config/mcp-projects.example.json outside the repository, create the referenced credential and token files with restrictive permissions, and start the service with:

OLGITBRIDGE_MCP_CONFIG=/absolute/path/mcp-projects.json \
OLGITBRIDGE_CREDENTIAL_DIR=/absolute/path/credentials \
npm start

The MCP listener must remain on a loopback address. See docs/olgitbridge-mcp/DEPLOYMENT.md and deploy/README.md before exposing it through a separate authentication proxy.

Selecting a project

Call list_projects first, then pass the returned key as projectName to all project-specific tools:

{
  "projectName": "example-paper",
  "filePath": "main.tex"
}

Write tools also require the latest revision as expectedRevision. A stale revision fails closed with REVISION_CONFLICT.

Git bridge compatibility

The Git HTTP endpoint remains compatible with the original form:

http://bridge.example.invalid/<overleaf-project-id>

The bridge performs whole-file synchronization through Overleaf's web API. Online editors may therefore report that a file changed externally after a Git or MCP write.

Upstream and license

This project derives from axkibe/olgitbridge and retains its AGPL-3.0-only license. The configured Git remote points at the maintainer's fork; publishing remains an explicit operation.