tex-mcp-web 0.8.2__py3-none-any.whl

tex_mcp_web/__init__.py

@@ -0,0 +1,3 @@
+"""tex-mcp-web — agentic-first review tool for LaTeX papers."""
+
+__version__ = "0.8.2"

tex_mcp_web/agent/init.md

@@ -0,0 +1,104 @@
+# Set up a folder for tex review
+
+The user said "do tex init", or `listen` found no config. Set up review for the current MCP
+session. Read setup paths from `setup_info()`, not from the shell's current directory. Its
+startup directory is where the config goes. Configuration discovery searches that directory
+and its parents, never its subfolders. The discovered config and an existing binding may
+differ. A successful binding is retained until the MCP process is restarted.
+
+Resolve `dir` relative to the config's directory, and `main` relative to `dir`, or to the
+config's directory when `dir` is unset. Init creates the config, not the paper. Confirm only
+choices the user has not already authorized. For an explicitly requested setup for another
+session, use that session's intended startup directory and report separately whether its
+connection has been verified.
+
+## 1. Inspect (write nothing)
+
+- Call `setup_info()` before connecting or writing, and read its startup directory,
+  discovered config, and existing binding.
+- Run `tex-mcp-web config` without arguments from the startup directory and inspect the
+  selected path and values. If the config serves the intended project, reuse it and edit only
+  the settings the request requires. If a parent config serves another project, leave it
+  unchanged and propose a new config in the startup directory. If a config already exists in
+  the startup directory, edit that file rather than replacing it with init. A missing main
+  file alone does not establish that a config belongs to another project.
+- Main file: `grep -l '\\documentclass' *.tex` in the paper's folder. One hit is the proposal.
+  Several are asked. No hit in the startup directory: ask where the paper is, and that folder
+  becomes `dir`.
+- Port: the first free one from 8765 (`ss -ltn`, or `lsof -iTCP -sTCP:LISTEN -P -n` on macOS), also skipping the port in a
+  `.html-mcp-web.yaml` in this folder, since both tools default to 8765.
+- Compiler: `command -v latexmk`. Missing: tell the user, and do not install a TeX distribution.
+- References: a folder the user names that holds the papers theirs builds on, converted to
+  Markdown. Unnamed: leave it unset.
+- Guideline: `setup_info()` lists the user's guidelines folder, with its absolute path and
+  entries. Mark an entry without GUIDELINE.md, which cannot be chosen. None is the default.
+- Page token: off is the default. Every account on a machine can reach the page's port, so on
+  a machine other people log in to, such as a lab server, the page token keeps them out.
+
+## 2. Confirm
+
+Show one summary, in the user's language, like:
+
+    config   : <startup directory>/.tex-mcp-web.yaml
+    dir      : paper2  (the paper's folder, relative to the config)
+    main     : main.tex  (in dir, the only file with \documentclass)
+    port     : 8765
+    watch    : *.tex *.bib -> 9 files (main.tex, sections/*.tex, refs.bib)
+    ignore   : *_backup.tex
+    compiler : auto (latexmk)
+    references : ../related  (the reference papers in Markdown, relative to the config)
+    guideline : my-field  (writing rules the agent reads before editing)
+    page token : off  (on: the page opens only from its link, for a machine others log in to)
+
+Leave out `dir` when the paper is in the startup directory, `references` when the user named
+no folder, and `guideline` when the user has none. Under guideline, list the user's
+guidelines and none, each with one line on what it is for, read from its first lines, with
+none as the default. Under page token, ask whether other people can log in to this machine:
+on, the page opens only from a link with a token only this account can read, once per
+browser, after which its plain address works as a bookmark there. Off, the plain address
+opens it for anyone on the machine, as it does on a computer of one's own. Ask once. A choice
+the user has already approved is not asked again.
+
+## 3. Write
+
+Run init and subsequent config commands with the MCP startup directory as their working
+directory, with the command that `listen()`'s missing-config error names. Changing the shell's
+working directory does not retarget this MCP process.
+
+    tex-mcp-web --port <port> init --main <file>
+    tex-mcp-web config <dir|compiler|watch|ignore|references|guideline|page_token> <value>   # only for changed fields
+
+Continue only if init succeeds and the expected local config exists. Before changing any
+setting, run `tex-mcp-web config` without arguments and confirm that it selects the intended
+file. Stop if it selects another file. Inspect the resulting values after the changes.
+
+In this setup, use `init --force` only after confirming that the existing config is in a
+parent directory and creating a local config is authorized. It creates the local config
+without changing the parent. Do not use it to replace an existing local config.
+
+## 4. Verify
+
+Before reporting completion, confirm that configuration discovery selects the intended file,
+`dir` resolves to the intended paper directory, and `main` resolves to an existing paper file.
+
+Then check the current connection without a build. Call `guide()`, which connects this session
+to its project, read every file in its read list in full, and then call `setup_info()`. Its
+`bound_config_path` must be the intended config. A review server is shared only by the same config file, so this is the config the
+review page serves. If it is bound to another config, restart the MCP server process through
+the client and check again. A successful init or CLI config check alone does not establish
+this.
+
+Report setup as complete only after both the files and the current connection have been
+verified. Otherwise report what was prepared and what remains unverified.
+
+## 5. Tell the user
+
+Report setup as ready only after the current MCP connection passes the check. If restarting
+the MCP process remains necessary, say that the files are prepared but this session is not
+ready yet, and state the remaining action. Saying "do tex listen" starts the review page. With
+the page token on, give the user the link `tex-mcp-web link` prints in the paper's folder, to
+open once in each browser.
+To follow an Overleaf project, the user presses Connect Overleaf in the page's top bar (in
+the ⋯ menu on a phone) and follows what it asks. Tell them so in one line.
+With the plugin, Claude Code started in the folder later listens on its own. Start listening
+only when the user asks for it.

tex_mcp_web/cli.py

@@ -0,0 +1,361 @@
+"""tex-mcp-web command-line interface.
+
+Subcommands:
+    serve      run the viewer server on its own (default if no subcommand)
+    link       print the page's address, with its token when page_token is on
+    init       scaffold .tex-mcp-web.yaml
+    config     get/set values in .tex-mcp-web.yaml
+    compile    one-shot compile, print structured errors
+    goto       scroll a running viewer
+    mcp        run the MCP server (stdio transport) and serve the viewer
+
+Comment management lives in the browser (for humans) and the MCP tools
+(for the agent).  The CLI deliberately does not expose comment commands
+because nobody types ``tex-mcp-web comment add ...`` from a shell.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from pathlib import Path
+
+from .config import DEFAULT_PORT, create_config, find_config, load_config
+from . import __version__
+
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+
+def _configure_logging(verbose: bool) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(name)s — %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+# ---------------------------------------------------------------------------
+# serve
+# ---------------------------------------------------------------------------
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    from .server import run as run_server
+
+    cfg = load_config(main_file=getattr(args, "main", None))
+    port = args.port or cfg.port
+    print(
+        f"tex-mcp-web v{__version__}  serving {cfg.main} at http://127.0.0.1:{port}"
+        + ("  (open it from the link `tex-mcp-web link` prints)" if cfg.page_token else ""),
+        file=sys.stderr,
+    )
+    run_server(cfg, port=port)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# link
+# ---------------------------------------------------------------------------
+
+
+def cmd_link(args: argparse.Namespace) -> int:
+    """The page's address, to open or bookmark: with page_token on, the link with the token,
+    which a browser opens once and then keeps."""
+    from .page_token import link
+
+    cfg = load_config()
+    print(link(args.port or cfg.port, cfg.page_token))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    existing = find_config()
+    if existing and not args.force:
+        # init writes here. A config found higher up is left alone by --force.
+        if existing.parent.resolve() == Path.cwd().resolve():
+            print(f"Config already exists here: {existing}", file=sys.stderr)
+            print("--force overwrites it.", file=sys.stderr)
+        else:
+            print(f"Config found in a parent folder: {existing}", file=sys.stderr)
+            print("--force writes a new config here, which takes precedence for this folder. "
+                  "The parent is not changed.", file=sys.stderr)
+        return 1
+    path = create_config(main=args.main, port=args.port or DEFAULT_PORT)
+    print(f"Wrote {path}", file=sys.stderr)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# config
+# ---------------------------------------------------------------------------
+
+
+_CONFIG_KEYS = ("main", "dir", "port", "compiler", "watch", "ignore", "references", "guideline", "page_token")
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    import yaml
+
+    from .config import DEFAULT_CONFIG_NAME
+
+    path = find_config()
+    if path is None:
+        print(f"No {DEFAULT_CONFIG_NAME} found. `tex-mcp-web init` writes one here, "
+              "and `tex-mcp-web config dir <folder>` then names the paper's folder anywhere.", file=sys.stderr)
+        return 1
+    with open(path) as f:
+        data = yaml.safe_load(f) or {}
+
+    if args.key is None:
+        print(f"# {path}")
+        print(yaml.dump(data, default_flow_style=False, sort_keys=False), end="")
+        return 0
+
+    if args.key not in _CONFIG_KEYS:
+        print(f"unknown key {args.key!r}; one of: {', '.join(_CONFIG_KEYS)}", file=sys.stderr)
+        return 1
+
+    if args.value is None:
+        if args.key not in data:
+            print(f"{args.key} is not set in {path}", file=sys.stderr)
+            return 1
+        v = data[args.key]
+        print(",".join(v) if isinstance(v, list) else v)
+        return 0
+
+    value: object = args.value
+    if args.key == "port":
+        value = int(args.value)
+    elif args.key == "page_token":
+        if args.value not in ("true", "false"):
+            print("page_token is true or false", file=sys.stderr)
+            return 1
+        value = args.value == "true"
+    elif args.key in ("watch", "ignore"):
+        value = [p.strip() for p in args.value.split(",") if p.strip()]
+    elif args.key == "guideline":
+        from .config import Config, get_guideline_files
+
+        try:
+            get_guideline_files(Config.from_dict({"main": "main.tex", "guideline": args.value}))
+        except (OSError, ValueError) as error:
+            print(f"{error}. setup_info() lists the guidelines to choose from.", file=sys.stderr)
+            return 1
+    elif args.key == "compiler":
+        from .compiler import ALLOWED_COMPILERS
+
+        if args.value not in ALLOWED_COMPILERS:
+            print(
+                f"unknown compiler {args.value!r}; one of: {', '.join(sorted(ALLOWED_COMPILERS))}",
+                file=sys.stderr,
+            )
+            return 1
+    data[args.key] = value
+    with open(path, "w") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+    print(f"{args.key} = {value}  ({path})", file=sys.stderr)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# compile (one-shot)
+# ---------------------------------------------------------------------------
+
+
+def cmd_compile(args: argparse.Namespace) -> int:
+    from .compiler import compile_tex
+    from .config import get_main_file, get_watch_dir
+
+    cfg = load_config(main_file=args.main)
+    main = get_main_file(cfg)
+    watch_dir = get_watch_dir(cfg)
+
+    result = asyncio.run(compile_tex(main, compiler=cfg.compiler, work_dir=watch_dir))
+
+    if args.json:
+        print(json.dumps(_compile_result_dict(result), indent=2))
+    else:
+        if result.success:
+            print(f"compile succeeded in {result.duration_seconds:.2f}s")
+        else:
+            print(f"compile FAILED ({len(result.errors)} errors)", file=sys.stderr)
+        for err in result.errors:
+            loc = f"{err.file}:{err.line}" if err.line else err.file
+            print(f"  ERROR  {loc}  {err.message}", file=sys.stderr)
+            if err.context:
+                for line in err.context:
+                    print(f"           {line}", file=sys.stderr)
+        for w in result.warnings:
+            loc = f"{w.file}:{w.line}" if w.line else w.file
+            print(f"  warn   {loc}  {w.message}", file=sys.stderr)
+    return 0 if result.success else 1
+
+
+def _compile_result_dict(result) -> dict:
+    import dataclasses
+
+    return {
+        "success": result.success,
+        "errors": [dataclasses.asdict(e) for e in result.errors],
+        "warnings": [dataclasses.asdict(w) for w in result.warnings],
+        "output_file": str(result.output_file) if result.output_file else None,
+        "duration_seconds": result.duration_seconds,
+    }
+
+
+# ---------------------------------------------------------------------------
+# goto (requires running daemon)
+# ---------------------------------------------------------------------------
+
+
+def cmd_goto(args: argparse.Namespace) -> int:
+    import urllib.request
+
+    from .mcp_server import parse_goto_target
+
+    cfg = load_config()
+    port = args.port or cfg.port
+    body = parse_goto_target(args.target, default_file=cfg.main)
+
+    from .page_token import headers
+
+    req = urllib.request.Request(
+        f"http://127.0.0.1:{port}/goto",
+        data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json", **headers()},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            print(resp.read().decode())
+        return 0
+    except Exception as exc:
+        print(f"could not reach daemon at {port}: {exc}", file=sys.stderr)
+        return 2
+
+
+# ---------------------------------------------------------------------------
+# mcp
+# ---------------------------------------------------------------------------
+
+
+def cmd_mcp(args: argparse.Namespace) -> int:
+    if args.check:
+        from .mcp_server import check
+
+        tools = check(Path.cwd())
+        print(f"tex-mcp: {len(tools)} tools ({', '.join(tools)})")
+        return 0
+    from .mcp_server import main as mcp_main
+
+    mcp_main()
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tex-mcp-web",
+        description=(
+            "Live PDF preview + review-style commenting for LaTeX papers, "
+            "designed for a coding agent as the author. Run with no arguments to "
+            "start the server."
+        ),
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="DEBUG logging")
+    parser.add_argument("--port", type=int, help="HTTP port (default: from config)")
+
+    sub = parser.add_subparsers(dest="cmd")
+
+    p = sub.add_parser("serve", help="run the viewer server on its own (default)")
+    p.add_argument("--main", help="main .tex file (overrides config)")
+    p.set_defaults(func=cmd_serve)
+
+    p = sub.add_parser("link", help="print the page's address, with its token when page_token is on")
+    p.set_defaults(func=cmd_link)
+
+    p = sub.add_parser("init", help="scaffold .tex-mcp-web.yaml")
+    p.add_argument("--main", default="paper.tex")
+    p.add_argument("--force", action="store_true")
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("config", help="get/set values in .tex-mcp-web.yaml")
+    p.add_argument("key", nargs="?", help=f"one of: {', '.join(_CONFIG_KEYS)}")
+    p.add_argument("value", nargs="?", help="new value (lists comma-separated); omit to print")
+    p.set_defaults(func=cmd_config)
+
+    p = sub.add_parser("compile", help="one-shot compile")
+    p.add_argument("--main", help="main .tex file (overrides config)")
+    p.add_argument("--json", action="store_true", help="JSON output")
+    p.set_defaults(func=cmd_compile)
+
+    p = sub.add_parser("goto", help="scroll a running viewer")
+    p.add_argument("target", help="section title, line number, file:line, or pN")
+    p.set_defaults(func=cmd_goto)
+
+    p = sub.add_parser("mcp", help="run the MCP server (stdio); serves the viewer too")
+    p.add_argument("--check", action="store_true",
+                   help="build the server and list its tools instead of serving")
+    p.set_defaults(func=cmd_mcp)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    _configure_logging(getattr(args, "verbose", False))
+
+    if not getattr(args, "func", None):
+        args.main = None
+        return cmd_serve(args)
+    return args.func(args)
+
+
+def _split_root_args(argv: list[str]) -> tuple[list[str], list[str]]:
+    # Root-parser flags must precede the subcommand in argparse.
+    root: list[str] = []
+    rest: list[str] = []
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a in ("-v", "--verbose") or a.startswith("--port="):
+            root.append(a)
+        elif a == "--port":
+            root.extend(argv[i : i + 2])
+            i += 1
+        else:
+            rest.append(a)
+        i += 1
+    return root, rest
+
+
+def main_mcp(argv: list[str] | None = None) -> int:
+    """`tex-mcp` entry point: MCP stdio server."""
+    root, rest = _split_root_args(sys.argv[1:] if argv is None else argv)
+    return main([*root, "mcp", *rest])
+
+
+def main_serve(argv: list[str] | None = None) -> int:
+    """`tex-web` entry point: web server."""
+    root, rest = _split_root_args(sys.argv[1:] if argv is None else argv)
+    return main([*root, "serve", *rest])
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tex_mcp_web/comment_drafts.py

@@ -0,0 +1,123 @@
+"""Server-owned, file-backed comment replies and rewrites. Only the Reply and Edit
+blocks are editable."""
+
+import contextlib
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import uuid
+
+
+@contextlib.contextmanager
+def _directory(root: Path, create: bool = False):
+    # Walk directory descriptors, never following a symlink, including ancestors.
+    root = root.absolute()
+    if ".." in root.parts:
+        raise ValueError("invalid draft directory")
+    fd = os.open("/", os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        for part in root.parts[1:]:
+            if create:
+                try:
+                    os.mkdir(part, mode=0o700, dir_fd=fd)
+                except FileExistsError:
+                    pass
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        yield fd
+    finally:
+        os.close(fd)
+
+
+def _read(fd: int, name: str) -> str:
+    source = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=fd)
+    with os.fdopen(source, "r", encoding="utf-8", newline="") as stream:
+        info = os.fstat(stream.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+            raise ValueError("draft must be a regular, unlinked file")
+        return stream.read()
+
+
+def export(root: Path, comments: list[dict]) -> dict:
+    """Write the draft. Each comment gets an Edit block per entry the agent wrote,
+    holding its current text, and one empty Reply block; everything else is fixed."""
+    ids = [comment["id"] for comment in comments]
+    if not ids or len(ids) != len(set(ids)):
+        raise ValueError("comment_ids must be nonempty and unique")
+    key = uuid.uuid4().hex
+    segments = ["# Comment replies\n\nEdit only Reply and Edit blocks; keep their markers. "
+                "A Reply block left empty adds nothing; an Edit block left as it is changes nothing.\n"]
+    slots: list[list] = []  # ["reply", comment_id] or ["edit", comment_id, entry_id, original]
+    for comment in comments:
+        # The heading carries what the reader needs to answer: which thread, where it
+        # sits, and its state. Anchors, selectors and stamps are the store's business
+        # and the snapshot beside this file already holds what the reply is checked
+        # against, so none of them is written out for someone to read past.
+        source = comment["resolved_source"] if "resolved_source" in comment else None
+        where = (f"  {source['file']}:{source['line_start']}-{source['line_end']}"
+                 if source is not None else "")
+        segments[-1] += f"\n## {comment['id']}{where}  [{comment['status']}]\n"
+        for entry in comment["thread"]:
+            # A human entry is there to be read; an agent's own entry is there to be
+            # rewritten, and its Edit block already holds the text, so neither is
+            # written twice.
+            if entry["author"] != "agent":
+                segments[-1] += f"\n{entry['author']}  {entry['text']}\n"
+                continue
+            segments[-1] += f"\n### Edit {entry['id']}\n<!-- edit:{key}:{entry['id']} -->\n"
+            segments.append(f"\n<!-- /edit:{key}:{entry['id']} -->\n")
+            slots.append(["edit", comment["id"], entry["id"], entry["text"]])
+        segments[-1] += f"\n### Reply\n<!-- reply:{key}:{comment['id']} -->\n"
+        segments.append(f"\n<!-- /reply:{key}:{comment['id']} -->\n")
+        slots.append(["reply", comment["id"]])
+    # Between an opening marker line and its closing marker sits the block's content:
+    # the entry's current text for an Edit block, nothing yet for a Reply block.
+    body = ""
+    for index, segment in enumerate(segments):
+        body += segment
+        if index < len(slots) and slots[index][0] == "edit":
+            body += slots[index][3]
+    snapshot = {"ids": ids, "updated": [c["updated"] for c in comments], "segments": segments, "slots": slots}
+    root = root.absolute()
+    with _directory(root, create=True) as fd:
+        for suffix, text in ((".snapshot", json.dumps(snapshot, ensure_ascii=False)), (".md", body)):
+            target = os.open(key + suffix, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=fd)
+            with os.fdopen(target, "w", encoding="utf-8", newline="") as stream:
+                stream.write(text)
+    return {"path": str(root / (key + ".md")), "sha256": hashlib.sha256(body.encode("utf-8")).hexdigest(), "comment_ids": ids}
+
+
+def load(root: Path, path: str) -> tuple[dict[str, str], list[tuple[str, str, str]], dict[str, str]]:
+    """Read a filled draft back: (replies by comment id, entry rewrites as (comment id,
+    entry id, text), expected updated stamps by comment id). Only changed blocks count."""
+    candidate = Path(path)
+    if ".." in candidate.parts or candidate.parent != root.absolute() or not re.fullmatch(r"[0-9a-f]{32}\.md", candidate.name):
+        raise ValueError("draft must be a server-created draft path")
+    try:
+        with _directory(root) as fd:
+            snapshot = json.loads(_read(fd, candidate.stem + ".snapshot"))
+            body = _read(fd, candidate.name)
+        # Exact immutable segments protect IDs, snapshot timestamps and thread text.
+        match = re.fullmatch("(.*?)".join(re.escape(s) for s in snapshot["segments"]), body, re.DOTALL)
+        if match is None or len(match.groups()) != len(snapshot["slots"]):
+            raise ValueError("malformed draft: edit only Reply and Edit blocks")
+        replies: dict[str, str] = {}
+        entry_edits: list[tuple[str, str, str]] = []
+        for slot, value in zip(snapshot["slots"], match.groups()):
+            if slot[0] == "reply":
+                if value.strip():
+                    replies[slot[1]] = value.strip()
+            elif value.strip() != slot[3].strip():
+                if not value.strip():
+                    raise ValueError(f"the Edit block for {slot[2]} must not be emptied")
+                entry_edits.append((slot[1], slot[2], value.strip()))
+        if not replies and not entry_edits:
+            raise ValueError("the draft holds no reply and no changed Edit block")
+        expected = dict(zip(snapshot["ids"], snapshot["updated"]))
+        return replies, entry_edits, expected
+    except (OSError, UnicodeError, KeyError, TypeError, IndexError, json.JSONDecodeError) as error:
+        raise ValueError("invalid or unregistered draft") from error