Content
# 🔨 papersmith
> **Wrap python-docx in a premium fluent API** with native LaTeX equations, citation management, charts, and built-in MCP server for LLMs.
[](https://github.com/imnb57/papersmith/actions/workflows/ci.yml)
[](https://pypi.org/project/papersmith/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://peps.python.org/pep-0561/)
---
## 🌟 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
```mermaid
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]
```
---
## 🚀 Quick Start
### Installation
```bash
pip install papersmith
```
### 1. Document Creation with Math & Layouts
```python
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
```python
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):
```json
{
"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:
```bash
# 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
```bash
# 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:
```bash
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](LICENSE) file for details.
