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 도구 살펴보기
서버는 다음 세 가지 주요 도구를 제공합니다.
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의 모든 항목을 확인하세요.
실용적인 에이전트 워크플로
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 애플리케이션에 통합할 수 있습니다. 합법적인 개발 및 테스트를 위해 국가 등록 패턴은 새로운 생성기를 추가할 수 있는 명확한 방법도 제공합니다.