overleaf-forge 2.7.3 → 2.9.1

package/README.md

@@ -148,7 +148,7 @@ For more than one project, per-project contexts, or the SSA bootstrap, use a `pr
 npx overleaf-forge init
 ```
 
-That creates `~/.overleaf-mcp/projects.json` from the example and copies the editable templates into `~/.overleaf-mcp/templates/`. Then fill in the config:
+That creates `~/.overleaf-mcp/projects.json` from the example and copies the editable templates into `~/.overleaf-mcp/templates/`. You can fill in the settings conversationally instead of by hand: ask the assistant to set up overleaf-forge and it runs the `configure` tool (which asks where your templates, voice linter, and course folders live, then writes them). Or edit the file directly:
 
 ```json
 {
@@ -171,7 +171,7 @@ That creates `~/.overleaf-mcp/projects.json` from the example and copies the edi
 | `settings.gitToken` | Overleaf git token, used by every project (or set `OVERLEAF_GIT_TOKEN`). A per-project `gitToken` overrides it. |
 | `settings.repoDir` | Where project clones land by default (`repoDir/<name>`). A per-project `localPath` overrides it. |
 | `settings.templatesDir` | Optional. Directory of scaffold templates, overriding the bundled defaults. |
-| `settings.voiceLinter` | Optional. A prose-linter command (or set `OVERLEAF_VOICE_LINTER`) that `voice_lint` runs on a file. No default. |
+| `settings.voiceLinter` | Optional. A prose-linter command (or set `OVERLEAF_VOICE_LINTER`) that `voice_lint` runs on a file. Defaults to the bundled `examples/voice-lint.mjs`; override with your own house style. |
 | `projects.<key>.projectId` | The id from `https://www.overleaf.com/project/<ID>`. |
 | `projects.<key>.cwd` | Directory you launch the client from for this project; used to auto-detect the active project. |
 | `projects.<key>.localPath` | Explicit clone location (optional). |
@@ -251,6 +251,7 @@ By the built-in convention this parses the name, locates the parent course folde
 
 | Tool | Purpose |
 | --- | --- |
+| `configure` | Set up the global settings conversationally: call with no arguments to see what's unset and the questions to ask, then call again with the answers. Writes `projects.json`. |
 | `get_context` | Read the writing guidelines + the active project's context. Intended first call of a session. |
 | `list_projects` | List configured projects; mark which one auto-detects from the current directory. |
 | `register_project` | Add or overwrite a project entry without hand-editing JSON. |
@@ -293,7 +294,7 @@ By the built-in convention this parses the name, locates the parent course folde
 | `cite_lint` | Report undefined (`\cite` with no entry) and unused (entry never cited) citations. Read-only. |
 | `checkpoint` | Mark a local rollback point (a `mcp-snap/<label>` tag) before a risky edit. |
 | `restore` | Roll back to a checkpoint via a forward commit + push (no force, no history rewrite). |
-| `voice_lint` | Run a configured prose linter (`settings.voiceLinter`) on a `.tex`. Read-only, advisory. |
+| `voice_lint` | Run a prose linter on a `.tex` (the bundled `examples/voice-lint.mjs` by default; override via `settings.voiceLinter`). Lints the local working copy as-is, never pulls. Read-only, advisory. |
 
 ## How it works
 

package/examples/voice-lint.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Example prose linter for overleaf-forge's `voice_lint` tool.
+//
+// Contract: take a file path as the last argument, print findings to stderr,
+// exit 2 if anything was found and 0 if clean. `voice_lint` runs whatever
+// command settings.voiceLinter (or $OVERLEAF_VOICE_LINTER) points at; this
+// script is the bundled default so the tool works with no configuration.
+//
+// The checks are deliberately generic writing hygiene, chosen to rarely
+// false-positive on LaTeX. Replace them with your own house style: copy this
+// file, edit CHECKS, and point settings.voiceLinter at your copy
+// (e.g. "node /path/to/your-linter.mjs").
+import { readFileSync } from 'node:fs';
+
+const file = process.argv[2];
+if (!file) process.exit(0);
+let text;
+try { text = readFileSync(file, 'utf8'); } catch { process.exit(0); }
+
+// [regex, label]. Each is a documented, broadly-defensible prose check.
+const CHECKS = [
+  [/\b(TODO|FIXME|XXX)\b/,                              'leftover marker (TODO/FIXME/XXX)'],
+  [/\b(\w+)\s+\1\b/i,                                   'repeated word'],
+  [/\bin order to\b/i,                                  "wordy: 'in order to' -> 'to'"],
+  [/\b(very|really|quite|basically|actually) \w/i,      'filler intensifier (often cuttable)'],
+];
+
+// Skip code/verbatim environments and comment lines so source does not false-positive.
+const SKIP_BEGIN = /\\begin\{(lstlisting|verbatim|minted|Verbatim)\}/;
+const SKIP_END   = /\\end\{(lstlisting|verbatim|minted|Verbatim)\}/;
+
+const findings = [];
+let skipping = false;
+text.split(/\r?\n/).forEach((line, i) => {
+  if (SKIP_BEGIN.test(line)) { skipping = true; return; }
+  if (SKIP_END.test(line))   { skipping = false; return; }
+  if (skipping || line.trimStart().startsWith('%')) return;
+  for (const [rx, label] of CHECKS) {
+    if (rx.test(line)) findings.push(`${i + 1}: ${label}\n    > ${line.trim().slice(0, 90)}`);
+  }
+});
+
+if (findings.length) {
+  process.stderr.write(
+    `voice-lint (bundled example): ${findings.length} finding(s)\n` +
+    findings.map(f => '  ' + f).join('\n') + '\n' +
+    '(this is the generic example linter; set settings.voiceLinter for your own rules)\n',
+  );
+  process.exit(2);
+}
+process.exit(0);

package/overleaf-mcp-server.js

@@ -189,6 +189,35 @@ function resolveLocalPath(config, projectKey, project) {
   return path.join(DEFAULT_REPO_DIR, project.name || projectKey);
 }
 
+// The global settings the `configure` tool manages, each with the question to
+// ask the user when it is unset. Order is the order to ask in.
+const SETTING_HELP = {
+  repoDir:      'Where should project clones land by default? (absolute path; clones go to repoDir/<name>)',
+  academicRoot: 'Where do your course folders live? (bootstrap_ssa searches academicRoot/Year <n>/Q*/<COURSE>*)',
+  ssaSubdir:    'What subfolder name should new SSAs go under inside each course folder? (e.g. "MY SSAs")',
+  templatesDir: 'Use your own scaffold templates? Give the directory holding main.tex / context-scaffold.md (blank keeps the bundled examples).',
+  voiceLinter:  'Use your own prose linter for voice_lint? Give the command (takes a file path, exits non-zero on findings; blank keeps the bundled example).',
+  gitToken:     'Overleaf git token (prefer the OVERLEAF_GIT_TOKEN env var; set here only if you must store it in projects.json).',
+};
+const SETTING_KEYS = Object.keys(SETTING_HELP);
+const SETTING_PATHY = new Set(['repoDir', 'academicRoot', 'templatesDir']);
+
+// Merge the provided settings into the current ones, expanding a leading ~ for
+// path-like fields. Pure (homeDir injected) so it is unit-testable. Returns the
+// new settings object and the list of keys actually changed.
+export function mergeSettings(current, args, homeDir) {
+  const settings = { ...(current || {}) };
+  const provided = [];
+  for (const k of SETTING_KEYS) {
+    if (args[k] === undefined) continue;
+    let v = args[k];
+    if (typeof v === 'string' && SETTING_PATHY.has(k) && v.startsWith('~')) v = path.join(homeDir, v.slice(1));
+    settings[k] = v;
+    provided.push(k);
+  }
+  return { settings, provided };
+}
+
 // Default project resolution:
 //   1. explicit projectName argument
 //   2. project whose `cwd` is a prefix of SESSION_CWD (longest match wins)
@@ -534,8 +563,13 @@ class OverleafGitClient {
     if (!command || !command.trim()) {
       throw new Error('No voice linter configured. Set settings.voiceLinter in projects.json or the OVERLEAF_VOICE_LINTER env var (e.g. a command that takes a file path and exits non-zero on findings).');
     }
-    await this.cloneOrPull();
+    // Lint the local working copy as-is: never pulls, no network. Advisory and
+    // read-only, so it reflects on-disk state including edits not yet pushed. If
+    // the clone is absent, say so rather than silently fetching.
     const abs = path.join(this.repoPath, filePath);
+    if (!existsSync(abs)) {
+      throw new Error(`voice_lint: ${filePath} not found in the local clone (${this.repoPath}). voice_lint reads the local working copy and never pulls; open the project once (list_files / read_file) to clone it, then lint.`);
+    }
     const home = os.homedir();
     const parts = command.trim().split(/\s+/).map(t => (t.startsWith('~') ? home + t.slice(1) : t));
     const [prog, ...rest] = parts;
@@ -983,6 +1017,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'configure',
+      description: 'Set up or update overleaf-forge\'s global settings: the scaffold templates directory, the voice_lint command, and the recurring-work settings bootstrap_ssa uses (academic root, SSA subdir, default clone dir). FIRST call this with NO arguments to see the current settings and which are unset, with a question for each; ask the user those questions in turn; THEN call it again with their answers to write them to projects.json. Omit a field to leave it unchanged; pass an empty string to clear it back to the bundled default. The git token is redacted in all output. Intended right after install to configure the server conversationally.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          repoDir: { type: 'string', description: 'Default clone location; clones go to repoDir/<name>. Absolute path (a leading ~ is expanded).' },
+          academicRoot: { type: 'string', description: 'Root folder bootstrap_ssa searches: academicRoot/Year <n>/Q*/<COURSE>*. Absolute path (~ expanded).' },
+          ssaSubdir: { type: 'string', description: 'Subfolder name created under each course folder for new SSAs, e.g. "MY SSAs".' },
+          templatesDir: { type: 'string', description: 'Directory of your scaffold templates (main.tex, context-scaffold.md), overriding the bundled examples. ~ expanded. Empty string reverts to bundled.' },
+          voiceLinter: { type: 'string', description: 'Prose-linter command for voice_lint (takes a file path, exits non-zero on findings), overriding the bundled example. Empty string reverts to bundled.' },
+          gitToken: { type: 'string', description: 'Overleaf git token. Prefer the OVERLEAF_GIT_TOKEN env var; set here only to store it in projects.json.' },
+        },
+      },
+    },
     {
       name: 'register_project',
       description: 'Add or overwrite a project entry in projects.json. Lets you onboard a new Overleaf project without hand-editing JSON. Uses the global gitToken from settings. After registering, also call update_context to set the project notes.',
@@ -1194,7 +1243,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'voice_lint',
-      description: 'Lint a .tex file with a user-configured prose linter (settings.voiceLinter in projects.json, or the OVERLEAF_VOICE_LINTER env var; no default). The command receives the file path and should exit non-zero on findings. Read-only and advisory: reports output, never blocks. Useful after editing prose via edit_file/write_file, which bypass any local editor hooks.',
+      description: 'Lint a .tex file for prose issues. Runs a bundled generic example linter by default; override with settings.voiceLinter in projects.json or the OVERLEAF_VOICE_LINTER env var (a command that takes a file path and exits non-zero on findings). Lints the LOCAL working copy as-is and never pulls, so it reflects on-disk state including edits not yet pushed; if the project has not been cloned locally yet it errors rather than fetching. Read-only and advisory: reports output, never blocks. Useful after editing prose via edit_file/write_file, which bypass any local editor hooks.',
       inputSchema: {
         type: 'object',
         properties: { filePath: { type: 'string' }, projectName: { type: 'string' } },
@@ -1366,6 +1415,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text: out.join('\n') }] };
       }
 
+      case 'configure': {
+        const config = await loadConfig();
+        config.settings = config.settings || {};
+        const redact = (s) => { const r = { ...s }; if (r.gitToken) r.gitToken = '(set)'; return r; };
+        const { settings, provided } = mergeSettings(config.settings, args, os.homedir());
+
+        if (provided.length === 0) {
+          // Report mode: show current state and the questions for what is unset.
+          const unset = SETTING_KEYS.filter(k => config.settings[k] === undefined || config.settings[k] === '');
+          const lines = [
+            '# overleaf-forge configuration',
+            '',
+            'Current settings:',
+            '```json',
+            JSON.stringify(redact(config.settings), null, 2),
+            '```',
+            '',
+            unset.length
+              ? 'Not set yet. Ask the user each of these, then call configure again with their answers (omit any they want to skip):'
+              : 'All settings are set. Pass any field to update it (empty string reverts a template/linter to the bundled default).',
+            ...unset.map((k, i) => `${i + 1}. **${k}** — ${SETTING_HELP[k]}`),
+          ];
+          return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+
+        // Apply mode: persist the provided settings.
+        config.settings = settings;
+        await saveConfig(config);
+        return { content: [{ type: 'text', text: `Updated: ${provided.join(', ')}.\n\`\`\`json\n${JSON.stringify(redact(config.settings), null, 2)}\n\`\`\`\nTakes effect on the next call (projects.json is re-read each time).` }] };
+      }
+
       case 'register_project': {
         const config = await loadConfig();
         if (!args.key || !args.projectId) throw new Error('key and projectId are required');
@@ -1577,7 +1657,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'voice_lint': {
         const config = await loadConfig();
         const { client } = await getClient(args.projectName);
-        const command = config.settings?.voiceLinter || process.env.OVERLEAF_VOICE_LINTER;
+        // settings.voiceLinter / $OVERLEAF_VOICE_LINTER override the bundled
+        // example linter, which ships with the package so voice_lint works out
+        // of the box. The example implements generic prose checks; point the
+        // setting at your own command to enforce a house style.
+        const command = config.settings?.voiceLinter
+          || process.env.OVERLEAF_VOICE_LINTER
+          || `node ${path.join(PACKAGE_DIR, 'examples', 'voice-lint.mjs')}`;
         const r = await client.voiceLint(args.filePath, { command });
         return { content: [{ type: 'text', text: r.clean ? `✓ voice OK — ${args.filePath}${r.findings ? `\n${r.findings}` : ''}` : `voice findings in ${args.filePath}:\n${r.findings}` }] };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overleaf-forge",
-  "version": "2.7.3",
+  "version": "2.9.1",
   "description": "MCP server to read, edit, compile, and verify Overleaf/LaTeX projects over git: conflict-safe edits, figure upload, clean-build verification, citation and voice linting.",
   "type": "module",
   "main": "overleaf-mcp-server.js",
@@ -10,6 +10,7 @@
   "files": [
     "overleaf-mcp-server.js",
     "templates/",
+    "examples/",
     "writing-guidelines.md",
     "projects.example.json"
   ],

package/templates/main.tex

@@ -1,135 +1,30 @@
-%% ----- Document Class -----
+%% Example document template for overleaf-forge's bootstrap_ssa scaffold.
+%%
+%% The tokens __SSA_TITLE__, __SSA_DATE__, and __OVERLEAF_READ_URL__ are
+%% substituted at scaffold time; \author is rewritten when an author is passed.
+%% This is a deliberately plain starting point. Replace it with your own house
+%% style and point settings.templatesDir (or $OVERLEAF_MCP_TEMPLATES) at your copy.
+%% The chapter/appendix/refs layout below matches what reset_ssa_content expects
+%% (Chapters/ch*.tex, Chapters/app_*.tex, refs.bib, figures/).
 \documentclass[a4paper]{article}
 
-%% ----- Font -----
 \usepackage[T1]{fontenc}
-\usepackage[RMstyle=Light,SSstyle=Text,TTstyle=Light,DefaultFeatures={Ligatures=Common}]{plex-otf}
-\renewcommand*\familydefault{\sfdefault}
-
-\usepackage[basic,italic,symbolgreek]{mathastext}
-
-\makeatletter
-\@for\@tempa:=a,b,c,d,e,h,i,k,l,m,n,o,q,r,s,t,u,v,w,x\do{%
-\MTsetmathskips{\@tempa}{0.5mu}{0.5mu}}%
-\makeatother
-
-\MTsetmathskips{f}{2.5mu}{0.5mu}
-\MTsetmathskips{g}{1.5mu}{0.5mu}
-\MTsetmathskips{j}{2.5mu}{0.5mu}
-\MTsetmathskips{p}{1.5mu}{0mu}
-\MTsetmathskips{y}{1.5mu}{0.5mu}
-\MTsetmathskips{z}{1mu}{0.5mu}
-
-%% ----- Basics -----
+\usepackage[margin=1in]{geometry}
 \usepackage{graphicx}
 \graphicspath{{figures/}}
 \usepackage{hyperref}
-\usepackage{subcaption}
 \usepackage{xurl}
-\usepackage{multicol}
-\usepackage{parskip}
-\usepackage{longtable}
+\usepackage{amsmath}
 \usepackage{siunitx}
-\sisetup{mode=text}   %% prevents mathastext/siunitx conflict (\mathrm undefined in XeTeX)
-\usepackage{xcolor}
-\usepackage[margin=1in]{geometry}
-\usepackage{minted}
-\usemintedstyle{fruity}
-\usepackage{listings}
-\usepackage{enumitem}
-\usepackage{wrapfig}
-\usepackage{ragged2e}
-\usepackage{array}
-\usepackage{hhline}
-\usepackage{colortbl}
-\usepackage{marginnote}
-\usepackage{emoji}
-\usepackage{tocloft}
-\usepackage{tcolorbox}
-\tcbuselibrary{skins,breakable}
-\usepackage{titlesec}
-\usepackage{titling}
 \usepackage{booktabs}
-\usepackage{tikz}
-\usetikzlibrary{positioning, calc, arrows.meta}
-\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}}
-\newcolumntype{R}[1]{>{\raggedleft\arraybackslash}p{#1}}
-\usepackage{pdflscape}
-\usepackage{everypage}
-\newcommand{\Lpagenumber}{%
-  \ifdim\textwidth=\linewidth\else\bgroup
-    \dimendef\margin=0
-    \ifodd\value{page}\margin=\oddsidemargin
-    \else\margin=\evensidemargin\fi
-    \raisebox{\dimexpr-\topmargin-\headheight-\headsep-0.5\linewidth}[0pt][0pt]{%
-      \rlap{\hspace{\dimexpr\margin+\textheight+\footskip}%
-      \llap{\rotatebox{90}{\thepage}}}}%
-  \egroup\fi}
-\AddEverypageHook{\Lpagenumber}
+\usepackage{longtable}
+\usepackage{listings}
 \usepackage[backend=biber,style=ieee,sorting=none]{biblatex}
 \addbibresource{refs.bib}
 
-%% ----- Equation annotations -----
-\usepackage{annotate-equations}
-
-%% ----- Body text color -----
-\let\originalnormalfont\normalfont
-\renewcommand{\normalfont}{\originalnormalfont\color{black!60}}
-
-%% ----- Headings locked to full black -----
-\titleformat{\section}{\normalfont\Large\bfseries\color{black}}{\thesection}{1em}{}
-\titleformat{\subsection}{\normalfont\large\bfseries\color{black}}{\thesubsection}{1em}{}
-\titleformat{\subsubsection}{\normalfont\normalsize\bfseries\color{black}}{\thesubsubsection}{1em}{}
-
-%% ----- Title block locked to full black -----
-\pretitle{\begin{center}\color{black}\Large\bfseries}
-\posttitle{\end{center}}
-\preauthor{\begin{center}\color{black}\normalsize}
-\postauthor{\end{center}}
-\predate{\begin{center}\color{black}\normalsize}
-\postdate{\end{center}}
-\titleformat{\paragraph}[hang]{\normalfont\normalsize\bfseries\color{black}}{\theparagraph}{1em}{}
-\titlespacing*{\paragraph}{0pt}{2ex plus 0.5ex minus 0.2ex}{0.5em}
-
-%% ----- For Code -----
-\definecolor{codegreen}{rgb}{0,0.6,0}
-\definecolor{codegray}{rgb}{0.5,0.5,0.5}
-\definecolor{codepurple}{rgb}{0.58,0,0.82}
-\definecolor{backcolour}{rgb}{0.95,0.95,0.92}
-\lstdefinestyle{mystyle}{
-    backgroundcolor=\color{backcolour},
-    commentstyle=\color{codegreen},
-    keywordstyle=\color{magenta},
-    numberstyle=\tiny\color{codegray},
-    stringstyle=\color{codepurple},
-    basicstyle=\ttfamily\footnotesize,
-    breakatwhitespace=false,
-    breaklines=true,
-    captionpos=b,
-    keepspaces=true,
-    numbers=left,
-    numbersep=5pt,
-    showspaces=false,
-    showstringspaces=false,
-    showtabs=false,
-    tabsize=2
-}
-\lstset{style=mystyle}
-\allowdisplaybreaks
-
-%% ----- ToC settings -----
-\renewcommand{\cftsecdotsep}{\cftdotsep}
-\renewcommand{\contentsname}{}
-\renewcommand{\cftdot}{ -. }
-\renewcommand{\cftsecfont}{\color{black}}
-\renewcommand{\cftsubsecfont}{\color{black}}
-\renewcommand{\cftsecpagefont}{\color{black}}
-\renewcommand{\cftsubsecpagefont}{\color{black}}
-
-%% ----- Title Page Data -----
 \title{\textbf{__SSA_TITLE__}}
-\author{\textbf{Written and submitted by Your Name}}
-\date{\textbf{__SSA_DATE__}}
+\author{Your Name}
+\date{__SSA_DATE__}
 
 \begin{document}
 \maketitle
@@ -137,23 +32,10 @@
     \url{__OVERLEAF_READ_URL__}
 \end{center}
 
-\input{Chapters/ch1}
+\tableofcontents
+\clearpage
 
-\vspace{1em}
-\begin{tcolorbox}[
-  arc=0pt,
-  colback=white,
-  colframe=gray,
-  colbacktitle=gray,
-  coltitle=white,
-  title=DETAILS,
-  boxrule=0.5pt,
-  fonttitle=\bfseries\large,
-  breakable
-]
-\vspace{-3em}
-  \tableofcontents
-\end{tcolorbox}
+\input{Chapters/ch1}
 
 \clearpage
 \input{Chapters/ch2}
@@ -165,5 +47,4 @@
 \clearpage
 \input{Chapters/app_A}
 
-
 \end{document}