Skip to content
Back to search

yowes

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hirotomasato--yowes/badge.svg)](/listings/hirotomasato--yowes)

HTML

<a href="/listings/hirotomasato--yowes"><img src="/api/listings/hirotomasato--yowes/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 299 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Yowes — Canva Education Document Generator
  3. **Headless MCP server** that generates teacher verification documents — employment letters, teacher ID cards, teaching licenses, payslips, and more — across **13 countries**.
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  5. [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
  6. [![MCP](https://img.shields.io/badge/MCP-stdio-brightgreen.svg)](https://modelcontextprotocol.io)
  7. ![Platform](https://img.shields.io/badge/platform-win%20%7C%20linux%20%7C%20macOS-lightgrey.svg)
  8. *Portable, self-contained, and installable anywhere.*
  9. </div>
  10. ---
  11. ## Table of Contents
  12. - [Sample outputs](#sample-outputs)
  13. - [Features](#features)
  14. - [Supported countries](#supported-countries)
  15. - [Requirements](#requirements)
  16. - [Installation](#installation)
  17. - [Usage — MCP server](#usage--mcp-server)
  18. - [Legacy GUI](#legacy-gui)
  19. - [Project structure](#project-structure)
  20. - [Adding a new country](#adding-a-new-country)
  21. - [License](#license)
  22. ---
  23. ## Sample outputs
  24. Documents are rendered as high-resolution PNGs. Examples generated by this tool:
  25. | Teacher ID (US) | Employment letter (US) |
  26. |:---:|:---:|
  27. | ![US teacher ID](docs/examples/example_us_teacher_id.png) | ![US letter](docs/examples/example_us_letter.png) |
  28. | Teacher ID (UK) | Employment letter (UK) |
  29. |:---:|:---:|
  30. | ![UK teacher ID](docs/examples/example_uk_teacher_id.png) | ![UK letter](docs/examples/example_uk_letter.png) |
  31. ---
  32. ## Features
  33. - **Headless MCP server** — document generation exposed as agent-callable tools over stdio.
  34. - **13 countries**, each with its own document types and local conventions.
  35. - **Real school databases** with street addresses, districts, and contact info.
  36. - **Consistent profile photos** per person — hash-based selection from a bundled, gender-aware photo pool.
  37. - **Cross-platform fonts** — DejaVu Sans bundled; no system-font dependency.
  38. - **Packaged & portable** — ships as a self-contained wheel (code + photos + fonts) installable with one command.
  39. ---
  40. ## Supported countries
  41. | Code | Country | Document types |
  42. |------|---------|----------------|
  43. | `uk` | United Kingdom | employment_letter, teacher_id, teaching_license |
  44. | `us` | United States | employment_letter, teacher_id, teaching_license |
  45. | `france` | France | installation_statement, iprof_screenshot, bylaws_extract, teaching_certificate |
  46. | `netherlands` | Netherlands | employment_contract, teacher_registration, duo_declaration, school_id |
  47. | `indonesia` | Indonesia | payslip, teaching_experience_letter, nuptk_card, appointment_letter |
  48. | `australia` | Australia | signed_school_letter, school_id, teaching_license |
  49. | `canada` | Canada | oct_card, teaching_license, signed_school_letter |
  50. | `spain` | Spain | teaching_id, signed_school_letter, employment_contract |
  51. | `argentina` | Argentina | payslip, employment_certificate, signed_school_letter |
  52. | `slovakia` | Slovakia | payslip, employment_letter, signed_school_letter |
  53. | `mexico` | Mexico | teaching_id, signed_school_letter, employment_certificate |
  54. | `philippines` | Philippines | teaching_id, employment_certificate, teaching_license |
  55. | `thailand` | Thailand | payslip, letter_of_employment |
  56. ---
  57. ## Requirements
  58. - Python **3.10+**
  59. - Dependencies (installed automatically): `Pillow`, `mcp`
  60. ---
  61. ## Installation
  62. ### From the built wheel
  63. ```bash
  64. pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl
  65. ```
  66. ### From source (editable)
  67. ```bash
  68. pip install -e .
  69. ```
  70. ### Via uv
  71. ```bash
  72. uvx --from . yowes-mcp
  73. ```
  74. ---
  75. ## Usage — MCP server
  76. 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.
  77. ### Step 1 — Install & verify
  78. ```bash
  79. # from the built wheel
  80. pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whl
  81. # or editable from source
  82. pip install -e .
  83. ```
  84. Verify the install and that bundled assets resolve:
  85. ```bash
  86. python -c "from countries.utils import load_font, get_profile_photo; \
  87. print(load_font(30).getname()); print(get_profile_photo((280,340), person_id='x', gender='Male') is not None)"
  88. # ('DejaVu Sans', 'Book') <-- bundled font, not system
  89. # True <-- bundled photo found
  90. ```
  91. ### Step 2 — Run the server
  92. ```bash
  93. # After install:
  94. yowes-mcp
  95. # Or from source:
  96. python mcp_server.py
  97. ```
  98. It blocks and waits for MCP requests over stdin/stdout — don't run it as a foreground terminal app expecting prompts.
  99. ### Step 3 — Register in your agent runtime
  100. Point your MCP client at the `yowes-mcp` command:
  101. ```json
  102. {
  103. "mcpServers": {
  104. "yowes": {
  105. "command": "yowes-mcp",
  106. "args": []
  107. }
  108. }
  109. }
  110. ```
  111. If `yowes-mcp` isn't on your `PATH`, use the absolute path to your interpreter and module instead:
  112. ```json
  113. {
  114. "mcpServers": {
  115. "yowes": {
  116. "command": "/path/to/python",
  117. "args": ["-m", "mcp_server"]
  118. }
  119. }
  120. }
  121. ```
  122. ### Tools
  123. | Tool | Description |
  124. |------|-------------|
  125. | `list_countries_tool` | List available countries, display names, and their document types. |
  126. | `list_schools(country)` | List all schools for a country code. |
  127. | `generate_documents(...)` | Render one or more documents to PNG and return their paths. |
  128. #### `list_countries_tool()`
  129. No arguments. Returns one result item per country — `{ code, name, document_types }`. (Because a list return is split into one MCP content item per entry, iterate `content` to see them all.)
  130. #### `list_schools(country: str)`
  131. - `country` *(required)* — country code from `list_countries_tool` (e.g. `"us"`).
  132. - Returns one result item per school — `{ name, address, town, postcode, state, phone, lea }`. Iterate `content` to see them all.
  133. #### `generate_documents(...)`
  134. | Parameter | Type | Required | Default | Description |
  135. |-----------|------|----------|---------|-------------|
  136. | `country` | string | ✅ | — | Country code (e.g. `"us"`, `"uk"`). |
  137. | `first_name` | string | ✅ | — | Teacher's first name. |
  138. | `last_name` | string | ✅ | — | Teacher's last name. |
  139. | `school_name` | string | ✅ | — | Exact or partial school name (matched against that country's school list). |
  140. | `position` | string | ✅ | — | Teaching position/title. |
  141. | `date_of_birth` | string | ✅ | — | DOB string, printed on the teacher ID (e.g. `"12/05/1988"`). |
  142. | `gender` | string | — | `"Random"` | `"Random"`, `"Male"`, or `"Female"` — selects the profile-photo pool. |
  143. | `document_types` | string[] | — | all types | Which documents to render, e.g. `["employment_letter", "teacher_id"]`. |
  144. | `output_dir` | string | — | `output/` | Where to save PNGs (relative to the server's working dir). |
  145. Returns `{ country, school, document_types, files, count, output_dir }` — `files` are absolute PNG paths.
  146. ### Connect from a Python client
  147. Minimal working client (requires `pip install mcp`):
  148. ```python
  149. import asyncio
  150. from mcp import ClientSession, StdioServerParameters
  151. from mcp.client.stdio import stdio_client
  152. async def main():
  153. params = StdioServerParameters(command="yowes-mcp", args=[])
  154. async with stdio_client(params) as (read, write):
  155. async with ClientSession(read, write) as session:
  156. await session.initialize()
  157. countries = await session.call_tool("list_countries_tool", {})
  158. # A list return is split into one content item per entry:
  159. for item in countries.content:
  160. print(item.text)
  161. res = await session.call_tool("generate_documents", {
  162. "country": "us",
  163. "first_name": "John",
  164. "last_name": "Smith",
  165. "school_name": "Valley High",
  166. "position": "Head of Science Department",
  167. "date_of_birth": "12/05/1988",
  168. "gender": "Male",
  169. })
  170. print(res.content[0].text)
  171. asyncio.run(main())
  172. ```
  173. ### Typical agent workflow
  174. 1. Call `list_countries_tool` to see what's available.
  175. 2. Call `list_schools("us")` to pick a real school.
  176. 3. Call `generate_documents(...)` with the chosen country, school, and person details.
  177. 4. Read the returned PNG paths and use the files.
  178. Generated PNGs are written to `output/` (or the `output_dir` you pass).
  179. ---
  180. ## Legacy GUI
  181. A tkinter (CustomTkinter) GUI is still available for manual use. The core generation logic is shared.
  182. ```bash
  183. python main_gui.py # on Windows, use run.bat (sets TCL_LIBRARY)
  184. ```
  185. > The MCP server is the primary, headless interface. The GUI is optional and not required for the skill.
  186. ---
  187. ## Project structure
  188. ```
  189. yowes/
  190. ├── countries/ # Document generation core (package)
  191. │ ├── base.py # CountryGenerator ABC (contract)
  192. │ ├── utils.py # Fonts, profile photos, shared helpers
  193. │ ├── foto/ # Bundled profile photos (package data)
  194. │ ├── fonts/ # Bundled DejaVu fonts (package data)
  195. │ └── <country>/ # One package per country
  196. ├── mcp_server.py # MCP server exposing tools
  197. ├── main_gui.py # Legacy tkinter GUI
  198. ├── docs/examples/ # Sample rendered documents
  199. ├── pyproject.toml # Packaging, deps, entry point
  200. ├── output/ # Generated documents (git-ignored)
  201. └── run.bat # Windows GUI launcher
  202. ```
  203. ---
  204. ## Adding a new country
  205. 1. Create `countries/<code>/__init__.py` with a class inheriting `countries.base.CountryGenerator`.
  206. 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`.
  207. 3. Register it in `countries/__init__.py` via `register_country("<code>", <Name>Generator)`.
  208. 4. Optionally add a display label in `main_gui.py` (`get_country_list` / `on_country_change`).
  209. The new country is automatically picked up by the MCP `list_countries_tool` and `list_schools`.
  210. ---
  211. ## Contributors
  212. - **[Masanto](https://github.com/hirotomasato)** — author & maintainer
  213. ---
  214. ## License
  215. [MIT](./LICENSE) © 2026 hirotomasato

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.