texflow-mcp 1.0.0__tar.gz

texflow_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aaron Bockelie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

texflow_mcp-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include pyproject.toml
+include server.py
+recursive-include texflow/data *

texflow_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: texflow-mcp
+Version: 1.0.0
+Summary: LaTeX document compiler with MCP interface
+Author-email: Aaron Bockelie <aaronsb@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aaronsb/texflow-mcp
+Project-URL: Repository, https://github.com/aaronsb/texflow-mcp
+Project-URL: Issues, https://github.com/aaronsb/texflow-mcp/issues
+Keywords: mcp,latex,document,typesetting,pdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: mistune>=3.2.0
+Dynamic: license-file
+
+# TeXFlow MCP
+
+![License](https://img.shields.io/github/license/aaronsb/texflow-mcp)
+![PyPI](https://img.shields.io/pypi/v/texflow-mcp)
+![Python](https://img.shields.io/pypi/pyversions/texflow-mcp)
+
+A LaTeX document compiler with an [MCP](https://modelcontextprotocol.io) interface. AI agents operate on a structured document model — sections, paragraphs, figures, tables — while TeXFlow handles all LaTeX mechanics: packages, preamble, fonts, and compilation.
+
+## Install
+
+```bash
+pip install texflow-mcp
+```
+
+Or run without installing:
+
+```bash
+uvx texflow-mcp
+```
+
+### System dependencies (optional)
+
+TeXFlow compiles documents to PDF using XeLaTeX. Without it, you can still build and export `.tex` files.
+
+```bash
+# Arch
+pacman -S texlive-xetex texlive-fontsrecommended texlive-fontsextra
+
+# Debian/Ubuntu
+apt install texlive-xetex texlive-fonts-recommended texlive-fonts-extra
+
+# Fedora
+dnf install texlive-xetex texlive-collection-fontsrecommended texlive-collection-fontsextra
+```
+
+For page preview (PNG), install `poppler-utils` (provides `pdftoppm`).
+
+## Configure with Claude Code
+
+```bash
+claude mcp add texflow -- uvx texflow-mcp
+```
+
+That's it. Restart Claude Code and the tools are available.
+
+To set a workspace directory (where documents are saved):
+
+```bash
+claude mcp add texflow -- uvx texflow-mcp ~/Documents/TeXFlow
+```
+
+## Configure with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "texflow": {
+      "command": "uvx",
+      "args": ["texflow-mcp"]
+    }
+  }
+}
+```
+
+## How it works
+
+TeXFlow has two entry flows, both converging on the same in-memory document model:
+
+1. **Scaffold** — `document(action="create")` builds an empty document skeleton. Add content with `edit(action="insert")`.
+2. **Markdown ingest** — `document(action="ingest", source="paper.md")` parses markdown into the model. Refine layout from there.
+
+The model auto-saves to disk as JSON. LaTeX is only ever an output artifact — you never edit `.tex` directly.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `document` | Create, ingest markdown, show outline, read sections |
+| `layout` | Columns, fonts, paper, margins, headers/footers, TOC |
+| `edit` | Insert, replace, delete, move blocks (section, paragraph, figure, table, code, equation, list, raw) |
+| `render` | Compile to PDF, preview page as PNG, export `.tex` |
+| `reference` | Search LaTeX commands, symbols, packages, error help |
+| `queue` | Batch multiple operations in one call |
+
+Every response includes a workflow state hint showing where you are and what to do next.
+
+## Example session
+
+```
+> document(action="create", title="My Paper", document_class="article")
+
+> queue(operations=[
+    {"tool": "edit", "action": "insert", "block_type": "section", "title": "Introduction", "level": 1},
+    {"tool": "edit", "action": "insert", "content": "This paper explores...", "section": "Introduction"},
+    {"tool": "edit", "action": "insert", "block_type": "section", "title": "Methods", "level": 1},
+    {"tool": "layout", "font": "palatino", "columns": 2}
+  ])
+
+> render(action="compile")
+```
+
+## Development
+
+```bash
+git clone https://github.com/aaronsb/texflow-mcp
+cd texflow-mcp
+uv sync
+uv run pytest tests/ -v    # 222 tests
+uv run texflow              # Start MCP server
+```
+
+## License
+
+MIT

texflow_mcp-1.0.0/README.md

@@ -0,0 +1,116 @@
+# TeXFlow MCP
+
+![License](https://img.shields.io/github/license/aaronsb/texflow-mcp)
+![PyPI](https://img.shields.io/pypi/v/texflow-mcp)
+![Python](https://img.shields.io/pypi/pyversions/texflow-mcp)
+
+A LaTeX document compiler with an [MCP](https://modelcontextprotocol.io) interface. AI agents operate on a structured document model — sections, paragraphs, figures, tables — while TeXFlow handles all LaTeX mechanics: packages, preamble, fonts, and compilation.
+
+## Install
+
+```bash
+pip install texflow-mcp
+```
+
+Or run without installing:
+
+```bash
+uvx texflow-mcp
+```
+
+### System dependencies (optional)
+
+TeXFlow compiles documents to PDF using XeLaTeX. Without it, you can still build and export `.tex` files.
+
+```bash
+# Arch
+pacman -S texlive-xetex texlive-fontsrecommended texlive-fontsextra
+
+# Debian/Ubuntu
+apt install texlive-xetex texlive-fonts-recommended texlive-fonts-extra
+
+# Fedora
+dnf install texlive-xetex texlive-collection-fontsrecommended texlive-collection-fontsextra
+```
+
+For page preview (PNG), install `poppler-utils` (provides `pdftoppm`).
+
+## Configure with Claude Code
+
+```bash
+claude mcp add texflow -- uvx texflow-mcp
+```
+
+That's it. Restart Claude Code and the tools are available.
+
+To set a workspace directory (where documents are saved):
+
+```bash
+claude mcp add texflow -- uvx texflow-mcp ~/Documents/TeXFlow
+```
+
+## Configure with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "texflow": {
+      "command": "uvx",
+      "args": ["texflow-mcp"]
+    }
+  }
+}
+```
+
+## How it works
+
+TeXFlow has two entry flows, both converging on the same in-memory document model:
+
+1. **Scaffold** — `document(action="create")` builds an empty document skeleton. Add content with `edit(action="insert")`.
+2. **Markdown ingest** — `document(action="ingest", source="paper.md")` parses markdown into the model. Refine layout from there.
+
+The model auto-saves to disk as JSON. LaTeX is only ever an output artifact — you never edit `.tex` directly.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `document` | Create, ingest markdown, show outline, read sections |
+| `layout` | Columns, fonts, paper, margins, headers/footers, TOC |
+| `edit` | Insert, replace, delete, move blocks (section, paragraph, figure, table, code, equation, list, raw) |
+| `render` | Compile to PDF, preview page as PNG, export `.tex` |
+| `reference` | Search LaTeX commands, symbols, packages, error help |
+| `queue` | Batch multiple operations in one call |
+
+Every response includes a workflow state hint showing where you are and what to do next.
+
+## Example session
+
+```
+> document(action="create", title="My Paper", document_class="article")
+
+> queue(operations=[
+    {"tool": "edit", "action": "insert", "block_type": "section", "title": "Introduction", "level": 1},
+    {"tool": "edit", "action": "insert", "content": "This paper explores...", "section": "Introduction"},
+    {"tool": "edit", "action": "insert", "block_type": "section", "title": "Methods", "level": 1},
+    {"tool": "layout", "font": "palatino", "columns": 2}
+  ])
+
+> render(action="compile")
+```
+
+## Development
+
+```bash
+git clone https://github.com/aaronsb/texflow-mcp
+cd texflow-mcp
+uv sync
+uv run pytest tests/ -v    # 222 tests
+uv run texflow              # Start MCP server
+```
+
+## License
+
+MIT

texflow_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "texflow-mcp"
+version = "1.0.0"
+description = "LaTeX document compiler with MCP interface"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    {name = "Aaron Bockelie", email = "aaronsb@users.noreply.github.com"},
+]
+keywords = ["mcp", "latex", "document", "typesetting", "pdf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Markup :: LaTeX",
+]
+dependencies = [
+    "fastmcp>=3.0.0",
+    "mistune>=3.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/aaronsb/texflow-mcp"
+Repository = "https://github.com/aaronsb/texflow-mcp"
+Issues = "https://github.com/aaronsb/texflow-mcp/issues"
+
+[project.scripts]
+texflow = "server:main"
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = {find = {where = ["."], include = ["texflow*"]}}
+py-modules = ["server"]
+include-package-data = true
+
+[tool.setuptools.package-data]
+texflow = ["data/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

texflow_mcp-1.0.0/server.py

@@ -0,0 +1,226 @@
+"""TeXFlow MCP server — LaTeX document compiler with MCP interface."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from texflow.tools.state import set_output_dir
+from texflow.tools.document import document_tool
+from texflow.tools.layout import layout_tool
+from texflow.tools.edit import edit_tool
+from texflow.tools.render import render_tool
+from texflow.tools.reference import reference_tool
+from texflow.tools.queue import queue_tool
+from texflow.tools.workflow import state_hint, error_hint, WORKFLOW_MAP
+
+mcp = FastMCP(
+    "texflow",
+    instructions=(
+        "TeXFlow is a LaTeX document compiler. "
+        "Use 'document' to create or ingest content, 'layout' to configure typesetting, "
+        "'edit' to manipulate content structurally, 'render' to compile to PDF, "
+        "'reference' for LaTeX documentation search, and "
+        "'queue' to batch multiple operations in one call. "
+        "Every response includes a workflow state hint showing where you are and what to do next."
+    ),
+)
+
+
+def _with_hints(result: str) -> str:
+    """Append workflow state hint and error guidance to a tool result."""
+    extra = error_hint(result)
+    return result + extra + state_hint()
+
+
+# --- Workflow resource ---
+
+@mcp.resource("texflow://workflow")
+def workflow_map() -> str:
+    """TeXFlow workflow map showing states and transitions."""
+    return WORKFLOW_MAP + "\n" + state_hint()
+
+
+# --- Document tool ---
+
+@mcp.tool()
+def document(
+    action: str,
+    document_class: str | None = None,
+    title: str | None = None,
+    author: str | None = None,
+    source: str | None = None,
+    section: str | None = None,
+) -> str:
+    """Create, ingest, and inspect documents.
+
+    Actions:
+    - create: Scaffold a new empty document. Optionally set class, title, author.
+    - ingest: Parse markdown text or file path into the document model.
+    - outline: Show document structure (sections, block counts).
+    - read: Read content of a specific section as prose text.
+    """
+    return _with_hints(document_tool(action, document_class, title, author, source, section))
+
+
+# --- Layout tool ---
+
+@mcp.tool()
+def layout(
+    columns: int | None = None,
+    font: str | None = None,
+    font_sans: str | None = None,
+    font_mono: str | None = None,
+    font_size: str | None = None,
+    paper: str | None = None,
+    margins: str | None = None,
+    header_left: str | None = None,
+    header_center: str | None = None,
+    header_right: str | None = None,
+    footer_left: str | None = None,
+    footer_center: str | None = None,
+    footer_right: str | None = None,
+    toc: bool | None = None,
+    lof: bool | None = None,
+    lot: bool | None = None,
+    line_spacing: float | None = None,
+) -> str:
+    """Configure document typesetting and layout.
+
+    Only provided parameters are changed; others are left as-is.
+    Returns the current full layout configuration after changes.
+    """
+    return _with_hints(layout_tool(
+        columns, font, font_sans, font_mono, font_size, paper, margins,
+        header_left, header_center, header_right,
+        footer_left, footer_center, footer_right,
+        toc, lof, lot, line_spacing,
+    ))
+
+
+# --- Edit tool ---
+
+@mcp.tool()
+def edit(
+    action: str,
+    block_type: str | None = None,
+    section: str | None = None,
+    position: int | None = None,
+    content: str | None = None,
+    title: str | None = None,
+    level: int | None = None,
+    language: str | None = None,
+    path: str | None = None,
+    caption: str | None = None,
+    headers: list[str] | None = None,
+    rows: list[list[str]] | None = None,
+    target_section: str | None = None,
+    target_position: int | None = None,
+) -> str:
+    """Manipulate document content structurally.
+
+    Actions:
+    - insert: Add a new block at a position within a section.
+    - replace: Replace a block at a position with new content.
+    - delete: Remove a block at a position.
+    - move: Move a block from one location to another.
+
+    Sections are addressed by title path (e.g., 'Methods/Data Collection').
+    Blocks within a section are addressed by 0-based index.
+    Use document(action='outline') to see current structure and indices.
+    """
+    return _with_hints(edit_tool(
+        action, block_type, section, position, content, title, level,
+        language, path, caption, headers, rows, target_section, target_position,
+    ))
+
+
+# --- Render tool ---
+
+@mcp.tool()
+def render(
+    action: str,
+    output_path: str | None = None,
+    page: int | None = None,
+    dpi: int | None = None,
+) -> str:
+    """Compile and export the document.
+
+    Actions:
+    - compile: Serialize model to .tex, compile to PDF. Returns PDF path.
+    - preview: Render a specific page as base64 PNG image.
+    - tex: Export the raw .tex source. Returns the LaTeX content.
+    """
+    return _with_hints(render_tool(action, output_path, page, dpi))
+
+
+# --- Reference tool ---
+
+@mcp.tool()
+def reference(
+    action: str,
+    query: str | None = None,
+    description: str | None = None,
+    name: str | None = None,
+    error: str | None = None,
+    topic: str | None = None,
+    path: str | None = None,
+) -> str:
+    """Search LaTeX documentation, symbols, packages, and error solutions.
+
+    Actions:
+    - search: Search for LaTeX commands or general topics.
+    - symbol: Find symbols by description (e.g., "approximately equal").
+    - package: Get information about a LaTeX package.
+    - check_style: Analyze a .tex file for best practices.
+    - error_help: Get help for LaTeX error messages.
+    - example: Get working examples for a topic (table, equation, figure, list, code).
+    """
+    return _with_hints(reference_tool(action, query, description, name, error, topic, path))
+
+
+# --- Queue tool ---
+
+@mcp.tool()
+def queue(
+    operations: list[dict],
+    continue_on_error: bool = False,
+) -> str:
+    """Execute multiple operations in a single call.
+
+    Each operation is a dict with 'tool' (document, layout, edit, render, reference)
+    plus the arguments for that tool. Operations run sequentially; disk is written
+    once at the end.
+
+    Example:
+        queue(operations=[
+            {"tool": "document", "action": "create", "title": "My Doc"},
+            {"tool": "edit", "action": "insert", "block_type": "section", "title": "Intro", "level": 1},
+            {"tool": "edit", "action": "insert", "content": "Hello world.", "section": "Intro"},
+            {"tool": "layout", "columns": 2, "font": "palatino"}
+        ])
+
+    Args:
+        operations: List of operation dicts.
+        continue_on_error: If False (default), stop on first error.
+    """
+    # Queue gets summary + state hint, no per-operation hints
+    result = queue_tool(operations, continue_on_error)
+    return result + state_hint()
+
+
+def main():
+    """Entry point for the texflow CLI."""
+    # Optional workspace dir argument
+    if len(sys.argv) > 1:
+        workspace = Path(sys.argv[1])
+        workspace.mkdir(parents=True, exist_ok=True)
+        set_output_dir(workspace)
+
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

texflow_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

texflow_mcp-1.0.0/tests/test_compiler.py

@@ -0,0 +1,99 @@
+"""Tests for the LaTeX compiler."""
+
+import shutil
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from texflow.compiler import CompileError, CompileResult, compile_tex, preview_page, _parse_errors
+from texflow.model import Document, Metadata, Paragraph, Section
+from texflow.serializer import serialize
+
+HAS_XELATEX = shutil.which("xelatex") is not None
+HAS_PDFLATEX = shutil.which("pdflatex") is not None
+HAS_LATEX = HAS_XELATEX or HAS_PDFLATEX
+HAS_PDFTOPPM = shutil.which("pdftoppm") is not None
+
+
+def _minimal_tex() -> str:
+    doc = Document(
+        metadata=Metadata(title="Test"),
+        content=[Section(title="Hello", level=1, content=[Paragraph(text="World")])],
+    )
+    return serialize(doc)
+
+
+def test_compile_result_dataclass():
+    r = CompileResult(success=True, pdf_path=Path("/tmp/test.pdf"))
+    assert r.success is True
+    assert r.errors == []
+
+
+def test_parse_errors_from_log():
+    log = """This is some log output
+! Undefined control sequence.
+l.42 \\badcommand
+
+! Missing $ inserted.
+l.55 some_text_
+"""
+    errors = _parse_errors(log)
+    assert len(errors) == 2
+    assert errors[0].message == "Undefined control sequence."
+    assert errors[0].line == 42
+    assert errors[1].message == "Missing $ inserted."
+    assert errors[1].line == 55
+
+
+def test_parse_errors_empty_log():
+    assert _parse_errors("All good, no errors here.") == []
+
+
+@pytest.mark.skipif(not HAS_LATEX, reason="No LaTeX engine installed")
+def test_compile_minimal_document():
+    tex = _minimal_tex()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = compile_tex(tex, output_dir=Path(tmpdir), filename="test")
+        assert result.tex_path is not None
+        assert result.tex_path.exists()
+        if result.success:
+            assert result.pdf_path is not None
+            assert result.pdf_path.exists()
+            assert result.pdf_path.stat().st_size > 0
+
+
+@pytest.mark.skipif(not HAS_LATEX, reason="No LaTeX engine installed")
+def test_compile_with_errors():
+    bad_tex = "\\documentclass{article}\n\\begin{document}\n\\badcommand\n\\end{document}"
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = compile_tex(bad_tex, output_dir=Path(tmpdir), filename="bad")
+        assert result.tex_path is not None
+        assert len(result.errors) > 0
+
+
+@pytest.mark.skipif(not (HAS_LATEX and HAS_PDFTOPPM), reason="Requires LaTeX + pdftoppm")
+def test_preview_page():
+    tex = _minimal_tex()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = compile_tex(tex, output_dir=Path(tmpdir))
+        if result.success and result.pdf_path:
+            b64 = preview_page(result.pdf_path, page=1, dpi=72)
+            assert b64 is not None
+            assert len(b64) > 100  # Should be a non-trivial PNG
+
+
+def test_preview_nonexistent_file():
+    result = preview_page(Path("/tmp/nonexistent.pdf"))
+    assert result is None
+
+
+@pytest.mark.skipif(HAS_LATEX, reason="Only test when no LaTeX engine available")
+def test_compile_without_engine():
+    tex = _minimal_tex()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = compile_tex(tex, output_dir=Path(tmpdir))
+        assert result.success is False
+        assert result.tex_path is not None
+        assert result.tex_path.exists()
+        assert any("No LaTeX engine" in e.message for e in result.errors)