{"id":30805551,"url":"https://github.com/aaronsb/texflow-mcp","last_synced_at":"2026-03-02T06:31:22.105Z","repository":{"id":295544717,"uuid":"990393711","full_name":"aaronsb/texflow-mcp","owner":"aaronsb","description":"MCP server enabling AI assistants to author, edit, and print documents using LaTeX/Markdown with collaborative editing and project-based organization","archived":false,"fork":false,"pushed_at":"2025-07-26T03:30:39.000Z","size":6081,"stargazers_count":10,"open_issues_count":4,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T00:58:57.644Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-26T03:49:56.000Z","updated_at":"2025-08-14T17:27:10.000Z","dependencies_parsed_at":"2025-05-26T05:28:08.839Z","dependency_job_id":"763df36b-0c60-441c-95c9-5a22216aca66","html_url":"https://github.com/aaronsb/texflow-mcp","commit_stats":null,"previous_names":["aaronsb/cups-mcp","aaronsb/texflow-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/texflow-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Ftexflow-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Ftexflow-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Ftexflow-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Ftexflow-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/texflow-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Ftexflow-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29994122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T00:58:51.801Z","updated_at":"2026-03-02T06:31:22.019Z","avatar_url":"https://github.com/aaronsb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeXFlow\n\n![TeXFlow](docs/img/texflow-banner.png)\n\nA document authoring and composition MCP server that provides a pipeline for document creation: **Content → Processing → Output**. TeXFlow transforms your ideas into typeset documents using LaTeX, Markdown, and modern document processing tools.\n\n## 🚀 Key Innovation: Collaborative Document Editing\n\nThis server introduces **collaborative editing capabilities** that prevent conflicts when multiple agents (human or AI) work on the same documents:\n\n- **Change Detection**: Automatically detects when documents are modified externally\n- **Diff Visualization**: Shows unified diffs of what changed between edits\n- **Conflict Prevention**: Refuses to overwrite external changes, protecting everyone's work\n- **AI-to-AI Collaboration**: Enables multiple AI agents to work together on documents without conflicts\n\n## Core Value Proposition\n\nTeXFlow enables MCP-compatible AI clients (Claude Desktop, Dive AI, or custom implementations) to have document workflow capabilities with **project-based organization**. Your AI assistant becomes a document authoring companion that can:\n\n- Create and manage document projects with organized structure\n- Author content in Markdown or LaTeX with proper project context\n- Transform documents through a sophisticated processing pipeline\n- Generate beautiful PDFs with professional typography\n- Print or export documents in various formats\n\n## 🚀 Quick Start with Projects\n\n```python\n# Create a new document project\ncreate_project(\"my-paper\", \"article\")\n# Created project 'my-paper' at ~/Documents/TeXFlow/my-paper\n\n# Write content (automatically saved to project)\nsave_markdown(\"# Introduction\\n\\nThis is my paper.\", \"intro.md\")\n# Markdown saved to project 'my-paper': content/intro.md\n\n# Generate PDF (automatically saved to project/output/pdf/)\nmarkdown_to_pdf(file_path=\"intro.md\", output_path=\"intro.pdf\")\n# PDF saved to project 'my-paper': output/pdf/intro.pdf\n\n# Switch between projects\nuse_project(\"thesis-2024\")\nlist_projects()  # See all your document projects\n```\n\n## 🎯 Semantic Tool Organization\n\nTeXFlow's tools are organized into 9 semantic operations for easier discovery and use:\n\n- **📄 Document** - Create, edit, convert, and validate documents\n- **🖨️ Output** - Print and export to various formats\n- **📁 Project** - Organize work into logical units\n- **🔍 Discover** - Find documents, fonts, and resources\n- **📦 Organizer** - Archive, move, clean documents and auxiliary files\n- **🖨️ Printer** - Manage printing hardware\n- **💡 Workflow** - Get guidance and automation\n- **📋 Templates** - Start from pre-built document templates\n- **📚 Reference** - LaTeX documentation search and help\n\nSee [Tool Reference](docs/TEXFLOW_REFERENCE.md) for detailed documentation of all tools.\n\n## Features\n\n### 📁 Project-Based Document Management\n- Create organized document projects with templates (article, thesis, letter)\n- Automatic project structure with content/, output/, and assets/ directories  \n- Switch between projects seamlessly\n- Project-aware file paths for better organization\n- All documents in one project stay together\n\n### Printing\n- List available CUPS printers with status information\n- Print plain text directly\n- Print Markdown documents (rendered to PDF via pandoc)\n- Print files from the filesystem\n- Automatic file type detection\n\n### Document Creation \u0026 Saving\n- Convert Markdown to PDF without printing\n- Save Markdown content to .md files\n- Save LaTeX content to .tex files\n- Print LaTeX documents with full XeLaTeX compilation\n- Smart path handling with Documents folder default\n- Automatic file renaming to avoid overwrites\n\n### Printer Management\n- Get detailed printer information\n- Set default printer\n- Enable/disable printers\n- Update printer descriptions and locations\n\n### Collaborative Document Editing 🤝\n- Read documents with line numbers for precise editing\n- Make targeted edits with string replacement and validation\n- **Track external changes** with modification time and content hashing\n- **Show diffs** when documents are edited outside the AI session\n- **Prevent conflicts** between multiple editors (human or AI)\n- Check document status to see what changed since last read\n- Enable safe concurrent editing workflows\n\n### Document Archiving \u0026 Version Management 📦\n- Archive (soft delete) documents to hidden .texflow_archive folder\n- List and browse archived documents\n- Restore archived documents to original or new location\n- Find versions of a document (current and archived)\n- Bulk cleanup with pattern matching (e.g., archive *_old* files)\n- Preserves document history with timestamps\n\n### Smart Features\n- Dependency checking at startup\n- Conditional tool registration based on available dependencies\n- Clear feedback when dependencies are missing\n- Automatic file type detection and appropriate handling\n\n## Prerequisites\n\n### Required\n- Linux system with CUPS installed\n- Python 3.10+\n\n### Optional (for additional features)\n- `pandoc` - For markdown to PDF conversion\n  - Debian/Ubuntu: `apt install pandoc`\n  - Fedora: `dnf install pandoc`\n  - Arch: `pacman -S pandoc`\n- `weasyprint` - For HTML to PDF conversion\n  - Debian/Ubuntu: `apt install weasyprint`\n  - Fedora: `dnf install weasyprint`\n  - Arch: `pacman -S python-weasyprint`\n- `rsvg-convert` - For SVG to PDF conversion\n  - Debian/Ubuntu: `apt install librsvg2-bin`\n  - Fedora: `dnf install librsvg2-tools`\n  - Arch: `pacman -S librsvg`\n- **LaTeX/XeLaTeX** - For PDF generation from markdown and LaTeX documents\n  \n  **Core Requirements:**\n  - XeLaTeX engine for PDF compilation\n  - Latin Modern fonts for proper text rendering\n  - Standard LaTeX packages for document formatting\n  \n  **Installation by Distribution:**\n  \n  - **Debian/Ubuntu**: \n    ```bash\n    # Essential packages\n    apt install texlive-xetex texlive-fonts-recommended texlive-latex-recommended\n    \n    # For TikZ diagrams and graphics (if needed)\n    apt install texlive-pictures\n    \n    # For LaTeX validation (chktex)\n    apt install chktex\n    ```\n  \n  - **Fedora**: \n    ```bash\n    # Essential packages\n    dnf install texlive-xetex texlive-collection-fontsrecommended\n    \n    # For TikZ diagrams and graphics (if needed)\n    dnf install texlive-collection-pictures\n    \n    # For LaTeX validation (chktex)\n    dnf install texlive-chktex\n    ```\n  \n  - **Arch**: \n    ```bash\n    # Essential packages\n    pacman -S texlive-xetex texlive-fontsrecommended\n    \n    # For TikZ diagrams and graphics (if needed)\n    pacman -S texlive-pictures\n    \n    # For LaTeX validation (chktex)\n    pacman -S texlive-binextra\n    ```\n  \n  **What Each Package Provides:**\n  - `texlive-xetex`: XeLaTeX engine and fontspec package\n  - `texlive-fonts-recommended`: Latin Modern, Computer Modern, and other standard fonts\n  - `texlive-latex-recommended`: Essential LaTeX packages (geometry, etc.)\n  - `texlive-pictures`: TikZ package for creating diagrams and graphics\n  - `chktex`/`texlive-binextra`: LaTeX validation tools for checking syntax\n\nThe server checks for these dependencies at startup and enables features that have their requirements met. Missing dependencies are reported with installation instructions.\n\n## Installation\n\n```bash\n# Install system dependencies (choose your distribution)\n\n# Debian/Ubuntu - Full installation with all features\nsudo apt-get install cups pandoc texlive-xetex texlive-fonts-recommended \\\n                     texlive-latex-recommended texlive-pictures chktex \\\n                     weasyprint librsvg2-bin\n\n# Fedora - Full installation with all features  \nsudo dnf install cups pandoc texlive-xetex texlive-collection-fontsrecommended \\\n                 texlive-collection-pictures texlive-chktex \\\n                 weasyprint librsvg2-tools\n\n# Arch - Full installation with all features\nsudo pacman -S cups pandoc texlive-xetex texlive-fontsrecommended \\\n               texlive-pictures texlive-binextra \\\n               python-weasyprint librsvg\n\n# Clone and install\ngit clone https://github.com/aaronsb/texflow-mcp\ncd texflow-mcp\nuv sync\n```\n\n## Quick Start\n\n### Option 1: Run directly from GitHub (Recommended)\n\nNo installation needed! Just ensure you have `uv` installed and run:\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Run TeXFlow directly from GitHub\nuvx --from git+https://github.com/aaronsb/texflow-mcp.git texflow\n```\n\n### Option 2: Clone and run locally\n\n```bash\n# Clone the repository\ngit clone https://github.com/aaronsb/texflow-mcp\ncd texflow-mcp\n\n# Run the server\nuv run texflow\n```\n\n## Usage\n\n### Quick Start - 9 Unified Tools\n\nTeXFlow provides 9 semantic tools that intelligently guide your document workflow:\n\n#### 1. `document` - Create, edit, and transform documents\n```python\n# Create with auto-format detection\ndocument(action=\"create\", content=\"# My Paper\", intent=\"research\")\n\n# Convert existing files (don't recreate!)\ndocument(action=\"convert\", source=\"notes.md\", target_format=\"latex\")\n\n# Edit with conflict detection\ndocument(action=\"edit\", path=\"paper.tex\", old_string=\"draft\", new_string=\"final\")\n```\n\n#### 2. `output` - Print or export documents\n```python\n# Print existing file (preferred)\noutput(action=\"print\", source=\"report.pdf\")\n\n# Export to PDF\noutput(action=\"export\", source=\"notes.md\", output_path=\"notes.pdf\")\n```\n\n#### 3. `project` - Organize your work\n```python\n# Create project with AI-guided structure\nproject(action=\"create\", name=\"thesis\", description=\"PhD thesis on quantum computing\")\n\n# Switch projects\nproject(action=\"switch\", name=\"thesis\")\n```\n\n#### 4. `printer` - Manage printing hardware\n```python\nprinter(action=\"list\")  # Show all printers\nprinter(action=\"set_default\", name=\"Office_Laser\")\n```\n\n#### 5. `discover` - Find resources\n```python\ndiscover(action=\"documents\", folder=\"drafts\")  # Find documents\ndiscover(action=\"fonts\", style=\"serif\")  # Browse fonts\n```\n\n#### 6. `archive` - Manage versions\n```python\narchive(action=\"versions\", filename=\"paper.tex\")  # Find all versions\narchive(action=\"cleanup\", pattern=\"*_old*\")  # Clean old files\n```\n\n#### 7. `workflow` - Get intelligent guidance\n```python\nworkflow(action=\"suggest\", task=\"write paper with citations\")\nworkflow(action=\"next_steps\")  # What to do next\n```\n\nEach tool provides hints for next steps, guiding you through complex workflows.\n\n### Complete Tool Reference\n\nFor detailed documentation of all 9 tools, see [Tool Reference](docs/TEXFLOW_REFERENCE.md).\n\n### Legacy Tool Documentation\n\nFor users still using individual tools, the original tool documentation follows below. Note that the unified semantic tools above are the recommended approach.\n\n#### `print_text`\nPrints plain text content.\n\n```json\n{\n  \"name\": \"print_text\",\n  \"arguments\": {\n    \"content\": \"Hello, World!\",\n    \"printer\": \"Brother_HL_L2350DW\"  // optional\n  }\n}\n```\n\n#### `print_markdown`\nPrints Markdown content rendered as PDF via pandoc and XeLaTeX.\n\n**Supports:**\n- Standard markdown formatting (headers, lists, tables, code blocks)\n- LaTeX math expressions (inline with `$`, display with `$$`)\n- Latin scripts including European languages\n- Greek and Cyrillic alphabets\n- Basic symbols and punctuation\n\n**Limited support for:**\n- Complex Unicode (emoji, box drawing characters)\n- Right-to-left scripts (Arabic, Hebrew)\n- CJK characters (Chinese, Japanese, Korean)\n\n```json\n{\n  \"name\": \"print_markdown\",\n  \"arguments\": {\n    \"content\": \"# My Document\\n\\nThis is **bold** text.\\n\\nMath: $E = mc^2$\",\n    \"printer\": \"HP_LaserJet\",  // optional\n    \"title\": \"My Document\"     // optional\n  }\n}\n```\n\n#### `print_file`\nPrints a file from the filesystem.\n\n```json\n{\n  \"name\": \"print_file\",\n  \"arguments\": {\n    \"path\": \"/path/to/document.pdf\",\n    \"printer\": \"Canon_PIXMA\"  // optional\n  }\n}\n```\n\n#### `get_printer_info`\nGet detailed information about a specific printer including status, make/model, location, and URI.\n\n```json\n{\n  \"name\": \"get_printer_info\",\n  \"arguments\": {\n    \"printer_name\": \"My_Printer\"\n  }\n}\n```\n\n#### `set_default_printer`\nChange the default printer.\n\n```json\n{\n  \"name\": \"set_default_printer\",\n  \"arguments\": {\n    \"printer_name\": \"CanonG3260\"\n  }\n}\n```\n\n#### `enable_printer` / `disable_printer`\nControl printer availability for accepting jobs.\n\n```json\n{\n  \"name\": \"enable_printer\",\n  \"arguments\": {\n    \"printer_name\": \"My_Printer\"\n  }\n}\n```\n\n#### `update_printer_info`\nUpdate printer description and/or location.\n\n```json\n{\n  \"name\": \"update_printer_info\",\n  \"arguments\": {\n    \"printer_name\": \"My_Printer\",\n    \"description\": \"Office Color Laser\",\n    \"location\": \"Room 201\"\n  }\n}\n```\n\n#### `markdown_to_pdf`\nConvert markdown to PDF and save to a file (without printing).\n\n**Supports:**\n- Same markdown features as `print_markdown`\n- Saves PDF to specified path instead of printing\n\n```json\n{\n  \"name\": \"markdown_to_pdf\",\n  \"arguments\": {\n    \"content\": \"# My Document\\n\\nSave this as PDF.\",\n    \"output_path\": \"report.pdf\",  // Saves to ~/Documents/report.pdf by default\n    \"title\": \"My Document\"\n  }\n}\n```\n\n#### `print_latex`\nPrint LaTeX content (compiled to PDF via XeLaTeX).\n\n**Supports:**\n- Full LaTeX syntax and packages\n- Mathematical formulas and equations\n- TikZ diagrams and graphics\n- Bibliography and citations\n- Custom document classes\n\n```json\n{\n  \"name\": \"print_latex\",\n  \"arguments\": {\n    \"content\": \"\\\\documentclass{article}\\n\\\\begin{document}\\nHello LaTeX!\\n\\\\end{document}\",\n    \"printer\": \"My_Printer\",  // optional\n    \"title\": \"My LaTeX Doc\"  // optional\n  }\n}\n```\n\n#### `save_markdown`\nSave markdown content to a .md file.\n\n```json\n{\n  \"name\": \"save_markdown\",\n  \"arguments\": {\n    \"content\": \"# My Document\\n\\nThis is my markdown content.\",\n    \"filename\": \"notes.md\"  // Saves to ~/Documents/notes.md by default\n  }\n}\n```\n\n#### `save_latex`\nSave LaTeX content to a .tex file.\n\n```json\n{\n  \"name\": \"save_latex\",\n  \"arguments\": {\n    \"content\": \"\\\\documentclass{article}\\n\\\\begin{document}\\nHello LaTeX!\\n\\\\end{document}\",\n    \"filename\": \"document.tex\"  // Saves to ~/Documents/document.tex by default\n  }\n}\n```\n\n#### `list_documents`\nList PDF and Markdown files in the Documents folder.\n\n```json\n{\n  \"name\": \"list_documents\",\n  \"arguments\": {\n    \"folder\": \"reports\"  // Optional: list files in ~/Documents/reports\n  }\n}\n```\n\n#### `print_from_documents`\nPrint a PDF or Markdown file from the Documents folder.\n\n```json\n{\n  \"name\": \"print_from_documents\",\n  \"arguments\": {\n    \"filename\": \"report.pdf\",     // or just \"report\" - will find .pdf or .md\n    \"printer\": \"My_Printer\",  // optional\n    \"folder\": \"reports\"           // optional subfolder\n  }\n}\n```\n\n**Features:**\n- Automatically finds .pdf or .md extension if not specified\n- Converts Markdown files to PDF before printing\n- Works with subfolders in Documents\n\n#### `markdown_to_latex`\nConvert a Markdown file to LaTeX format for further customization.\n\n```json\n{\n  \"name\": \"markdown_to_latex\",\n  \"arguments\": {\n    \"file_path\": \"research_notes.md\",  // Path to markdown file\n    \"output_path\": \"research_paper.tex\",  // Optional: output path\n    \"title\": \"My Research Paper\",  // Optional: document title\n    \"standalone\": true  // Optional: create complete document (default: true)\n  }\n}\n```\n\n**Features:**\n- Converts Markdown to editable LaTeX format\n- Preserves math expressions, tables, and formatting\n- Adds conversion metadata as comments\n- Allows fine-tuning before final PDF compilation\n- Part of the markdown → LaTeX → PDF workflow\n\n**Workflow example:**\n```bash\n1. save_markdown(content=\"...\", filename=\"notes.md\")\n2. markdown_to_latex(file_path=\"notes.md\")  # Creates notes.tex\n3. edit_document(file_path=\"notes.tex\", ...)  # Optional: customize\n4. latex_to_pdf(file_path=\"notes.tex\", output_path=\"final.pdf\")\n```\n\n#### `list_available_fonts`\nList fonts available for use with XeLaTeX documents.\n\n```json\n{\n  \"name\": \"list_available_fonts\",\n  \"arguments\": {\n    \"style\": \"serif\"  // Optional: filter by 'serif', 'sans', 'mono', or None for all\n  }\n}\n```\n\n**Features:**\n- Lists all system fonts compatible with XeLaTeX\n- Filter by font style (serif, sans-serif, monospace)\n- Groups fonts alphabetically for easy browsing\n- Provides usage examples for LaTeX documents\n- Shows popular font recommendations\n\n#### `validate_latex`\nValidate LaTeX content for syntax errors before compilation.\n\n```json\n{\n  \"name\": \"validate_latex\",\n  \"arguments\": {\n    \"content\": \"\\\\documentclass{article}\\n\\\\begin{document}\\nHello!\\n\\\\end{document}\"\n  }\n}\n```\n\n**Features:**\n- Uses `lacheck` and `chktex` for syntax checking (if available)\n- Performs test compilation with XeLaTeX\n- Returns detailed error reports and warnings\n- Helps catch errors before printing\n\n#### `read_document`\nRead a document file with line numbers for editing.\n\n```json\n{\n  \"name\": \"read_document\",\n  \"arguments\": {\n    \"file_path\": \"proposal.tex\",  // or full path\n    \"offset\": 1,                  // starting line (optional, default: 1)\n    \"limit\": 50                   // number of lines (optional, default: 50)\n  }\n}\n```\n\n**Features:**\n- Returns content with line numbers in `cat -n` format\n- Works with any text file in Documents folder\n- Smart path handling (defaults to ~/Documents/)\n- Supports reading portions of large files\n\n#### `edit_document`\nEdit a document file by replacing exact string matches.\n\n```json\n{\n  \"name\": \"edit_document\",\n  \"arguments\": {\n    \"file_path\": \"proposal.tex\",\n    \"old_string\": \"Hello World\",\n    \"new_string\": \"Hello CUPS MCP\",\n    \"expected_replacements\": 1    // optional, default: 1\n  }\n}\n```\n\n**Features:**\n- Exact string replacement with occurrence validation\n- Returns context snippet showing changes\n- Prevents accidental replacements with count validation\n- Same smart path handling as read_document\n- **Collaborative editing support:** Detects external file changes and shows diffs\n- Prevents overwrites when user has edited file externally\n- Automatically tracks file modifications for safe concurrent editing\n\n#### `check_document_status`\nCheck if a document has been modified externally and show changes.\n\n```json\n{\n  \"name\": \"check_document_status\",\n  \"arguments\": {\n    \"file_path\": \"proposal.tex\"  // or full path\n  }\n}\n```\n\n**Features:**\n- Tracks document modification times and content hashes\n- Detects external changes made by users or other programs\n- Shows unified diff of what changed since last read\n- Helps coordinate collaborative editing between AI and users\n- Essential for preventing conflicting edits in shared documents\n\n**Path handling for save tools:**\n- Simple filename (e.g., `report.pdf`) → Saves to `~/Documents/`\n- Full path (e.g., `/home/user/Documents/report.pdf`) → Uses exact path\n- Path with `~` (e.g., `~/Downloads/report.pdf`) → Expands to home directory\n\n**Automatic features:**\n- Creates Documents directory if it doesn't exist\n- Generates unique filename if file already exists (adds _1, _2, etc.)\n- Returns clear error messages for permission issues or other failures\n\n### AI Agent Guidelines\n\n#### Printer Selection Logic\n\nWhen using the printing tools, AI agents should follow this logic:\n\n1. **First print request:**\n   - If user doesn't specify, ask: \"Would you like to print or save as PDF?\"\n   - If printing and no default printer exists, ask which printer to use\n   - Remember the chosen printer for the session\n\n2. **Subsequent requests:**\n   - Use the remembered printer from the first request\n   - Only change if user explicitly specifies a different printer\n\n#### File Paths\n\nWhen saving PDFs with `markdown_to_pdf`:\n- Use simple filenames (e.g., `report.pdf`) which save to `~/Documents/`\n- Don't assume the user's home directory path\n- Let the tool handle path expansion\n\nThis ensures users aren't repeatedly asked about printer selection and files are saved to predictable locations.\n\n## Configuration for Claude Desktop and Claude Code\n\n### Important: Workspace Path\n\nTeXFlow requires a workspace path where all your document projects will be stored. This is passed as the last argument to the `texflow` command.\n\n### For Claude Desktop\n\nClaude Desktop uses a JSON configuration file to manage MCP servers. The location depends on your operating system:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n#### Method 1: Run from GitHub (Recommended)\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"texflow\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/aaronsb/texflow-mcp.git\", \"texflow\", \"/home/aaron/Documents/TeXFlow\"]\n    }\n  }\n}\n```\n\n**Note**: Replace `/home/aaron/Documents/TeXFlow` with your desired workspace path.\n\n#### Method 2: Run from local directory\n\nIf you've cloned the repository locally:\n\n```json\n{\n  \"mcpServers\": {\n    \"texflow\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/texflow-mcp\", \"run\", \"texflow\", \"/home/aaron/Documents/TeXFlow\"]\n    }\n  }\n}\n```\n\n**Note**: Replace `/path/to/texflow-mcp` with the actual path to your cloned repository.\n\nAfter editing the config file, restart Claude Desktop for the changes to take effect.\n\n### For Claude Code\n\nClaude Code provides a CLI command to add MCP servers. You can choose between different scopes:\n\n- `--scope user`: Available across all your projects (recommended)\n- `--scope project`: Only available in the current project\n- `--scope local`: Available only on this machine\n\n#### Method 1: Run from GitHub (Recommended)\n\n```bash\n# Add with user scope (available in all projects)\nclaude mcp add --scope user texflow uvx -- --from git+https://github.com/aaronsb/texflow-mcp.git texflow ~/Documents/TeXFlow\n\n# Or with project scope (current project only)\nclaude mcp add --scope project texflow uvx -- --from git+https://github.com/aaronsb/texflow-mcp.git texflow ~/Documents/TeXFlow\n```\n\n#### Method 2: Run from local directory\n\nIf you've cloned the repository:\n\n```bash\n# Add with user scope\nclaude mcp add --scope user texflow uv -- --directory /path/to/texflow-mcp run texflow ~/Documents/TeXFlow\n\n# Or with project scope\nclaude mcp add --scope project texflow uv -- --directory /path/to/texflow-mcp run texflow ~/Documents/TeXFlow\n```\n\n**Note**: The `--` after the scope is required to separate Claude Code options from the command arguments.\n\n### Workspace Path Options\n\nYou can specify the workspace path in three ways:\n\n1. **Command line argument**: `~/Documents/TeXFlow` as shown in the examples above\n2. **Environment variable**: Set `TEXFLOW_WORKSPACE=~/Documents/TeXFlow` in your shell or system environment\n3. **Default**: If neither is provided, defaults to `~/Documents/TeXFlow`\n\nAll TeXFlow projects and documents will be created within this workspace directory.\n\n### Verifying Installation\n\nAfter installation, you can verify TeXFlow is working by asking Claude to:\n\n1. List available TeXFlow projects: \"Use texflow to list my projects\"\n2. Check system dependencies: \"Check texflow system dependencies\"\n3. Create a test project: \"Create a new texflow project called 'test'\"\n\n## AI-to-AI Collaboration 🤖🤝🤖\n\nThe collaborative editing features enable fascinating multi-agent workflows:\n\n### Use Cases\n- **Parallel Document Development**: Multiple AI agents can work on different sections simultaneously\n- **Review Workflows**: One AI drafts, another reviews and edits\n- **Specialized Collaboration**: Domain-specific AIs (e.g., technical writer + code reviewer) working together\n- **Iterative Refinement**: AIs can build upon each other's contributions with full visibility\n\n### How It Works\n1. **Agent A** reads and edits a document, establishing a baseline\n2. **Agent B** detects Agent A's changes through the diff system\n3. **Agent B** reviews the changes before making its own contributions\n4. Each agent maintains awareness of others' modifications through the tracking system\n\n### Example Workflow\n```bash\n# Agent 1 (Technical Writer AI)\n- Creates initial documentation structure\n- Writes API reference sections\n\n# Agent 2 (Code Examples AI)  \n- Detects Agent 1's additions\n- Adds code examples to each API section\n- Preserves Agent 1's documentation\n\n# Agent 3 (Review AI)\n- Sees combined work from both agents\n- Fixes inconsistencies\n- Adds cross-references\n```\n\nThis opens up entirely new possibilities for AI collaboration on complex documentation and content creation tasks.\n\n## Examples\n\n### Common Workflows\n\n#### Academic Paper with Citations\n```python\n# Create project structure\nproject(action=\"create\", name=\"ml-paper\", description=\"Machine learning research paper\")\n\n# Create bibliography\ndocument(action=\"create\", content=\"@article{smith2023,...}\", path=\"refs.bib\")\n\n# Create main document\ndocument(action=\"create\", content=\"\\\\documentclass{article}...\", path=\"paper.tex\")\n\n# Export to PDF\noutput(action=\"export\", source=\"paper.tex\", output_path=\"paper.pdf\")\n```\n\n#### Convert and Edit Workflow\n```python\n# Convert existing Markdown notes to LaTeX\ndocument(action=\"convert\", source=\"notes.md\", target_format=\"latex\")\n\n# Edit the converted file\ndocument(action=\"edit\", path=\"notes.tex\", old_string=\"TODO\", new_string=\"Introduction\")\n\n# Generate PDF\noutput(action=\"export\", source=\"notes.tex\")\n```\n\n### Workflow Features\n\nThe system prevents common AI workflow issues:\n\n1. **Smart Content Detection**: The server detects when LaTeX content has already been saved and warns against regenerating it\n2. **Clear Tool Guidance**: Tool descriptions guide the preferred workflow (save → use file path)\n3. **Better Error Handling**: LaTeX error parser provides specific package installation instructions\n\nExample of the improved workflow:\n```python\n# Step 1: Save LaTeX content\nsave_latex(content=\"...\", filename=\"paper.tex\")\n# Returns: \"LaTeX saved successfully to: /home/user/Documents/paper.tex\"\n\n# Step 2: Convert to PDF using file path (not content!)\nlatex_to_pdf(file_path=\"/home/user/Documents/paper.tex\", output_path=\"paper.pdf\")\n# Efficient: Uses saved file instead of regenerating content\n```\n\n## Documentation\n\n- 📖 [Tool Reference](docs/TEXFLOW_REFERENCE.md) - Complete guide to all 9 semantic tools\n- 🤝 [Collaborative Editing Guide](docs/COLLABORATIVE_EDITING.md) - Deep dive into collaboration features\n- 🎯 [LaTeX Reference Design](docs/LATEX_REFERENCE_DESIGN.md) - Design of the LaTeX documentation tool\n- 📄 [System Dependencies](docs/SYSTEM_DEPENDENCIES.md) - System requirements and dependency management\n- 👨‍🍳 [Recipe Book Example](docs/RECIPE_BOOK_EXAMPLE.md) - Practical example creating a recipe book\n- 🚀 [Complete Workflow Example](docs/COMPLETE_WORKFLOW_EXAMPLE.md) - End-to-end workflow examples\n\n## Future Enhancements\n\n- [ ] HTML to PDF printing (via weasyprint)\n- [ ] SVG to PDF printing (via rsvg-convert)\n- [ ] Image format handling and scaling\n- [ ] Print job status tracking\n- [ ] Print job cancellation\n- [ ] Printer options (paper size, orientation, etc.)\n- [ ] Base64 encoded content support\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Ftexflow-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Ftexflow-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Ftexflow-mcp/lists"}