feat: 3 new tools + remote compile + bug fixes (26 tools, 173 tests)

Completeness:
- latex_flatten — inline \input/\include/\subfile into one .tex (arXiv/export).
- overleaf_diff — unified diff of the working copy vs HEAD or between refs.
- latex_compile_plan — dry-run the compile routing decision.
- latex_compile now falls back to remote compile (CLSI, else the experimental
  Overleaf session) when no local TeX engine is installed.

Polish (adversarial pass):
- refcheck now handles starred (\ref*) and cleveref (\cref/\crefrange/...) forms.
- redact: scrub secrets embedded in string log args (URL userinfo, token/cookie
  query params) — defence in depth so a token can never leak via a raw log string.
- dedup engine-selection (capabilities reuses the compiler's selectEngine) and
  the git clone path; +71 tests.

Author: oscardvs

README.md

@@ -75,16 +75,17 @@ Other Overleaf MCP servers stop at one trick — read-only Git, or local-only co
 | Create a **new** project from generated LaTeX (no auth) | ✅ | ❌ | ❌ | copy-paste |
 | Works for **free-tier** Overleaf users | ✅ (experimental) | ❌ | local only | ✅ (you) |
 | Self-host free · Open-source (MIT) | ✅ | varies | varies | n/a |
-| 23 agent-first tools, one `npx` | ✅ | partial | partial | n/a |
+| 26 agent-first tools, one `npx` | ✅ | partial | partial | n/a |
 
 ## What you can do
 
 - **Ship a paper without leaving the chat.** *"Pull my thesis, fix the undefined references in chapter 3, recompile, and push."* — vibeTeX pulls over the Git bridge, edits the files, runs `latexmk`, and pushes the commit back to Overleaf.
 - **Compile and read the log.** `latex_compile` builds the PDF; `latex_log` returns the **parsed** errors and warnings (file, line, message) so your AI can actually fix the build — not guess.
 - **Catch problems before submission.** `latex_check_refs` finds undefined `\ref`/`\cite` and duplicate labels; `latex_lint` flags common LaTeX smells; `latex_outline` gives the document structure; `latex_word_count` counts real words (not markup).
 - **Draft, then hand off.** Generate fresh LaTeX and `overleaf_create_project` opens it as a **new** Overleaf project via the official "Open in Overleaf" flow — no token required.
-- **Inspect history and diffs.** `overleaf_history` and `overleaf_status` show what changed, so a review loop stays grounded in the real repository.
-- **Built for agents.** 23 consolidated, well-described `overleaf_*` / `latex_*` tools with structured output, namespaced and discoverable via `overleaf_whoami` and `latex_search_tools`.
+- **Inspect history and diffs.** `overleaf_history`, `overleaf_status`, and `overleaf_diff` show exactly what changed, so a review loop stays grounded in the real repository.
+- **Flatten for submission.** `latex_flatten` inlines every `\input`/`\include`/`\subfile` into one self-contained `.tex` — ready for arXiv or a single-file export.
+- **Built for agents.** 26 consolidated, well-described `overleaf_*` / `latex_*` tools with structured output, namespaced and discoverable via `overleaf_whoami` and `latex_search_tools`.
 
 ## The four capability tiers
 
@@ -129,15 +130,15 @@ Hosting a shared/remote instance (OAuth, rate limits, metrics)? See [`.env.examp
 
 ## Tools reference
 
-23 tools, namespaced `overleaf_*` (project + sync) and `latex_*` (compile + quality). Discover them at runtime with `latex_search_tools`.
+26 tools, namespaced `overleaf_*` (project + sync) and `latex_*` (compile + quality). Discover them at runtime with `latex_search_tools`.
 
 **Discovery** — `overleaf_whoami` · `latex_search_tools`
 
-**Project sync (Git bridge / session)** — `overleaf_list_projects` · `overleaf_pull` · `overleaf_status` · `overleaf_push` · `overleaf_history` · `overleaf_list_files` · `overleaf_read_file` · `overleaf_write_file` · `overleaf_edit_file` · `overleaf_delete_file` · `overleaf_create_project` · `overleaf_download_zip`
+**Project sync (Git bridge / session)** — `overleaf_list_projects` · `overleaf_pull` · `overleaf_status` · `overleaf_push` · `overleaf_diff` · `overleaf_history` · `overleaf_list_files` · `overleaf_read_file` · `overleaf_write_file` · `overleaf_edit_file` · `overleaf_delete_file` · `overleaf_create_project` · `overleaf_download_zip`
 
-**Compile** — `latex_compile` · `latex_log` · `latex_get_pdf`
+**Compile (local / CLSI / session)** — `latex_compile` · `latex_compile_plan` · `latex_log` · `latex_get_pdf`
 
-**Quality** — `latex_outline` · `latex_check_refs` · `latex_lint` · `latex_format` · `latex_word_count` · `latex_bib`
+**Quality** — `latex_outline` · `latex_check_refs` · `latex_lint` · `latex_format` · `latex_word_count` · `latex_bib` · `latex_flatten`
 
 ## Documentation
 

src/api/git-bridge.ts

@@ -68,6 +68,40 @@ export interface PushResult {
   committed: string[];
 }
 
+/** Options for {@link GitBridgeClient.diff}. */
+export interface DiffOptions {
+  /** Base ref (commit/branch/tag). With `to` set, diffs `from..to`; alone, diffs `from` vs worktree. */
+  from?: string;
+  /** Target ref. Requires `from`; diffs `from..to`. */
+  to?: string;
+  /** Scope the diff to a single project-relative path (file or directory). */
+  path?: string;
+}
+
+/** Per-file change summary in a {@link DiffResult}. */
+export interface DiffFile {
+  path: string;
+  /** Lines added (insertions) in this file; undefined for binary files. */
+  added?: number;
+  /** Lines removed (deletions) in this file; undefined for binary files. */
+  removed?: number;
+  /** True when git reports the file as binary (no line-level diff). */
+  binary: boolean;
+}
+
+/** Result of a `git diff` over the working copy. */
+export interface DiffResult {
+  /** The unified-diff text (empty when there are no changes). */
+  patch: string;
+  /** Per-file insertion/deletion summary. */
+  files: DiffFile[];
+  /** Total insertions / deletions across all files. */
+  added: number;
+  removed: number;
+  /** Human-readable description of what was compared (e.g. "working copy vs HEAD"). */
+  range: string;
+}
+
 /** A slice of file content read from the working copy. */
 export interface FileContent {
   path: string;
@@ -273,33 +307,35 @@ export class GitBridgeClient {
     }
   }
 
+  /**
+   * Clone `project` into its workdir. LOCK-FREE: callers must already hold the per-project lock
+   * (re-acquiring our Semaphore(1) would self-deadlock). Shared by ensureClone + pull.
+   */
+  private async cloneInto(project: ResolvedProject): Promise<PullResult> {
+    await mkdir(dirname(project.workdir), { recursive: true });
+    // `git clone <url> <dir>` creates <dir> exactly.
+    await this.git(['clone', project.gitUrl, project.workdir], { authed: true });
+    const head = await this.headHash(project.workdir);
+    this.logger.info(`Cloned Overleaf project ${project.id} → ${project.workdir} @ ${head}`);
+    return { cloned: true, head, changed: [], workdir: project.workdir };
+  }
+
   /** Clone the project if absent, else leave the working copy untouched. Returns its workdir/head. */
   ensureClone(project: ResolvedProject): Promise<PullResult> {
     return this.lockFor(project.workdir).run(async () => {
       if (this.isCloned(project.workdir)) {
         const head = await this.headHash(project.workdir);
         return { cloned: false, head, changed: [], workdir: project.workdir };
       }
-      await mkdir(dirname(project.workdir), { recursive: true });
-      // Clone into the exact workdir. `git clone <url> <dir>` creates <dir>.
-      await this.git(['clone', project.gitUrl, project.workdir], { authed: true });
-      const head = await this.headHash(project.workdir);
-      this.logger.info(`Cloned Overleaf project ${project.id} → ${project.workdir} @ ${head}`);
-      return { cloned: true, head, changed: [], workdir: project.workdir };
+      return this.cloneInto(project);
     });
   }
 
   /** Fetch + fast-forward the working copy from Overleaf. */
   pull(project: ResolvedProject): Promise<PullResult> {
     return this.lockFor(project.workdir).run(async () => {
       if (!this.isCloned(project.workdir)) {
-        // Defer to ensureClone's own locking-free internals: replicate inline to avoid a
-        // nested lock acquisition (Semaphore(1) would deadlock on re-entry).
-        await mkdir(dirname(project.workdir), { recursive: true });
-        await this.git(['clone', project.gitUrl, project.workdir], { authed: true });
-        const head = await this.headHash(project.workdir);
-        this.logger.info(`Cloned Overleaf project ${project.id} → ${project.workdir} @ ${head}`);
-        return { cloned: true, head, changed: [], workdir: project.workdir };
+        return this.cloneInto(project);
       }
       const before = await this.headHash(project.workdir);
       await this.git(['pull', '--ff-only'], { cwd: project.workdir, authed: true });
@@ -385,6 +421,71 @@ export class GitBridgeClient {
     });
   }
 
+  /**
+   * `git diff` over the working copy. By default diffs the working copy (including staged +
+   * unstaged changes) against HEAD — i.e. exactly what overleaf_push would commit. Pass
+   * `opts.from`/`opts.to` to diff between two refs (`from..to`), or `opts.from` alone to diff a
+   * ref against the current worktree. Scope to one file/dir with `opts.path`. Returns the unified
+   * patch plus a per-file insertion/deletion summary. Read-only; runs on the local clone only
+   * (no token, no network), so it is safe to call freely.
+   */
+  diff(project: ResolvedProject, opts: DiffOptions = {}): Promise<DiffResult> {
+    return this.lockFor(project.workdir).run(async () => {
+      if (!this.isCloned(project.workdir)) {
+        throw new OverleafError({
+          status: 400,
+          message:
+            'Cannot diff: project not pulled yet. Run overleaf_pull first to populate the working copy.',
+        });
+      }
+      // Build the revision selector. `from..to` for two refs; `from` alone diffs that ref vs the
+      // worktree; nothing → working copy (HEAD + index + worktree) vs HEAD. `--` separates a
+      // path from refs so a filename can never be mistaken for a ref.
+      const refArgs: string[] = [];
+      let range: string;
+      if (opts.from && opts.to) {
+        refArgs.push(`${opts.from}..${opts.to}`);
+        range = `${opts.from}..${opts.to}`;
+      } else if (opts.from) {
+        refArgs.push(opts.from);
+        range = `${opts.from} vs working copy`;
+      } else {
+        // Compare HEAD against the working tree, INCLUDING untracked-but-staged changes. We add
+        // -A-staged content into the diff by diffing HEAD (covers both staged and unstaged).
+        refArgs.push('HEAD');
+        range = 'working copy vs HEAD';
+      }
+      const pathArgs = opts.path ? ['--', opts.path] : [];
+
+      const { stdout: patch } = await this.git(['diff', ...refArgs, ...pathArgs], {
+        cwd: project.workdir,
+      });
+      const { stdout: numstat } = await this.git(['diff', '--numstat', ...refArgs, ...pathArgs], {
+        cwd: project.workdir,
+      });
+
+      const files: DiffFile[] = [];
+      let added = 0;
+      let removed = 0;
+      for (const line of numstat.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        // numstat: `<added>\t<removed>\t<path>`; `-`/`-` marks a binary file.
+        const [a = '', r = '', ...rest] = trimmed.split('\t');
+        const path = rest.join('\t');
+        if (!path) continue;
+        const binary = a === '-' || r === '-';
+        const addedN = binary ? undefined : Number(a) || 0;
+        const removedN = binary ? undefined : Number(r) || 0;
+        if (addedN) added += addedN;
+        if (removedN) removed += removedN;
+        files.push({ path, added: addedN, removed: removedN, binary });
+      }
+
+      return { patch, files, added, removed, range };
+    });
+  }
+
   /** Recent commit log (newest first), capped at `limit`. */
   log(project: ResolvedProject, limit?: number): Promise<CommitInfo[]> {
     return this.lockFor(project.workdir).run(async () => {

src/api/session-client.ts

@@ -216,6 +216,23 @@ export class SessionClient {
     };
   }
 
+  /**
+   * Download one compile output artifact (the produced PDF or log) as raw bytes, authenticated
+   * with the session cookie. Exposed (non-breaking) so the CompileService can persist remote
+   * artifacts to disk and return a path rather than streaming bytes into chat. Best-effort —
+   * part of the experimental, unofficial session tier.
+   */
+  async fetchOutput(url: string): Promise<Buffer> {
+    this.assertEnabled();
+    const res = await this.deps.fetcher.fetch(url, {
+      method: 'GET',
+      headers: { cookie: this.cookieHeader() },
+      redirect: 'manual',
+    });
+    if (!res.ok) await this.raise(res, `fetch compile output ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+
   /** Throw a clear error if the experimental session tier is not enabled / configured. */
   private assertEnabled(): void {
     if (!this.deps.config.experimentalSession || !this.deps.config.sessionCookie) {

src/auth/consent.ts

@@ -36,7 +36,12 @@ export interface ConsentPageOptions {
 }
 
 /** Minimal self-contained HTML consent/passcode page; posts to ./consent. */
-export function renderConsentPage({ authId, clientName, redirectHost, error }: ConsentPageOptions): string {
+export function renderConsentPage({
+  authId,
+  clientName,
+  redirectHost,
+  error,
+}: ConsentPageOptions): string {
   const name = esc(sanitizeDisplay(clientName));
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8" />

src/auth/provider.ts

@@ -1,6 +1,9 @@
 import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto';
 import type { Response } from 'express';
-import type { OAuthServerProvider, AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+import type {
+  OAuthServerProvider,
+  AuthorizationParams,
+} from '@modelcontextprotocol/sdk/server/auth/provider.js';
 import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
 import { redirectUriMatches } from '@modelcontextprotocol/sdk/server/auth/handlers/authorize.js';
 import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
@@ -9,7 +12,10 @@ import type {
   OAuthTokens,
   OAuthTokenRevocationRequest,
 } from '@modelcontextprotocol/sdk/shared/auth.js';
-import { InvalidGrantError, InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import {
+  InvalidGrantError,
+  InvalidTokenError,
+} from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import { renderConsentPage } from './consent.js';
 import { MemoryStore, type OAuthStore, type StoredAccess, type StoredRefresh } from './store.js';
 
@@ -79,7 +85,8 @@ export class VibetexOAuthProvider implements OAuthServerProvider {
 
   constructor(private readonly opts: VibetexOAuthProviderOptions) {
     this.store = opts.store ?? new MemoryStore();
-    if (opts.mode === 'passcode' && !opts.passcode) throw new Error('passcode mode requires a passcode');
+    if (opts.mode === 'passcode' && !opts.passcode)
+      throw new Error('passcode mode requires a passcode');
   }
 
   readonly clientsStore: OAuthRegisteredClientsStore = {
@@ -99,7 +106,11 @@ export class VibetexOAuthProvider implements OAuthServerProvider {
     },
   };
 
-  async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void> {
+  async authorize(
+    client: OAuthClientInformationFull,
+    params: AuthorizationParams,
+    res: Response,
+  ): Promise<void> {
     this.sweep();
     const authId = randomUUID();
     this.pending.set(authId, {
@@ -126,18 +137,39 @@ export class VibetexOAuthProvider implements OAuthServerProvider {
     const pc = this.pending.get(authId);
     if (!pc || pc.expiresAt < Date.now()) {
       this.pending.delete(authId);
-      this.sendConsent(res, 400, authId, 'this client', '', 'Session expired — please reconnect from the client.');
+      this.sendConsent(
+        res,
+        400,
+        authId,
+        'this client',
+        '',
+        'Session expired — please reconnect from the client.',
+      );
       return;
     }
     if (!timingSafeEqualStr(passcode, this.opts.passcode ?? '')) {
       pc.attempts += 1;
       this.opts.onEvent?.('auth_failed');
       if (pc.attempts >= MAX_CONSENT_ATTEMPTS) {
         this.pending.delete(authId);
-        this.sendConsent(res, 429, authId, pc.clientName, hostOf(pc.redirectUri), 'Too many attempts — please reconnect from the client.');
+        this.sendConsent(
+          res,
+          429,
+          authId,
+          pc.clientName,
+          hostOf(pc.redirectUri),
+          'Too many attempts — please reconnect from the client.',
+        );
         return;
       }
-      this.sendConsent(res, 401, authId, pc.clientName, hostOf(pc.redirectUri), 'Incorrect passcode. Please try again.');
+      this.sendConsent(
+        res,
+        401,
+        authId,
+        pc.clientName,
+        hostOf(pc.redirectUri),
+        'Incorrect passcode. Please try again.',
+      );
       return;
     }
     this.pending.delete(authId);
@@ -166,7 +198,10 @@ export class VibetexOAuthProvider implements OAuthServerProvider {
     res.redirect(302, target.href);
   }
 
-  async challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+  async challengeForAuthorizationCode(
+    client: OAuthClientInformationFull,
+    authorizationCode: string,
+  ): Promise<string> {
     const c = this.codes.get(authorizationCode);
     if (!c || c.clientId !== client.client_id || c.expiresAt < Date.now()) {
       throw new InvalidGrantError('Invalid or expired authorization code');
@@ -224,7 +259,10 @@ export class VibetexOAuthProvider implements OAuthServerProvider {
     };
   }
 
-  async revokeToken(_client: OAuthClientInformationFull, request: OAuthTokenRevocationRequest): Promise<void> {
+  async revokeToken(
+    _client: OAuthClientInformationFull,
+    request: OAuthTokenRevocationRequest,
+  ): Promise<void> {
     this.store.deleteAccess(request.token);
     this.store.deleteRefresh(request.token);
     void this.store.flush();
@@ -268,7 +306,9 @@ export class VibetexOAuthProvider implements OAuthServerProvider {
   ): void {
     res.setHeader('Content-Type', 'text/html; charset=utf-8');
     res.setHeader('Cache-Control', 'no-store');
-    res.status(status).send(renderConsentPage({ authId, clientName, redirectHost: hostOf(redirectUri), error }));
+    res
+      .status(status)
+      .send(renderConsentPage({ authId, clientName, redirectHost: hostOf(redirectUri), error }));
   }
 
   /** Drop expired pending consents and codes; sweep expired tokens in the store. */