wishlist-mcp

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

https://mcp.wishlist.fit/mcp

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

Что это

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

Инструменты

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

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 .

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

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

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

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

Что важно знать, прежде чем менять это

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

• get_http_headers() отбрасывает заголовок authorization. Запрашивайте его явно. Без него каждый вызов инструмента сообщает «no access token», хотя 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, когда смысл в том, что путь отвечает напрямую.

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

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

Лицензия

MIT. См. LICENSE.