MCP Waifu 큐

이 프로젝트는 비동기 처리를 위해 Redis 큐를 거쳐 OpenRouter API를 활용하는 대화형 AI "와이푸" 캐릭터용 MCP(Model Context Protocol) 서버를 구현합니다. 간소화된 서버 설정 및 관리를 위해 FastMCP 라이브러리를 사용합니다.

목차

• 기능

• 아키텍처

• 사전 요구 사항

• 설치

• 구성

• 서비스 실행

• MCP API

• 테스트

• 문제 해결

• 기여

• 라이선스

Related MCP server: local-agent-context

기능

• ~/.model-openrouter 또는 openrouter/free의 모델을 사용하여 OpenRouter를 통한 텍스트 생성.

• 동시 요청을 비동기적으로 처리하기 위한 Redis 기반 요청 큐잉.

• FastMCP를 사용한 MCP 호환 API.

• MCP 리소스를 통한 작업 상태 추적.

• 환경 변수(.env 파일)를 통한 구성.

• API 키 로드:

  • OpenRouter: OPENROUTER_API_KEY 또는 ~/.api-openrouter

• 홈 디렉토리의 모델 선택 파일:

  • OpenRouter 모델 이름을 위한 ~/.model-openrouter

아키텍처

이 프로젝트는 다음과 같은 주요 구성 요소로 이루어져 있습니다:

• main.py: FastMCP 애플리케이션을 초기화하고 MCP 도구/리소스를 정의하는 메인 진입점.

• respond.py: OpenRouter API를 사용하는 핵심 텍스트 생성 로직 포함.

• task_queue.py: Redis 큐(python-rq 사용)와의 상호작용을 처리하고 생성 요청을 큐에 추가.

• utils.py: 워커가 respond.py의 생성 로직을 호출하기 위해 실행하는 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는 OpenRouter API와 상호작용하는 predict_response 함수(respond.py 내)를 호출합니다.

6. 생성된 텍스트(또는 오류 메시지)가 predict_response에 의해 반환되고 RQ에 의해 작업 결과로 저장됩니다.

7. 클라이언트는 job://{job_id} MCP 리소스(main.py에 정의됨)를 사용하여 작업 상태와 결과를 검색할 수 있습니다.

graph LR
    subgraph Client
        A[User/Client] -->|1. Send Prompt via MCP Tool| B(mcp-waifu-queue: main.py)
    end
    subgraph mcp-waifu-queue Server
        B -->|2. Enqueue Job (prompt)| C[Redis Queue]
        B -->|7. Return Job ID| A
        D[RQ Worker (worker.py)] --|>| C
        D -->|3. Dequeue Job & Execute| E(utils.call_predict_response)
        E -->|4. Call Generation Logic| F(respond.predict_response)
        F -->|5. Call OpenRouter API| G[OpenRouter API]
        G -->|6. Return Response| F
        F --> E
        E -->|Update Job Result in Redis| C
        A -->|8. Check Status via MCP Resource| B
        B -->|9. Fetch Job Status/Result| C
        B -->|10. Return Status/Result| A
    end

사전 요구 사항

• Python 3.7+

• pip 또는 uv (Python 패키지 설치 프로그램)

• Redis 서버 (설치 및 실행 중)

• OpenRouter API 키

시스템에 Redis를 설치하는 방법은 공식 Redis 웹사이트에서 확인할 수 있습니다: https://redis.io/docs/getting-started/ OpenRouter API 키는 다음에서 얻을 수 있습니다: https://openrouter.ai/

설치

1. 저장소 복제:

   git clone <YOUR_REPOSITORY_URL>
   cd mcp-waifu-queue

2. uv를 사용하여 가상 환경 생성 및 활성화:

   python -m uv venv .venv
   .venv/Scripts/python.exe -m ensurepip
   .venv/Scripts/python.exe -m pip install uv

3. 의존성 설치:

   .venv/Scripts/python.exe -m uv pip install -r requirements.txt
   .venv/Scripts/python.exe -m uv pip install -r requirements-dev.txt

구성

1. $HOME 내 파일을 통한 모델 이름:

   • OpenRouter 모델 파일:

     echo "openrouter/free" > ~/.model-openrouter

2. API 키: 환경 변수를 권장하며 파일 방식을 대체제로 사용:

   • OpenRouter: OPENROUTER_API_KEY 또는 ~/.api-openrouter GXP6

   (YOUR_API_KEY_HERE를 실제 키로 교체하세요)

3. 기타 설정: .env.example 파일을 .env로 복사:

   cp .env.example .env

4. .env 파일을 수정하여 나머지 구성 값을 설정:

   • MAX_NEW_TOKENS: 응답을 위한 최대 토큰 수 (기본값: 2048).

   • REDIS_URL: Redis 서버의 URL (기본값: redis://localhost:6379).

   • FLASK_ENV, FLASK_APP: 선택 사항, 다른 곳에서 사용되는 경우 Flask와 관련이 있으며 MCP 서버/워커 작업의 핵심은 아님.

서비스 실행

1. Redis가 실행 중인지 확인하십시오. 로컬에 설치한 경우 Redis 서버 프로세스를 시작해야 할 수 있습니다(예: redis-server 명령 또는 서비스 관리자를 통해).

2. RQ 워커 시작: 터미널을 열고 가상 환경을 활성화(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 플래그는 개발 시 유용합니다.

   또는 start-services.sh 스크립트(주로 Linux/macOS 환경용으로 설계됨)를 사용할 수 있습니다. 이 스크립트는 Redis(실행 중이 아닌 경우)와 워커를 백그라운드에서 시작하려고 시도합니다:

   # 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

  • 설명: 백그라운드 큐를 통해 OpenRouter API로 텍스트 생성 요청을 보냅니다.

  • 입력: {"prompt": "여기에 텍스트 프롬프트 입력"} (유형: GenerateTextRequest)

  • 출력: {"job_id": "rq:job:..."} (큐에 추가된 작업의 고유 ID)

리소스

• job://{job_id}

  • 설명: 이전에 제출된 작업의 상태와 결과를 검색합니다.

  • URI 매개변수: job_id (generate_text 도구가 반환한 ID).

  • 출력: {"status": "...", "result": "..."} (유형: JobStatusResponse)

    • status: 작업의 현재 상태 (예: "queued", "started", "finished", "failed"). RQ는 내부적으로 약간 다른 용어를 사용합니다("started" 대 "processing", "finished" 대 "completed"). 리소스는 이를 매핑합니다.

    • result: 작업 상태가 "completed"인 경우 생성된 텍스트, 그렇지 않으면 null. 작업이 실패한 경우 RQ의 처리에 따라 결과가 null이거나 오류 정보가 포함될 수 있습니다.

테스트

이 프로젝트에는 테스트가 포함되어 있습니다. 테스트 의존성이 설치되어 있는지 확인하십시오(pip install -e .[test] 또는 uv pip install -e .[test]).

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

pytest tests

참고: 테스트는 Redis 모킹(fakeredis)과 구현 방식에 따라 OpenRouter API 호출 모킹이 필요할 수 있습니다.

문제 해결

• 오류: OpenRouter API key not available: OPENROUTER_API_KEY가 설정되어 있는지, 또는 ~/.api-openrouter 파일에 키가 한 줄로(공백 없이) 작성되어 있는지 확인하십시오.

• 작업이 "queued" 상태에서 멈춤: 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 파일을 참조하십시오.