wishlist-mcp

Размещённый MCP-сервер для wishlist.fit. Он позволяет Claude, ChatGPT или Codex читать и обновлять ваш список желаний от вашего имени.

https://mcp.wishlist.fit/mcp

Подключите его через app.wishlist.fit/connect, где есть пошаговые инструкции для каждого клиента. Сначала нужна учётная запись wishlist; этот сервер никогда не создаёт её.

В docs/connecting.md — более подробная версия: точные команды для каждого клиента, что реально проверено на продакшене, и два флага Codex, которые стоят вам полдня, если перепутать.

Что это такое

Чистый ресурсный сервер OAuth 2.1 перед REST API wishlist. Он не хранит базу данных и не содержит бизнес-правил. Видимость, лимиты запросов и обработка приглашений — всё это живёт в API wishlist, и этот сервер наследует их, вызывая этот 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.

Related MCP server: Personal Toolkit MCP Server

Инструменты

Четырнадцать, по одному на каждое действие, которое вы уже можете выполнить вручную в веб-приложении. Паритет — правило: никаких привилегий только для агентов, и ничего, что приложение само не может сделать.

wishlist_get_gift_guide возвращает профиль человека и его список желаний вместе. Это причина, по которой кто-либо подключает этот сервер, и без него путь дарителя подарка обходится в три лишних запроса.

Два разрушающих инструмента несут destructiveHint: true, поэтому клиенты, которые подтверждают необратимые действия, сначала спросят. Отправка приглашения пишет реальному человеку, и его нельзя отозвать. Принятие приглашения взаимно: пригласивший получает доступ к вашим полям, видимым только для круга, так же как вы получаете доступ к его.

Одно подключение — всё

Никаких областей действия (scopes). 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 .

Тесты подменяют API wishlist с помощью respx. Проверяется собственная работа этого сервера: проверка токенов, формирование запросов и превращение ошибок API в предложения, на которые модель может реагировать. Сами правила принадлежат API и тестируются там.

Конфигурация

Каждая переменная имеет префикс WISHLIST_MCP_. См. .env.example.

RESOURCE_URI должен совпадать с индикатором ресурса, настроенным в WorkOS, символ в символ, включая путь /mcp. Несовпадение — самая частая причина, по которой клиент отказывается подключаться.

Что стоит знать перед изменением

Каждый из этих пунктов — баг, который однажды дошёл до продакшена.

• get_http_headers() удаляет authorization. Запрашивайте его явно. Без этого каждый вызов инструмента сообщает «нет токена доступа», в то время как initialize и tools/list всё ещё успешны, потому что они обрабатываются до выполнения тела любого инструмента. Зелёное рукопожатие — не доказательство, что инструменты работают.

• MCP-приложение смонтировано в корне и владеет своим путём. Монтирование его на /mcp заставляет Starlette перенаправлять /mcp на /mcp/, а адрес, который получает каждый клиент, не имеет завершающего слэша.

• X-Forwarded-Proto доверяется. Cloud Run завершает TLS, поэтому без него каждый сгенерированный URL заявляет http://. В сочетании с перенаправлением выше это однажды означало, что клиент мог бы отправить свой bearer-токен открытым текстом.

• Жизненный цикл FastMCP встроен в жизненный цикл приложения. Монтирование ASGI-приложения не запускает его жизненный цикл, и без него каждый вызов инструмента падает с «Task group is not initialized», в то время как модульные тесты всё ещё проходят.

• TestClient по умолчанию следует перенаправлениям. Передайте follow_redirects=False, когда суть в том, что путь отвечает напрямую.

• FastMCP сопоставляет Accept по подстроке. Он отвечает 406 Client must accept application/json клиенту, отправляющему */*, который уже это делает, и тому, кто не отправляет заголовок вообще, что по RFC 9110 тоже допустимо. WildcardAccept явно описывает эти случаи до того, как их увидит FastMCP. Обычный curl отправляет */*, так что это первое, с чем сталкивается каждый.

Развёртывание

Cloud Run, asia-southeast1, в том же проекте, что и остальной wishlist. main разворачивается при пуше. Инфраструктура живёт в wishlist-infrastructure.

Лицензия

MIT. См. LICENSE.