Yowes là một ứng dụng Python di động tạo các tài liệu liên quan đến giáo viên dưới dạng tệp PNG độ phân giải cao. Máy chủ Model Context Protocol (MCP) không giao diện của ứng dụng cung cấp chức năng tạo tài liệu qua stdio, cho phép sử dụng từ các môi trường chạy tác tử như Claude Desktop, Hermes và các ứng dụng khách MCP khác.
Dự án hỗ trợ 13 quốc gia, các loại tài liệu riêng theo từng quốc gia, phông chữ và ảnh hồ sơ được đóng gói, cùng dữ liệu trường học chứa địa chỉ và thông tin liên hệ. Hướng dẫn này trình bày cách cài đặt, thiết lập máy chủ, sử dụng công cụ MCP, tích hợp Python và các tùy chọn mở rộng.
Yowes thực hiện những gì
Yowes tạo các tài liệu giáo viên được bản địa hóa từ hồ sơ giáo viên và một trường học được chọn. Tùy theo quốc gia, các đầu ra có thể bao gồm thư xác nhận việc làm, thẻ giáo viên, giấy phép giảng dạy, phiếu lương, thẻ trường học, hợp đồng, chứng chỉ và các định dạng tài liệu khác.
Các tệp được tạo sẽ được lưu dưới dạng ảnh PNG. Ứng dụng tích hợp phông chữ DejaVu Sans và ảnh hồ sơ trong gói, nên không phụ thuộc vào phông chữ hệ thống hoặc tài nguyên ảnh bên ngoài khi chạy.
Các quốc gia được hỗ trợ
Các mã quốc gia và loại tài liệu hiện có bao gồm:
- Vương quốc Anh: thư xác nhận việc làm, thẻ giáo viên và giấy phép giảng dạy.
- Hoa Kỳ: thư xác nhận việc làm, thẻ giáo viên và giấy phép giảng dạy.
- Pháp: giấy xác nhận nhận nhiệm sở, ảnh chụp màn hình iProf, trích lục quy chế và chứng chỉ giảng dạy.
- Hà Lan: hợp đồng lao động, đăng ký giáo viên, giấy xác nhận DUO và thẻ trường học.
- Indonesia: phiếu lương, thư xác nhận kinh nghiệm giảng dạy, thẻ NUPTK và thư bổ nhiệm.
- Úc: thư trường học đã ký, thẻ trường học và giấy phép giảng dạy.
- Canada: thẻ OCT, giấy phép giảng dạy và thư trường học đã ký.
- Tây Ban Nha: thẻ giáo viên, thư trường học đã ký và hợp đồng lao động.
- Argentina: phiếu lương, giấy xác nhận việc làm và thư trường học đã ký.
- Slovakia: phiếu lương, thư xác nhận việc làm và thư trường học đã ký.
- Mexico: thẻ giáo viên, thư trường học đã ký và giấy xác nhận việc làm.
- Philippines: thẻ giáo viên, giấy xác nhận việc làm và giấy phép giảng dạy.
- Thái Lan: phiếu lương và thư xác nhận việc làm.
Chỉ sử dụng các tài liệu này cho mục đích kiểm thử, trình diễn hoặc quy trình hành chính được ủy quyền hợp pháp. Không được trình bày tài liệu đã tạo như giấy tờ chứng nhận chính thức nếu tài liệu đó chưa được cơ quan liên quan cấp và xác thực.
Yêu cầu
Yowes yêu cầu Python 3.10 trở lên. Các phần phụ thuộc chính là Pillow và mcp sẽ được tự động cài đặt khi bạn cài đặt gói.
Dự án hỗ trợ Windows, Linux và macOS. Vì phông chữ và ảnh được đóng gói sẵn, ứng dụng được đóng gói được thiết kế để có tính di động.
Cài đặt Yowes
Cài đặt từ wheel
Nếu bạn có tệp wheel đã xây dựng trong thư mục dist, hãy cài đặt bằng lệnh:
pip install dist/yowes_doc_generator-0.1.0-py3-none-any.whlCài đặt từ mã nguồn
Để phát triển hoặc thử nghiệm cục bộ, hãy cài đặt dự án ở chế độ editable:
pip install -e .Chạy bằng uv
Bạn cũng có thể khởi chạy dự án thông qua uv:
uvx --from . yowes-mcpKiểm tra tài nguyên được đóng gói
Sau khi cài đặt, hãy kiểm tra để đảm bảo các hàm hỗ trợ phông chữ và ảnh hồ sơ được đóng gói có thể được nạp chính xác:
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)"Lần chạy thành công sẽ báo cáo phông chữ DejaVu Sans và trả về True cho ảnh hồ sơ được đóng gói.
Kết nối máy chủ MCP
Yowes giao tiếp qua MCP bằng stdio. Khởi động lệnh đã cài đặt bằng:
yowes-mcpNgoài ra, khi làm việc trực tiếp từ cây mã nguồn, hãy chạy:
python mcp_server.pyTiến trình chờ các yêu cầu MCP trên đầu vào chuẩn và ghi phản hồi vào đầu ra chuẩn. Tiến trình không được thiết kế để hoạt động như một ứng dụng đầu cuối tương tác.
Đăng ký Yowes trong ứng dụng khách MCP
Trỏ môi trường chạy tác tử tương thích với MCP của bạn đến tệp thực thi:
{
"mcpServers": {
"yowes": {
"command": "yowes-mcp",
"args": []
}
}
}Nếu không thể tìm thấy lệnh trong PATH, hãy sử dụng đường dẫn tuyệt đối đến Python và gọi mô-đun máy chủ:
{
"mcpServers": {
"yowes": {
"command": "/path/to/python",
"args": ["-m", "mcp_server"]
}
}
}Khám phá các công cụ MCP hiện có
Máy chủ cung cấp ba công cụ chính:
list_countries_toolliệt kê mã quốc gia, tên hiển thị và các loại tài liệu.list_schools(country)liệt kê các trường học của quốc gia được chọn.generate_documents(...)kết xuất một hoặc nhiều tài liệu và trả về đường dẫn đến các tệp.
Liệt kê các quốc gia
Gọi list_countries_tool không có đối số. Phản hồi chứa một mục kết quả cho mỗi quốc gia, với các giá trị như code, name và document_types. Vì danh sách được chia thành nhiều mục nội dung MCP, hãy lặp qua tập hợp content được trả về để kiểm tra mọi quốc gia.
Liệt kê trường học
Truyền mã quốc gia vào list_schools:
{
"country": "us"
}
Mỗi kết quả trường học có thể bao gồm tên, địa chỉ, thị trấn, mã bưu chính, bang, số điện thoại và thông tin về cơ quan giáo dục địa phương. Khi tạo tài liệu, hãy sử dụng tên trường chính xác hoặc một phần tên trường được công cụ này trả về.
Tạo tài liệu
Công cụ generate_documents yêu cầu quốc gia, tên giáo viên, trường học, chức vụ và ngày sinh. Bạn có thể tùy chọn giới tính, loại tài liệu và thư mục đầu ra.
Yêu cầu mẫu
{
"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"
}Giá trị gender có thể là Random, Male hoặc Female. Giá trị này kiểm soát việc chọn ảnh hồ sơ từ nhóm ảnh đi kèm. Nếu bỏ qua document_types, Yowes sẽ tạo tất cả loại tài liệu có sẵn cho quốc gia đã chọn. Thư mục đầu ra mặc định là output/.
Phản hồi thành công bao gồm quốc gia và trường học đã chọn, các loại tài liệu, đường dẫn tệp được tạo, số lượng và thư mục đầu ra. Các đường dẫn PNG được trả về là đường dẫn tuyệt đối.
Ví dụ, các tài liệu của Hoa Kỳ được tạo có thể tương tự những đầu ra mẫu sau:
Sử dụng Yowes từ Python
Ứng dụng có thể khởi động máy chủ MCP và gọi các công cụ của máy chủ thông qua ứng dụng khách MCP dành cho Python. Cài đặt phần phụ thuộc của ứng dụng khách nếu cần:
pip install mcpVí dụ sau khởi tạo một phiên stdio, liệt kê các quốc gia và tạo tài liệu của Hoa Kỳ:
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())Vì các phản hồi danh sách được chia thành từng mục nội dung riêng lẻ, hãy kiểm tra mọi mục trong countries.content thay vì cho rằng toàn bộ danh sách luôn xuất hiện trong một giá trị phản hồi duy nhất.
Quy trình thực tế dành cho tác nhân
- Gọi
list_countries_toolđể tìm các mã quốc gia và loại tài liệu hợp lệ. - Gọi
list_schoolsvới mã quốc gia đã chọn. - Chọn một trường học từ dữ liệu được trả về.
- Gọi
generate_documentsvới thông tin giáo viên và trường học đã được ủy quyền. - Đọc các đường dẫn PNG được trả về và xử lý các tệp trong ứng dụng của bạn.
Trình tự này giúp tránh việc phỏng đoán mã quốc gia, tên trường học hoặc mã định danh loại tài liệu.
Mẹo nâng cao
Chỉ chọn các đầu ra cần thiết
Truyền một mảng document_types khi bạn chỉ cần một phần các tài liệu có sẵn của một quốc gia. Điều này giảm việc kết xuất không cần thiết và giúp thư mục đầu ra chỉ tập trung vào các tệp được yêu cầu.
Chọn ảnh hồ sơ ổn định
Yowes sử dụng cơ chế chọn dựa trên hàm băm để giữ ảnh hồ sơ nhất quán cho cùng một người. Cung cấp danh tính ổn định của người đó và giới tính cụ thể giúp tạo ra kết quả có thể dự đoán, đồng thời chọn ảnh từ nhóm ảnh đi kèm phù hợp.
Sử dụng thư mục đầu ra tùy chỉnh
Đặt output_dir để sắp xếp hình ảnh được tạo theo dự án, lần chạy kiểm thử hoặc quốc gia. Các đường dẫn tương đối được phân giải từ thư mục làm việc của máy chủ MCP.
Chạy giao diện GUI cũ khi cần
Dự án cũng bao gồm một giao diện CustomTkinter tùy chọn sử dụng chung logic tạo tài liệu cốt lõi:
python main_gui.pyTrên Windows, kho mã cũng cung cấp run.bat, tệp này thiết lập TCL_LIBRARY. Máy chủ MCP vẫn là giao diện không cần giao diện đồ họa chính và không phụ thuộc vào GUI.
Mở rộng Yowes với quốc gia mới
Để thêm một quốc gia, hãy tạo countries/<code>/__init__.py và định nghĩa một lớp kế thừa từ countries.base.CountryGenerator. Triển khai các phương thức bắt buộc:
get_country_nameget_country_codeget_schools_dataget_first_namesget_last_namesget_positionsget_document_typesgenerate_document
Đăng ký trình tạo trong countries/__init__.py bằng register_country("<code>", <Name>Generator). Sau khi đăng ký, các công cụ MCP về quốc gia và trường học có thể tự động phát hiện trình tạo này. Nếu GUI cần hiển thị nhãn tùy chỉnh, hãy cập nhật logic danh sách quốc gia và thay đổi quốc gia trong main_gui.py.
Kết luận
Yowes kết hợp các trình tạo tài liệu theo từng quốc gia, tài sản đi kèm và máy chủ MCP stdio thành một quy trình di động. Cài đặt bằng Python, khám phá các quốc gia và trường học hiện có thông qua MCP, tạo các tệp PNG đã chọn và tích hợp quy trình này vào một tác nhân hoặc ứng dụng Python. Đối với việc phát triển và kiểm thử hợp pháp, cấu trúc đăng ký quốc gia của Yowes cũng cung cấp một hướng rõ ràng để bổ sung các trình tạo mới.