# 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

```text
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.

```bash
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:

```bash
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`](docs/olgitbridge-mcp/DEPLOYMENT.md) and
[`deploy/README.md`](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:

```json
{
  "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:

```text
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`](https://gitlab.com/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.