wishlist-mcp

wishlist.fit을 위한 호스팅 MCP 서버입니다. Claude, ChatGPT, Codex가 사용자를 대신해 위시리스트를 읽고 업데이트할 수 있게 합니다.

https://mcp.wishlist.fit/mcp

app.wishlist.fit/connect에서 연결할 수 있으며, 이곳에 클라이언트별 설정 절차가 나와 있습니다. 먼저 wishlist 계정이 필요합니다. 이 서버는 계정을 만들지 않습니다.

개요

wishlist REST API 앞에 있는 순수한 OAuth 2.1 리소스 서버입니다. 데이터베이스도 비즈니스 규칙도 없습니다. 가시성, 속도 제한, 초대 처리는 모두 wishlist API에 있으며, 이 서버는 사용자 자신의 액세스 토큰으로 해당 API를 호출하여 그 규칙을 그대로 물려받습니다.

이렇게 나누는 것은 의도적입니다. 규칙을 복제해 가진 두 번째 서비스를 두는 대안은, 누가 무엇을 볼 수 있는지에 대해 두 표면이 조용히 어긋나기 시작하는 방식이기 때문입니다.

Claude / ChatGPT / Codex
        │  MCP over HTTP, bearer token
        ▼
   this server ──── verifies the token (issuer + audience)
        │
        │  the same token, forwarded
        ▼
   api.wishlist.fit ──── applies visibility, rate limits, invite rules
        │
        ▼
     Postgres

WorkOS AuthKit가 권한 부여 서버입니다. 이 서버는 아무것도 발행하지 않으며 동의 화면도 표시하지 않습니다. AuthKit가 서명한 것을 검증할 뿐입니다.

도구

14개이며, 웹 앱에서 이미 직접 할 수 있는 일마다 하나씩 대응합니다. 동등성이 원칙입니다. 에이전트 전용 권한도 없고, 앱 자체도 할 수 없는 일은 없습니다.

wishlist_get_gift_guide는 어떤 사람의 프로필과 위시리스트를 함께 반환합니다. 이것이 누군가 이 서버를 연결하는 이유이며, 이 도구가 없으면 선물을 주는 여정은 세 번의 왕복이 필요합니다.

두 파괴적 도구는 destructiveHint: true를 지니고 있어서, 되돌릴 수 없는 작업을 확인하는 클라이언트는 먼저 물어봅니다. 초대를 보내면 실제 사람에게 이메일이 전달되며, 보낸 것은 되돌릴 수 없습니다. 초대를 수락하는 일은 상호적입니다. 초대자가 내 서클 전용 필드에 접근하게 되고, 나도 초대자의 서클 전용 필드에 접근하게 됩니다.

하나의 연결, 모든 것

스코프는 없습니다. WorkOS는 사용자 지정 스코프를 표현할 수 없으므로, 연결 하나가 전체 도구 표면을 담당합니다. 쓰기 보호는 구조적이라기보다 행동적입니다. 위의 구분 표시, 도구 설명, 그리고 API가 적용하는 속도 제한이 그 수단입니다.

로컬에서 실행하기

uv sync
cp .env.example .env      # point it at a local API and the Local WorkOS environment
uv run python -m wishlist_mcp.main

uv run pytest
uv run ruff format --check . && uv run ruff check .

테스트는 respx로 wishlist API를 스텁합니다. 테스트가 확인하는 것은 이 서버가 직접 하는 일입니다. 토큰 검증, 요청 구성, 그리고 API 오류를 모델이 실제로 행동할 수 있는 문장으로 바꾸는 것. 규칙 그 자체는 API의 몫이며, 그쪽에서 테스트됩니다.

설정

모든 변수는 WISHLIST_MCP_ 접두어를 사용합니다. .env.example을 참조하세요.

RESOURCE_URI는 WorkOS에 구성된 리소스 표시자와 /mcp 경로를 포함해 글자 하나까지 일치해야 합니다. 일치하지 않으면 클라이언트가 연결을 거부하는 가장 흔한 원인이 됩니다.

이 코드를 변경하기 전에 알아 두면 좋은 것들

이 항목들은 각자 실제로 프로덕션까지 도달했던 버그입니다.

• get_http_headers()는 authorization을 제거합니다. 명시적으로 요청하세요. 그렇게 하지 않으면 initialize와 tools/list는 성공하는데, 모든 도구 호출은 "no access token"을 보고합니다. 두 작업은 도구 본문이 실행되기 전에 응답되기 때문입니다. 녹색 핸드셰이크는 도구가 잘 동작한다는 증거가 되지 못합니다.

• MCP 앱은 루트에 마운트되며 자체 경로를 가집니다. /mcp로 마운트하면 Starlette가 /mcp를 /mcp/로 리디렉트시키고, 모든 클라이언트가 받는 주소에는 마지막 슬래시가 없습니다.

• X-Forwarded-Proto를 신뢰합니다. Cloud Run이 TLS를 종료하므로, 이 헤더가 없으면 생성되는 모든 URL이 http://로 표시됩니다. 위의 리디렉트와 겹쳐서, 한 차례 클라이언트가 bearer 토큰을 평문으로 보낼 뻔했습니다.

• FastMCP의 lifespan은 앱의 lifespan에 연결됩니다. ASGI 앱을 마운트한다고 그 lifespan이 시작되지는 않으며, lifespan이 없으면 단위 테스트는 통과해도 모든 도구 호출이 "Task group is not initialized" 오류로 실패합니다.

• TestClient는 기본적으로 리디렉트를 따라갑니다. 확인하려는 것이 특정 경로가 직접 응답하는지라면 follow_redirects=False를 전달하세요.

배포

Cloud Run, asia-southeast1, wishlist의 나머지와 동일한 프로젝트에서 운영합니다. main은 푸시 시 배포됩니다. 인프라는 wishlist-infrastructure에 있습니다.

라이선스

MIT. LICENSE를 참조하세요.