MCP Waifu Queue

MCP 와이푸 큐(제미니 에디션)

이 프로젝트는 대화형 AI "와이푸" 캐릭터를 위한 MCP(모델 컨텍스트 프로토콜) 서버를 구현하며, 비동기 처리를 위해 Redis 큐를 통해 Google Gemini API를 활용합니다. FastMCP 라이브러리를 활용하여 서버 설정 및 관리를 간소화합니다.

목차

• 특징
• 건축학
• 필수 조건
• 설치
• 구성
• 서비스 실행
• MCP API
• 테스트
• 문제 해결
• 기여하다
• 특허

특징

• Google Gemini API( gemini-2.5-pro-preview-03-25 )를 사용한 텍스트 생성.
• Redis를 사용하여 동시 요청을 비동기적으로 처리하기 위한 요청 큐잉.
• FastMCP 사용한 MCP 호환 API.
• MCP 리소스를 통한 작업 상태 추적.
• 환경 변수( .env 파일)를 통한 구성 및 ~/.api-gemini 에서 API 키 로딩.

건축학

이 프로젝트는 몇 가지 핵심 구성 요소로 구성되어 있습니다.

• main.py : FastMCP 애플리케이션을 초기화하고 MCP 도구/리소스를 정의하는 주요 진입점입니다.
• respond.py : Gemini API와 상호 작용하기 위해 google-generativeai 라이브러리를 사용하는 핵심 텍스트 생성 로직을 담고 있습니다.
• task_queue.py : Redis 큐와의 상호작용을 처리하고( python-rq 사용), 생성 요청을 큐에 넣습니다.
• utils.py : 유틸리티 함수, 특히 respond.py 에서 Gemini 논리를 호출하기 위해 작업자가 실행하는 call_predict_response 포함되어 있습니다.
• worker.py : 큐에서 작업을 처리하고 call_predict_response 호출하는 Redis 워커( python-rq )입니다.
• config.py : pydantic-settings 사용하여 구성을 관리합니다.
• models.py : MCP 요청 및 응답 검증을 위한 Pydantic 모델을 정의합니다.

요청의 흐름은 다음과 같습니다.

1. 클라이언트는 generate_text MCP 도구( main.py 에 정의됨)에 요청을 보냅니다.
2. 이 도구는 요청(프롬프트)을 Redis 대기열( task_queue.py 에서 처리)에 넣습니다.
3. worker.py 프로세스는 큐에서 작업을 가져옵니다.
4. 워커는 call_predict_response 함수( utils.py 에서)를 실행합니다.
5. call_predict_response Gemini API와 상호 작용하는 predict_response 함수( respond.py 에 있음)를 호출합니다.
6. 생성된 텍스트(또는 오류 메시지)는 predict_response 에 의해 반환되고 RQ에 의해 작업 결과로 저장됩니다.
7. 클라이언트는 job://{job_id} MCP 리소스( main.py 에 정의됨)를 사용하여 작업 상태와 결과를 검색할 수 있습니다.

지엑스피1

필수 조건

• 파이썬 3.7 이상
• pip 또는 uv (Python 패키지 설치 프로그램)
• Redis 서버(설치 및 실행 중)
• Google Gemini API 키

시스템에 Redis를 설치하는 방법에 대한 지침은 공식 Redis 웹사이트( https://redis.io/docs/getting-started/) 에서 확인할 수 있습니다. Google AI Studio (https://aistudio.google.com/app/apikey) 에서 Gemini API 키를 얻을 수 있습니다.

설치

1. 저장소를 복제합니다.
   git clone <YOUR_REPOSITORY_URL> cd mcp-waifu-queue
2. 가상 환경을 만들고 활성화합니다( venv 또는 uv 사용):venv (표준 라이브러리) 사용:
   python -m venv .venv source .venv/bin/activate # On Linux/macOS # .venv\Scripts\activate # On Windows CMD # source .venv/Scripts/activate # On Windows Git Bash/PowerShell Core
   uv 사용(설치된 경우):
   # Ensure uv is installed (e.g., pip install uv) python -m uv venv .venv source .venv/bin/activate # Or equivalent activation for your shell
3. 종속성을 설치합니다(venv 또는 uv 내에서 pip 사용):pip 사용하기:
   pip install -e .[test] # Installs package in editable mode with test extras
   uv 사용 :
   # Ensure uv is installed inside the venv if desired, or use the venv's python # .venv/Scripts/python.exe -m pip install uv # Example for Windows .venv/Scripts/python.exe -m uv pip install -e .[test] # Example for Windows # python -m uv pip install -e .[test] # If uv is in PATH after venv activation

구성

1. API 키: 홈 디렉터리( ~/.api-gemini )에 .api-gemini 라는 이름의 파일을 만들고 그 안에 Google Gemini API 키를 넣으세요. 파일에 공백이 없어야 합니다.
   echo "YOUR_API_KEY_HERE" > ~/.api-gemini
   ( YOUR_API_KEY_HERE 실제 키로 바꾸세요)
2. 기타 설정: .env.example 파일을 .env 로 복사합니다.
   cp .env.example .env
3. 나머지 구성 값을 설정하려면 .env 파일을 수정하세요.
   • MAX_NEW_TOKENS : Gemini 응답에 대한 최대 토큰 수(기본값: 2048 ).
   • REDIS_URL : Redis 서버의 URL(기본값: redis://localhost:6379 ).
   • FLASK_ENV , FLASK_APP : 선택 사항이며, 다른 곳에서 사용되는 경우 Flask와 관련이 있으며 MCP 서버/작업자 작업의 핵심이 아닙니다.

서비스 실행

1. Redis가 실행 중인지 확인하세요. 로컬에 설치한 경우 Redis 서버 프로세스를 시작해야 할 수 있습니다(예: redis-server 명령 또는 서비스 관리자 사용).
2. RQ Worker를 시작합니다. 터미널을 열고 가상 환경을 활성화합니다( source .venv/bin/activate 또는 이와 유사한 명령어). 그리고 다음을 실행합니다.
   python -m mcp_waifu_queue.worker
   이 명령은 .env 파일에 정의된 Redis 대기열의 작업을 수신 대기하는 작업자 프로세스를 시작합니다. 이 터미널을 계속 실행하세요.
3. MCP 서버 시작: 다른 터미널을 열고 가상 환경을 활성화한 다음 uvicorn 과 같은 도구를 사용하여 MCP 서버를 실행합니다(설치가 필요할 수 있음: pip install uvicorn 또는 uv pip install uvicorn ):
   uvicorn mcp_waifu_queue.main:app --reload --port 8000 # Example port
   8000 원하는 포트로 바꾸세요. --reload 플래그는 개발 시 유용합니다.또는, Redis(실행 중이 아닌 경우)와 백그라운드의 작업자를 시작하려고 시도하는 start-services.sh 스크립트(주로 Linux/macOS 환경용으로 설계됨)를 사용할 수 있습니다.
   # Ensure the script is executable: chmod +x ./scripts/start-services.sh ./scripts/start-services.sh # Then start the MCP server manually as shown above.

MCP API

서버는 다음과 같은 MCP 호환 엔드포인트를 제공합니다.

도구

• generate_text
  • 설명: 백그라운드 큐를 통해 Gemini API에 텍스트 생성 요청을 보냅니다.
  • 입력: {"prompt": "Your text prompt here"} (유형: GenerateTextRequest )
  • 출력: {"job_id": "rq:job:..."} (대기 중인 작업에 대한 고유 ID)

자원

• job://{job_id}
  • 설명: 이전에 제출한 작업의 상태와 결과를 검색합니다.
  • URI 매개변수: job_id ( generate_text 도구에서 반환된 ID).
  • 출력: {"status": "...", "result": "..."} (유형: JobStatusResponse )
    • status : 작업의 현재 상태(예: "대기 중", "시작됨", "완료됨", "실패"). RQ는 내부적으로 약간 다른 용어를 사용합니다("시작됨" 대 "처리 중", "완료됨" 대 "완료됨"). 리소스는 이러한 용어를 매핑합니다.
    • result : 작업 상태가 "완료"이면 Gemini에서 생성된 텍스트이고, 그렇지 않으면 null . 작업이 실패하면 RQ 처리 방식에 따라 result는 null 이거나 오류 정보를 포함할 수 있습니다.

테스트

프로젝트에 테스트가 포함되어 있습니다. 테스트 종속성을 설치했는지 확인하세요( pip install -e .[test] 또는 uv pip install -e .[test] ).

pytest 사용하여 테스트를 실행합니다.

참고: 테스트에는 Redis( fakeredis )를 모의해야 할 수도 있고, 구현에 따라 Gemini API 호출을 모의해야 할 수도 있습니다.

문제 해결

• 오류: Gemini API key not found in .../.api-gemini or GEMINI_API_KEY environment variable . 홈 디렉터리에 ~/.api-gemini 파일을 생성하고 유효한 Gemini API 키를 그 안에 넣었는지 확인하세요. 또는 GEMINI_API_KEY 환경 변수가 대체 변수로 설정되어 있는지 확인하세요.
• Gemini API 호출 중 오류 발생(예: AuthenticationError, PermissionDenied) : ~/.api-gemini (또는 대체 환경 변수)의 API 키가 올바르고 유효한지 다시 한번 확인하세요. 해당되는 경우 Google Cloud 프로젝트에 API가 활성화되어 있는지 확인하세요.
• 작업이 "대기 중"에 갇힘 : RQ 워커( python -m mcp_waifu_queue.worker )가 별도의 터미널에서 실행 중이고 .env 에 지정된 동일한 Redis 인스턴스에 연결되어 있는지 확인하세요. 워커 로그에서 오류를 확인하세요.
• ConnectionRefusedError(Redis) : Redis 서버가 실행 중이고 .env 에 지정된 REDIS_URL 에서 액세스할 수 있는지 확인하세요.
• MCP 서버 연결 문제 : MCP 서버( uvicorn ... )가 실행 중이고 올바른 호스트/포트에 연결하고 있는지 확인하세요.

기여하다

1. 저장소를 포크합니다.
2. 기능이나 버그 수정을 위해 새로운 브랜치를 만듭니다( git checkout -b feature/your-feature-name ).
3. 변경 사항을 적용하고 커밋합니다( git commit -am 'Add some feature' ).
4. 포크한 저장소에 브랜치를 푸시합니다( git push origin feature/your-feature-name ).
5. 원래 저장소에 새로운 풀 리퀘스트를 만듭니다.

프로젝트의 코딩 표준과 린팅 규칙( ruff )을 준수하세요.

특허

이 프로젝트는 MIT-0 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.