Chapgar

KO | EN

gitlite — search

#reactjs #animation #rag #artificial-intelligence #containers #vue #markdown #electron #windows #framework

(★ 9)

Equip your AI agents (Claude, Cursor, etc.) to instantly compile beautiful Persian PDFs with zero LaTeX dependencies using Typst.

File Explorer

ZIP Download

- - ci.yml
- logo.png
- __init__.py
- generator.py
- - test_mcp_server.py
  - test_pdf_compilation.py
- - test_error_handling.py
  - test_path_resolution.py
  - test_preamble.py
  - test_sanitize_markup.py
- conftest.py
- test_chapgar.py
.gitignore
LICENSE
pyproject.toml
README.md
server.py

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Chapgar (چاپگر)</h1>

<p align="center">
  <em>Model Context Protocol (MCP) Server for Flawless Right-to-Left (RTL) Persian PDF Generation powered by Typst.</em>
</p>

**Chapgar** (چاپگر - Persian for *Printer*) enables AI agents (such as Claude Desktop, Antigravity IDE, Cursor, or Windsurf) to generate beautiful, pixel-perfect Persian PDFs with native Right-to-Left formatting, zero bidirectional layout glitches, embedded typography, and automatic digit localization.

---

## 🎭 Before / after

You ask your AI agent for a Persian PDF report. Without Chapgar, your agent attempts to write raw LaTeX, struggles with `xepersian` dependencies, fails to load local fonts, breaks alignment when mixing English words, and hallucinates complex build commands.

With Chapgar via MCP:

```typst
= گزارش فروش
این یک گزارش ساده است که شامل اعداد 123 و کلمات انگلیسی مانند Report می‌باشد.
```

*That's it. The agent just writes plain content. Chapgar automatically handles the Right-to-Left layout, embeds the Vazirmatn font, converts `123` to `۱۲۳`, and compiles the PDF instantly.*

---

## ⚙️ How it works

When an AI agent calls the `generate_persian_pdf` MCP tool, it doesn't need to know anything about Persian typography. Chapgar takes the raw input and applies a robust pipeline before compilation:

```text
1. Font Injection      → Automatically loads the selected embedded Persian font.
2. Directionality      → Enforces global Right-to-Left document flow.
3. Digit Localization  → Converts standard numerals (0-9) to Persian digits (۰-۹).
4. BiDi Handling       → Leverages Typst to seamlessly mix Persian, English, and code.
5. Clean Execution     → Compiles locally and returns the PDF path.
```

---

## 📊 The Impact

Large Language Models are notoriously bad at generating correct LaTeX for RTL languages. They often waste time (and context window tokens) outputting huge preambles, debugging font errors, and explaining why the PDF compilation failed.

By delegating the layout and compilation to Chapgar:
- **Less boilerplate** generated by the agent.
- **100% correct** RTL and BiDi rendering.
- **Zero** LaTeX dependencies or environment setup.
- **Cheaper and faster** agent responses.

---

## ✨ Features

- 🟢 **MCP Native**: Plugs directly into any Model Context Protocol host as a dedicated tool (`generate_persian_pdf`).
- ⚡ **Powered by Typst**: Blazing fast compilation without heavy TeX/LaTeX dependencies.
- 🔤 **Multiple High-Quality Persian Fonts**: Choose between **Vazirmatn** (modern & clean), **Estedad** (geometric & bold), **Shabnam** (rounded & friendly), **Sahel** (compact), **Amiri** (classical naskh), and **Noto Naskh Arabic** (maximum glyph coverage) out of the box.
- 📐 **Configurable Page Dimensions**: Native support for standard paper formats (`A4`, `Letter`, `A5`, `A3`, `Legal`, etc.).
- 🖼️ **Optional PNG Previews**: Compile high-resolution image thumbnails alongside your PDFs for instant chat previews.
- ↔️ **Flawless RTL & BiDi Handling**: Native handling of mixed Persian and English text, inline code, mirrored brackets/parentheses, bullet points, and RTL tables.
- 🔢 **Automatic Digit Localization**: Built-in rules to automatically map Western numerals (`0-9`) to Persian numerals (`۰-۹`).
- 🔒 **Safe & Thread-Isolated Execution**: Thread-safe isolated temporary directory compilation, with all writes confined to a configurable output directory (path traversal and absolute paths outside it are rejected).
- 🧠 **Context-Aware Error Reporting**: Translates raw Typst compiler errors into precise line-number hints for self-correcting AI agents.

---

## 📦 Installation

1. **Clone the repository**:
   ```bash
   git clone https://github.com/hosseinrezaie0/Chapgar.git
   cd Chapgar
   ```

2. **Create a virtual environment & install dependencies**:
   ```bash
   python -m venv .venv
   
   .venv\Scripts\activate
   
   # Linux / macOS
   source .venv/bin/activate
   
   pip install -r requirements.txt
   ```

3. **(Optional) Install as an editable package**:
   ```bash
   pip install -e .
   ```

---

## 📁 Output Directory

All generated files are written inside a single **output directory** (a jail). Chapgar refuses to write outside it, so an agent cannot overwrite arbitrary files on your disk via a crafted filename.

| | |
|---|---|
| **Default** | `~/Documents/Chapgar` (e.g. `C:\Users\You\Documents\Chapgar`). Falls back to `~/Chapgar` if no Documents folder exists (some localized Linux setups). |
| **Override** | Set the `CHAPGAR_OUTPUT_DIR` environment variable |

The directory is created automatically on first use. `output_filename` is always resolved *relative to this root*:

```text
report.pdf            → <output-dir>/report.pdf
invoices/march.pdf    → <output-dir>/invoices/march.pdf   (subfolders auto-created)
../../../secrets.pdf  → ✗ rejected: "Security violation"
C:\Windows\evil.pdf   → ✗ rejected: "Security violation"
```

To choose your own location, add an `env` block to your MCP config (works with every host below):

```json
"env": { "CHAPGAR_OUTPUT_DIR": "C:\\Users\\You\\Documents\\Chapgar" }
```

---

## ⚙️ MCP Integration Guide

Add **Chapgar** to your preferred AI app or agent framework using the configuration guides below (replace paths with your actual project location):

---

### 1. 🟧 Claude Desktop

Add to your `claude_desktop_config.json`:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "chapgar": {
      "command": "C:\\path\\to\\Chapgar\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\Chapgar\\server.py"
      ],
      "env": { "CHAPGAR_OUTPUT_DIR": "C:\\Users\\You\\Documents\\Chapgar" }
    }
  }
}
```

> The `env` block is optional — omit it to use the default `~/Documents/Chapgar` output directory (see [Output Directory](#-output-directory)).

---

### 2. 🪄 Cursor

Add to your workspace or global `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "chapgar": {
      "command": "C:\\path\\to\\Chapgar\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\Chapgar\\server.py"
      ]
    }
  }
}
```

---

### 3. 🌊 Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "chapgar": {
      "command": "C:\\path\\to\\Chapgar\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\Chapgar\\server.py"
      ]
    }
  }
}
```

---

### 4. ⚡ OpenCode CLI (`opencode`)

Add to `opencode.json` (or `~/.config/opencode/opencode.json`):

```json
{
  "mcp": {
    "chapgar": {
      "type": "local",
      "command": [
        "C:\\path\\to\\Chapgar\\.venv\\Scripts\\python.exe",
        "C:\\path\\to\\Chapgar\\server.py"
      ]
    }
  }
}
```

Or run via CLI:
```bash
opencode mcp add chapgar -- "C:\path\to\Chapgar\.venv\Scripts\python.exe" "C:\path\to\Chapgar\server.py"
```

---

### 5. 🌐 AnythingLLM Desktop

- **Via GUI**: **Settings** (⚙️) ➔ **Agent Skills** / **MCP Servers** ➔ **Add Custom MCP Server** (Command: Python path, Args: `server.py` path).
- **Via Config**: Edit `%APPDATA%\anythingllm-desktop\mcp.json`:

```json
{
  "mcpServers": {
    "chapgar": {
      "command": "C:\\path\\to\\Chapgar\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\Chapgar\\server.py"
      ]
    }
  }
}
```

---

### 6. 🚀 Antigravity IDE

Add to `.agents/mcp.json` (workspace) or `~/.gemini/config/mcp.json` (global):

```json
{
  "mcpServers": {
    "chapgar": {
      "command": "C:\\path\\to\\Chapgar\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\Chapgar\\server.py"
      ]
    }
  }
}
```

---

## 🚀 Usage

Once connected via MCP, your AI assistant can use the `generate_persian_pdf` tool automatically when asked to build PDFs in Persian.

### Tool Parameters
- `typst_markup` (*string, required*): The raw Typst markup body.
- `output_filename` (*string, optional*): Output path **relative to the [output directory](#-output-directory)** (e.g. `report.pdf`, `invoices/march.pdf`). Paths resolving outside it are rejected. Default: `output.pdf`.
- `font_family` (*string, optional*): Font choice: `"Vazirmatn"` (default), `"Estedad"`, `"Shabnam"`, `"Sahel"`, `"Amiri"`, or `"noto-naskh"`.
- `paper_size` (*string, optional*): Paper dimensions: `"a4"` (default), `"letter"`, `"a5"`, `"a3"`, `"legal"`.
- `generate_preview` (*boolean, optional*): If `True`, also generates a PNG thumbnail of the first page. Default: `False`.
- `persian_digits` (*boolean, optional*): If `True` (default), automatically converts document body ASCII digits (`0-9`) to Persian digits (`۰-۹`).
- `page_numbers` (*boolean, optional*): If `True` (default), shows page numbers at the bottom of each page. Set `False` for single-page documents like letters or invoices.

### Direct Python API Usage
You can also invoke the core generator programmatically in Python:

```python
from core.generator import create_pdf

typst_markup = """
= گزارش نمونه
این یک متن نمونه فارسی است که با فونت *استعداد* رندر شده است.

- آیتم اول
- آیتم دوم
"""

result = create_pdf(
    typst_markup,
    output_filename="sample.pdf",
    font_family="Estedad",
    paper_size="a4",
    generate_preview=True,
    base_dir="./out"      # output jail root; defaults to "." for direct API use
)

print(f"PDF created at: {result['pdf_path']}")
if result.get("preview_path"):
    print(f"Preview image: {result['preview_path']}")
```

> Note: `create_pdf` takes the jail root as an explicit `base_dir` argument (default `"."`). The `CHAPGAR_OUTPUT_DIR` environment variable is read by the MCP server layer, not by `create_pdf` itself.

---

## 🧪 Testing

Chapgar includes a modular test suite separated into unit and integration tests:

```bash
# Run all tests
pytest -v

# Run fast unit tests only
pytest tests/unit -v

# Run integration tests (PDF compilation & MCP server)
pytest tests/integration -v

# Run by pytest marker
pytest -m unit
pytest -m integration
```

To run the visual rendering stress test:

```bash
python tests/test_chapgar.py
```

---

## 📂 Project Structure

```
Chapgar/
├── LICENSE                        # MIT License
├── pyproject.toml                 # PEP 517/621 packaging & metadata
├── requirements.txt               # Dependencies (fastmcp, typst, pytest)
├── server.py                      # FastMCP server entry point & tool definitions
├── core/
│   ├── generator.py               # Thread-safe Typst engine, preamble, sanitization & errors
│   └── assets/
│       └── fonts/                 # Embedded Persian & Arabic fonts (OFL licensed)
└── tests/
    ├── conftest.py                # Pytest fixtures (sample Persian & BiDi markup)
    ├── test_chapgar.py            # RTL, ZWNJ & BiDi visual stress test script
    ├── unit/                      # Isolated unit tests
    │   ├── test_error_handling.py    # Error formatting and offset translation tests
    │   ├── test_path_resolution.py   # Safe path handling and directory resolution tests
    │   ├── test_preamble.py          # Font, paper size, and RTL preamble generation tests
    │   └── test_sanitize_markup.py   # LLM markup wrapper sanitization tests
    └── integration/               # End-to-end integration tests
        ├── test_mcp_server.py        # FastMCP tool invocation and response verification
        └── test_pdf_compilation.py   # PDF compilation, font embedding, preview image generation
```

---

## 🔤 Font Acknowledgments

- **[Vazirmatn](https://github.com/rastikerdar/vazirmatn)** by Saber Rastikerdar (OFL License)
- **[Estedad](https://github.com/aminabedini/Estedad)** by Amin Abedini (OFL License)
- **[Shabnam](https://github.com/rastikerdar/shabnam-font)** by Saber Rastikerdar (OFL License)
- **[Sahel](https://github.com/rastikerdar/sahel-font)** by Saber Rastikerdar (OFL License)
- **[Amiri](https://github.com/aliftype/amiri)** by Khaled Hosny (OFL License)
- **[Noto Naskh Arabic](https://github.com/notofonts/arabic)** by Google (OFL License)

---

## 📜 License

This project is licensed under the [MIT License](LICENSE).

Chapgar

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README