使用 Yowes 和 MCP 构建多国教师文档生成器

Yowes 是一个便携式 Python 应用程序，可将教师相关文档生成为高分辨率 PNG 文件。其无头 模型上下文协议（MCP）服务器通过标准输入输出公开文档生成功能，因此可从 Claude Desktop、Hermes 及其他 MCP 客户端等代理运行时中使用。

该项目支持 13 个国家、各国特定的文档类型、捆绑的字体和个人照片，以及包含地址和联系方式的学校数据。本教程将介绍安装、服务器设置、MCP 工具使用、Python 集成和扩展选项。

Yowes 的功能

Yowes 根据教师资料和所选学校创建本地化教师文档。根据所在国家/地区的不同，可生成的文档包括任职证明信、教师证件、教师执照、工资单、学校证件、合同、证书以及其他文档格式。

生成的文件会保存为 PNG 图像。应用程序在软件包中包含 DejaVu Sans 字体和个人照片，因此运行时不依赖系统字体或外部图像资源。

支持的国家/地区

可用的国家/地区代码和文档类型包括：

• 英国：任职证明信、教师证件和教师执照。
• 美国：任职证明信、教师证件和教师执照。
• 法国：任职声明、iProf 截图、章程摘录和教学证书。
• 荷兰：劳动合同、教师注册证明、DUO 声明和学校证件。
• 印度尼西亚：工资单、教学经历证明信、NUPTK 卡和任命信。
• 澳大利亚：已签署的学校信函、学校证件和教师执照。
• 加拿大：OCT 卡、教师执照和已签署的学校信函。
• 西班牙：教师证件、已签署的学校信函和劳动合同。
• 阿根廷：工资单、任职证明和已签署的学校信函。
• 斯洛伐克：工资单、任职证明信和已签署的学校信函。
• 墨西哥：教师证件、已签署的学校信函和任职证明。
• 菲律宾：教师证件、任职证明和教师执照。
• 泰国：工资单和任职证明信。

仅将这些文档用于合法测试、演示或经授权的行政流程。除非相关机构已签发并验证生成的文档，否则不得将其作为官方凭证出示。

要求

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 通过标准输入输出使用 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 工具

服务器提供三个主要工具：

• list_countries_tool 列出国家/地区代码、显示名称和文档类型。
• list_schools(country) 列出所选国家/地区的学校。
• generate_documents(...) 生成一个或多个文档，并返回其文件路径。

列出国家/地区

不带参数调用 list_countries_tool。响应中每个国家/地区对应一个结果项，其中包含 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())

由于列表响应会拆分为单独的内容项，请检查 countries.content 中的每一项，而不要假设完整列表会出现在单个响应值中。

实用的代理工作流

1. 调用 list_countries_tool，发现有效的国家代码和文档类型。
2. 使用所选国家代码调用 list_schools。
3. 从返回的数据中选择一所学校。
4. 使用经授权的教师和学校信息调用 generate_documents。
5. 读取返回的 PNG 路径，并在应用程序中处理这些文件。

此流程可以避免猜测国家代码、学校名称或文档类型标识符。

高级提示

仅选择所需的输出

当你只需要某个国家支持的部分文档时，传入 document_types 数组。这样可以减少不必要的渲染，并让输出目录只包含请求的文件。

选择稳定的头像

Yowes 使用基于哈希的选择方式，让同一个人的头像保持一致。提供稳定的人员身份信息和明确的性别，有助于从合适的内置头像池中选择并生成可预测的结果。

使用自定义输出目录

将 output_dir 设置为按项目、测试运行或国家整理生成的图像。相对路径会根据 MCP 服务器的工作目录解析。

必要时运行旧版 GUI

项目还包含一个可选的 CustomTkinter 界面，该界面与核心生成逻辑共用：

python main_gui.py

在 Windows 上，仓库还提供了会设置 TCL_LIBRARY 的 run.bat。MCP 服务器仍是主要的无头接口，不依赖 GUI。

为 Yowes 添加新国家

要添加国家，请创建 countries/<code>/__init__.py，并定义一个继承自 countries.base.CountryGenerator 的类。实现以下必需方法：

• get_country_name
• get_country_code
• get_schools_data
• get_first_names
• get_last_names
• get_positions
• get_document_types
• generate_document

使用 register_country("<code>", <Name>Generator) 在 countries/__init__.py 中注册生成器。注册后，MCP 国家和学校工具即可自动发现它。如果 GUI 需要显示自定义标签，请在 main_gui.py 中更新其国家列表和国家切换逻辑。

结语

Yowes 将特定国家/地区的文档生成器、打包资源和 MCP stdio 服务器整合为可移植的工作流。使用 Python 安装后，可通过 MCP 查询可用的国家/地区和学校，生成选定的 PNG 输出，并将整个流程集成到代理或 Python 应用程序中。对于合法的开发和测试，其国家/地区注册模式也为添加新的生成器提供了清晰的路径。