Yowes

Yowes — Canva Education Document Generator

Headless MCP server that generates teacher verification documents — employment letters, teacher ID cards, teaching licenses, payslips, and more — across 13 countries.

[](LICENSE) [](https://www.python.org/) [](https://modelcontextprotocol.io)

Portable, self-contained, and installable anywhere.

---

Table of Contents

• [Sample outputs](#sample-outputs)
• [Features](#features)
• [Supported countries](#supported-countries)
• [Requirements](#requirements)
• [Installation](#installation)
• [Usage — MCP server](#usage--mcp-server)
• [Legacy GUI](#legacy-gui)
• [Project structure](#project-structure)
• [Adding a new country](#adding-a-new-country)
• [License](#license)

---

Sample outputs

Documents are rendered as high-resolution PNGs. Examples generated by this tool:

| Teacher ID (US) | Employment letter (US) | |:---:|:---:| | | |

| Teacher ID (UK) | Employment letter (UK) | |:---:|:---:| | | |

---

Features

• Headless MCP server — document generation exposed as agent-callable tools over stdio.
• 13 countries, each with its own document types and local conventions.
• Real school databases with street addresses, districts, and contact info.
• Consistent profile photos per person — hash-based selection from a bundled, gender-aware photo pool.
• Cross-platform fonts — DejaVu Sans bundled; no system-font dependency.
• Packaged & portable — ships as a self-contained wheel (code + photos + fonts) installable with one command.

---

Supported countries

| Code | Country | Document types | |------|---------|----------------| | uk | United Kingdom | employmentletter, teacherid, teachinglicense | | us | United States | employmentletter, teacherid, teachinglicense | | france | France | installationstatement, iprofscreenshot, bylawsextract, teachingcertificate | | netherlands | Netherlands | employmentcontract, teacherregistration, duodeclaration, schoolid | | indonesia | Indonesia | payslip, teachingexperienceletter, nuptkcard, appointmentletter | | australia | Australia | signedschoolletter, schoolid, teachinglicense | | canada | Canada | octcard, teachinglicense, signedschoolletter | | spain | Spain | teachingid, signedschoolletter, employmentcontract | | argentina | Argentina | payslip, employmentcertificate, signedschoolletter | | slovakia | Slovakia | payslip, employmentletter, signedschoolletter | | mexico | Mexico | teachingid, signedschoolletter, employmentcertificate | | philippines | Philippines | teachingid, employmentcertificate, teachinglicense | | thailand | Thailand | payslip, letterof_employment |

---

Requirements

• Python 3.10+
• Dependencies (installed automatically): Pillow, mcp

---

Installation

From the built wheel

pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl

From source (editable)

pip install -e .

Via uv

uvx --from . yowes-mcp

---

Usage — MCP server

The server speaks MCP over stdio — the transport used by most agent runtimes (Hermes, Claude Desktop, and any MCP client). Connect it, discover the tools, then call them.

Step 1 — Install & verify

# from the built wheel
pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl

# or editable from source
pip install -e .

Verify the install and that bundled assets resolve:

python -c "from countries.utils import load_font, get_profile_photo; \
print(load_font(30).getname()); print(get_profile_photo((280,340), person_id='x', gender='Male') is not None)"
# ('DejaVu Sans', 'Book')    The MCP server is the primary, headless interface. The GUI is optional and not required for the skill.

---

## Project structure

yowes/ ├── countries/ # Document generation core (package) │ ├── base.py # CountryGenerator ABC (contract) │ ├── utils.py # Fonts, profile photos, shared helpers │ ├── foto/ # Bundled profile photos (package data) │ ├── fonts/ # Bundled DejaVu fonts (package data) │ └── / # One package per country ├── mcpserver.py # MCP server exposing tools ├── maingui.py # Legacy tkinter GUI ├── docs/examples/ # Sample rendered documents ├── pyproject.toml # Packaging, deps, entry point ├── output/ # Generated documents (git-ignored) └── run.bat # Windows GUI launcher

---

## Adding a new country

1. Create `countries//__init__.py` with a class inheriting `countries.base.CountryGenerator`.
2. Implement the abstract methods: `get_country_name`, `get_country_code`, `get_schools_data`, `get_first_names`, `get_last_names`, `get_positions`, `get_document_types`, `generate_document`.
3. Register it in `countries/__init__.py` via `register_country("", Generator)`.
4. Optionally add a display label in `main_gui.py` (`get_country_list` / `on_country_change`).

The new country is automatically picked up by the MCP `list_countries_tool` and `list_schools`.

---

## Contributors

- **[Masanto](https://github.com/hirotomasato)** — author & maintainer

---

## License

[MIT](./LICENSE) © 2026 hirotomasato

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hirotomasato](https://github.com/hirotomasato)
- **Source:** [hirotomasato/yowes](https://github.com/hirotomasato/yowes)
- **License:** MIT

Install and usage instructions live in the source repository linked above.