🔨 papersmith

Wrap python-docx in a premium fluent API with native LaTeX equations, citation management, charts, and built-in MCP server for LLMs.

---

🌟 Key Features

• 📝 Fluent Document API — Chainable methods to construct clean, professional documents.
• 📐 Math & Equations — Convert inline $E=mc^2$ or block $$\int x dx$$ into native Office Math (OMML) editable directly inside MS Word.
• 🎨 Style Presets — Apply pre-defined layouts (academic, modern, report, minimal, formal) or construct your own custom design systems.
• 📚 Citation Manager — Full APA, IEEE, Harvard, MLA, and Chicago format engines, featuring BibTeX file imports and clickable cross-references.
• 📊 Integrated Charting — Auto-embed matplotlib bar, line, pie, or scatter plots directly into document blocks.
• 💬 Review & Comments — Easily attach comments, insert tracked changes, and handle footnotes.
• 🛡️ Metadata Scrubbing — Auto-clean author names, edit times, and system metrics to keep documents pristine.
• 🤖 MCP Server — Expose a secure Model Context Protocol (MCP) server containing 25+ tools for Claude Desktop, Cursor, and other LLMs to generate documents.

---

⚙️ Architecture

graph TD
    UserCode[Python API / Markdown CLI] --> PaperSmith[papersmith.SmithDocument]
    PaperSmith --> StylePresets[Style Presets / Layout]
    PaperSmith --> MathModule[LaTeX Equation Renderer]
    PaperSmith --> CitationModule[Citation Manager / BibTeX]
    PaperSmith --> ChartModule[Matplotlib Chart Embedder]
    PaperSmith --> docx[python-docx Engine]
    docx --> OutputDocx[Word Document .docx]
    OutputDocx --> OutputPdf[PDF Export .pdf]

Loading

---

🚀 Quick Start

Installation

pip install papersmith

1. Document Creation with Math & Layouts

from papersmith import SmithDocument

# Initialize with the 'academic' styling preset
doc = SmithDocument(preset="academic")

# Design a title/cover page
doc.add_cover_page(
    title="Asymptotic Complexity & Data Structures",
    subtitle="Analysis of Sorting Algorithms",
    author="Jane Smith",
    institution="Massachusetts Institute of Technology",
    date="October 2026"
)

# Add headers and formatted body text
doc.add_heading("1. Merge Sort Analysis", level=2)
doc.add_text("Merge sort is a divide-and-conquer algorithm with an asymptotic complexity of $O(n \\log n)$.")

# Insert native editable equations
doc.add_equation(r"T(n) = 2T\left(\frac{n}{2}\right) + \Theta(n)")

# Save the document
doc.save("merge_sort_analysis.docx")

2. Citations & Bibliography

from papersmith import SmithDocument

doc = SmithDocument(preset="academic")
doc.citations.style = "ieee"  # Choose from apa, ieee, harvard, mla, chicago

# Import your BibTeX file directly
doc.citations.import_bibtex("references.bib")

# Or register inline sources manually
doc.citations.add_source(
    "knuth1997",
    author="Donald E. Knuth",
    title="The Art of Computer Programming",
    year=1997,
    publisher="Addison-Wesley",
)

doc.add_heading("2. Literature Review", level=2)
doc.add_text("Classic sorting models are comprehensively detailed in {cite:knuth1997}.")

# Automatically resolves keys and formats bibliography
doc.add_bibliography()
doc.save("citations_example.docx")

---

🤖 Model Context Protocol (MCP) Integration

papersmith contains a built-in MCP server that enables LLMs (like Claude or custom GPTs) to programmatically generate Word documents.

Claude Desktop Setup

Add this to your claude_desktop_config.json (typically in %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "papersmith": {
      "command": "papersmith",
      "args": ["mcp-server", "--transport", "stdio"]
    }
  }
}

Cursor Setup

1. Go to Settings -> Features -> MCP.
2. Click + Add New MCP Server.
3. Name: papersmith
4. Type: command
5. Command: papersmith mcp-server --transport stdio

---

💻 Command Line Interface (CLI)

The package exposes a papersmith CLI entry point with command helpers:

# Convert a Markdown file directly to docx using a style preset
papersmith convert report.md -o report.docx --preset report

# Convert markdown with custom author details
papersmith generate notes.md -o output.docx --preset modern --author "Alice"

# Scrub metadata (Creator, total edit time, revisions) from a file
papersmith scrub output.docx --author "Public Author"

# View all available style presets
papersmith presets

# Launch the MCP server
papersmith mcp-server --transport stdio

---

🛠️ Development & Testing

# Clone the repository
git clone https://github.com/imnb57/papersmith.git
cd papersmith

# Install development dependencies
pip install -e ".[dev]"

# Run tests & verify coverage
pytest

# Format & Lint
ruff check src/ tests/ --fix
ruff format src/ tests/

# Run type checker
mypy src/papersmith/

---

🚀 PyPI Releases

To publish a new release:

1. Bump the version in pyproject.toml.
2. Tag the commit and push it:

   git tag v0.1.4
   git push origin v0.1.4

3. The GitHub Actions release workflow (.github/workflows/release.yml) will automatically publish the built assets to PyPI using OIDC Trusted Publishing.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.