# Yowes

> Generate realistic teacher documents (ID cards, licenses, letters) for 13 countries via MCP.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hirotomasato-yowes`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hirotomasato](https://agentstack.voostack.com/s/hirotomasato)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hirotomasato](https://github.com/hirotomasato)
- **Source:** https://github.com/hirotomasato/yowes

## Install

```sh
agentstack add mcp-hirotomasato-yowes
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 | employment_letter, teacher_id, teaching_license |
| `us` | United States | employment_letter, teacher_id, teaching_license |
| `france` | France | installation_statement, iprof_screenshot, bylaws_extract, teaching_certificate |
| `netherlands` | Netherlands | employment_contract, teacher_registration, duo_declaration, school_id |
| `indonesia` | Indonesia | payslip, teaching_experience_letter, nuptk_card, appointment_letter |
| `australia` | Australia | signed_school_letter, school_id, teaching_license |
| `canada` | Canada | oct_card, teaching_license, signed_school_letter |
| `spain` | Spain | teaching_id, signed_school_letter, employment_contract |
| `argentina` | Argentina | payslip, employment_certificate, signed_school_letter |
| `slovakia` | Slovakia | payslip, employment_letter, signed_school_letter |
| `mexico` | Mexico | teaching_id, signed_school_letter, employment_certificate |
| `philippines` | Philippines | teaching_id, employment_certificate, teaching_license |
| `thailand` | Thailand | payslip, letter_of_employment |

---

## Requirements

- Python **3.10+**
- Dependencies (installed automatically): `Pillow`, `mcp`

---

## Installation

### From the built wheel

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

### From source (editable)

```bash
pip install -e .
```

### Via uv

```bash
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

```bash
# 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:

```bash
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
├── mcp_server.py         # MCP server exposing tools
├── main_gui.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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hirotomasato-yowes
- Seller: https://agentstack.voostack.com/s/hirotomasato
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.