Yowesは、教師関連の書類を高解像度のPNGファイルとして生成する、ポータブルなPythonアプリケーションです。ヘッドレスのModel Context Protocol（MCP）サーバーは、stdioを介して書類生成機能を公開するため、Claude Desktop、Hermes、その他のMCPクライアントなどのエージェントランタイムから利用できます。
このプロジェクトは、13か国、国別の書類タイプ、同梱フォントとプロフィール写真、住所や連絡先を含む学校データに対応しています。このチュートリアルでは、インストール、サーバー設定、MCPツールの使用方法、Pythonとの統合、拡張方法について説明します。
Yowesの機能
Yowesは、教師プロフィールと選択した学校から、地域に合わせた教師関連書類を作成します。国によって、雇用証明書、教師ID、教員免許、給与明細、学校ID、契約書、証明書など、さまざまな形式の書類を生成できます。
生成されたファイルはPNG画像として保存されます。アプリケーションにはDejaVu Sansフォントとプロフィール写真がパッケージに含まれているため、実行時にシステムフォントや外部画像アセットに依存しません。
対応国
利用可能な国コードと書類タイプは次のとおりです。
- イギリス：雇用証明書、教師ID、教員免許。
- アメリカ合衆国：雇用証明書、教師ID、教員免許。
- フランス：着任証明書、iProfスクリーンショット、規約抜粋、教員証明書。
- オランダ：雇用契約書、教師登録証、DUO申告書、学校ID。
- インドネシア：給与明細、教職経験証明書、NUPTKカード、任命書。
- オーストラリア：署名済み学校書簡、学校ID、教員免許。
- カナダ：OCTカード、教員免許、署名済み学校書簡。
- スペイン：教師ID、署名済み学校書簡、雇用契約書。
- アルゼンチン：給与明細、雇用証明書、署名済み学校書簡。
- スロバキア：給与明細、雇用証明書、署名済み学校書簡。
- メキシコ：教師ID、署名済み学校書簡、雇用証明書。
- フィリピン：教師ID、雇用証明書、教員免許。
- タイ：給与明細、雇用証明書。
これらの書類は、正当なテスト、デモンストレーション、または許可を受けた事務手続きに限って使用してください。関連機関によって発行・検証されていない生成書類を、公式な資格証明として提示してはいけません。
要件
YowesにはPython 3.10以降が必要です。主な依存関係であるPillowとmcpは、パッケージのインストール時に自動的にインストールされます。
このプロジェクトはWindows、Linux、macOSに対応しています。フォントと写真が同梱されているため、パッケージ化されたアプリケーションはポータブルに設計されています。
Yowesのインストール
wheelからインストールする
distディレクトリにビルド済みのwheelがある場合は、次のコマンドでインストールします。
pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whlソースからインストールする
開発やローカルでの試用では、プロジェクトを編集可能モードでインストールします。
pip install -e .uvで実行する
uvを使ってプロジェクトを起動することもできます。
uvx --from . yowes-mcp同梱アセットを確認する
インストール後、同梱フォントとプロフィール写真のヘルパーが正しく解決されることを確認します。
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フォントが報告され、同梱プロフィール写真についてTrueが返されます。
MCPサーバーに接続する
Yowesはstdioを使ってMCP経由で通信します。インストール済みのコマンドを次のように起動します。
yowes-mcpまた、ソースツリーから直接作業する場合は、次のように実行します。
python mcp_server.pyプロセスは標準入力でMCPリクエストを待ち、標準出力にレスポンスを書き込みます。対話型のターミナルアプリケーションとして動作するようには設計されていません。
MCPクライアントにYowesを登録する
MCP互換のエージェントランタイムから、実行ファイルを指定します。
{
"mcpServers": {
"yowes": {
"command": "yowes-mcp",
"args": []
}
}
}コマンドがPATHで利用できない場合は、Pythonの絶対パスを使用してサーバーモジュールを起動します。
{
"mcpServers": {
"yowes": {
"command": "/path/to/python",
"args": ["-m", "mcp_server"]
}
}
}利用可能なMCPツールを確認する
サーバーは3つの主要なツールを提供します。
list_countries_toolは、国コード、表示名、書類タイプを一覧表示します。list_schools(country)は、選択した国の学校を一覧表示します。generate_documents(...)は、1つ以上の書類を生成し、ファイルパスを返します。
国を一覧表示する
引数なしでlist_countries_toolを呼び出します。レスポンスには国ごとに1つの結果項目が含まれ、code、name、document_typesなどの値が格納されます。リストは複数のMCPコンテンツ項目に分割されているため、返されたcontentコレクションを反復処理して、すべての国を確認してください。
学校を一覧表示する
国コードをlist_schoolsに渡します。
{
"country": "us"
}
各学校の検索結果には、学校名、住所、町、市外局番、州、電話番号、地域の教育当局に関する情報が含まれる場合があります。ドキュメントを生成する際は、このツールが返した学校名の完全一致または部分一致の値を使用してください。
ドキュメントを生成する
generate_documents ツールには、国、教師名、学校、役職、生年月日が必要です。性別、ドキュメントの種類、出力ディレクトリは任意で指定できます。
リクエスト例
{
"country": "us",
"first_name": "John",
"last_name": "Smith",
"school_name": "Valley High",
"position": "Head of Science Department",
"date_of_birth": "12/05/1988",
"gender": "Male",
"document_types": ["employment_letter", "teacher_id"],
"output_dir": "output"
}gender の値には Random、Male、Female を指定できます。これは、同梱されたプロフィール写真プールからの選択を制御します。document_types を省略すると、Yowes は選択した国で利用可能なすべてのドキュメント種類を生成します。デフォルトの出力ディレクトリは output/ です。
成功したレスポンスには、選択した国と学校、ドキュメントの種類、生成されたファイルパス、件数、出力ディレクトリが含まれます。返されるPNGパスは絶対パスです。
たとえば、生成された米国向けドキュメントは、次のサンプル出力のようになります。
PythonからYowesを使用する
アプリケーションはMCPサーバーを起動し、Python MCPクライアントを通じてそのツールを呼び出せます。必要に応じてクライアントの依存関係をインストールしてください。
pip install mcp次の例では、stdioセッションを初期化し、国の一覧を取得して、米国向けドキュメントを生成します。
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
params = StdioServerParameters(command="yowes-mcp", args=[])
async with stdio_client(params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
countries = await session.call_tool(
"list_countries_tool", {}
)
for item in countries.content:
print(item.text)
result = await session.call_tool(
"generate_documents",
{
"country": "us",
"first_name": "John",
"last_name": "Smith",
"school_name": "Valley High",
"position": "Head of Science Department",
"date_of_birth": "12/05/1988",
"gender": "Male"
}
)
print(result.content[0].text)
asyncio.run(main())一覧レスポンスは個別のコンテンツ項目に分割されるため、完全な一覧が1つのレスポンス値に含まれると仮定せず、countries.content のすべての項目を確認してください。
実用的なエージェントワークフロー
list_countries_toolを呼び出して、有効な国コードとドキュメントの種類を確認します。- 選択した国コードを指定して
list_schoolsを呼び出します。 - 返されたデータから学校を選択します。
- 承認済みの教師情報と学校情報を指定して
generate_documentsを呼び出します。 - 返されたPNGパスを読み取り、アプリケーションでファイルを処理します。
この手順により、国コード、学校名、ドキュメント種類の識別子を推測せずに済みます。
高度なヒント
必要な出力だけを選択する
国で利用可能なドキュメントの一部だけが必要な場合は、document_types 配列を渡します。これにより不要なレンダリングを減らし、出力ディレクトリを要求したファイルに絞り込めます。
安定したプロフィール写真を選択する
Yowesはハッシュベースの選択を使用して、同じ人物のプロフィール写真を一貫させます。安定した人物識別情報と明示的な性別を指定すると、適切な同梱写真プールから選択しながら、予測可能な結果を生成できます。
カスタム出力ディレクトリを使用する
output_dir を設定すると、生成された画像をプロジェクト、テスト実行、国ごとに整理できます。相対パスはMCPサーバーの作業ディレクトリを基準に解決されます。
必要に応じてレガシーGUIを実行する
このプロジェクトには、コアの生成ロジックを共有するオプションのCustomTkinterインターフェースも含まれています。
python main_gui.pyWindowsでは、リポジトリに TCL_LIBRARY を設定する run.bat も用意されています。MCPサーバーは主要なヘッドレスインターフェースであり、GUIには依存しません。
新しい国でYowesを拡張する
国を追加するには、countries/<code>/__init__.py を作成し、countries.base.CountryGenerator を継承するクラスを定義します。次の必須メソッドを実装してください。
get_country_nameget_country_codeget_schools_dataget_first_namesget_last_namesget_positionsget_document_typesgenerate_document
countries/__init__.py で register_country("<code>", <Name>Generator) を使ってジェネレーターを登録します。登録すると、MCPの国ツールと学校ツールが自動的に検出できます。GUIにカスタムラベルを表示する場合は、main_gui.py の国一覧処理と国変更処理を更新してください。
まとめ
Yowesは、国ごとのドキュメント生成機能、同梱アセット、MCP stdioサーバーを、移植可能なワークフローに統合します。Pythonでインストールし、MCPを通じて利用可能な国や学校を確認し、選択したPNG出力を生成して、そのプロセスをエージェントやPythonアプリケーションに統合できます。正当な開発とテストのために、国別登録パターンは新しいジェネレーターを追加するための明確な方法も提供します。