MCP Stark Brain (Payments)

Локальный MCP-сервер, который помогает команде Payments в повседневной работе:

• Запрашивать архитектурный паттерн, используемый Python-микросервисами.

• Искать спецификации микросервисов (назначение и ответственность каждого сервиса).

• Разбираться в процессах обработки платежей.

• Проводить триаж и расследование тикетов Customer Success (CS), сочетая поиск по документации с анализом GCP (Datastore + Cloud Logging / Log Explorer).

• Вызывать Stark Bank APIs в среде development (по умолчанию) или sandbox (только по явному запросу), используя ваши учётные данные ECDSA Project.

Он выполняет RAG по документации в starkbank/alexandria, подписывает запросы к Stark Bank API вашим приватным ключом и выполняет GCP-запросы с использованием вашей собственной учётной записи gcloud (ADC).

1. Как это работает

IDE / LLM  --stdio-->  MCP server
                         |-- Docs (RAG): fetch alexandria via GitHub PAT -> local vector index
                         |-- Stark Bank API: ECDSA-signed HTTP to development (default) / sandbox
                         |-- GCP: Datastore + Cloud Logging via your gcloud ADC (project per call)

• Документация хранится удалённо (без сохранения git-клона). Сервер скачивает tar-архив репозитория через GitHub API (один запрос на всё содержимое) для построения локального индекса эмбеддингов. Локально кэшируется только векторный индекс.

• Учитывает ограничения скорости (rate limit). Когда бюджет GitHub на исходе, сервер предлагает клонировать репозиторий и переключиться в режим local (см. раздел 10).

• Stark Bank API по умолчанию использует среду development (https://development.api.starkbank.com). Sandbox используется только тогда, когда инструмент вызывается с environment="sandbox" после явного запроса пользователя. Production не разрешён никогда.

• Проект GCP передаётся при каждом вызове. Здесь нет фиксированной переменной окружения для проекта: каждый запрос принимает явный project, поэтому вы можете переключаться между проектами микросервисов в одной сессии, не трогая глобальный gcloud config.

• Никаких ключей сервисных аккаунтов для GCP. Доступ к GCP осуществляется через ваши личные учётные данные ADC, что сохраняет разрешения и аудит-журналы каждого пользователя.

2. Предварительные требования

• Python 3.12 (требуется для сборки/установки пакета). chromadb и fastembed (через onnxruntime) пока ненадёжно поставляют готовые wheel-файлы для новых интерпретаторов, поэтому проект закрепляет requires-python = ">=3.11,<3.13", и все команды ниже явно нацелены на 3.12 — не подменяйте системный python3 по умолчанию, не проверив сначала его версию.

• uv (рекомендуется) или pipx для установки пакета.

• Google Cloud SDK (gcloud).

Проверьте/установите закреплённую версию Python с помощью uv (это не затрагивает системный Python):

uv python install 3.12

3. Создание вашего GitHub PAT

Каждый разработчик генерирует собственный PAT (он никогда не передаётся и не коммитится). alexandria является приватным и принадлежит организации starkbank, поэтому выбор рабочего типа токена зависит от политики токенов организации — прочитайте оба варианта ниже, прежде чем выбрать один.

Вариант A: fine-grained PAT (попробуйте сначала)

1. GitHub -> Settings -> Developer settings -> Fine-grained tokens -> Generate new token.

2. Владелец ресурса: starkbank.

3. Доступ к репозиториям: Only select repositories -> starkbank/alexandria.

4. Разрешения: Repository permissions -> Contents: Read-only.

5. Сгенерируйте и скопируйте токен (вы зададите его как переменную окружения в вашем mcp.json).

6. Проверьте его статус на https://github.com/settings/personal-access-tokens. Если организация требует одобрения, статус будет Pending, и все запросы будут давать 404 до одобрения. Попросите владельца организации starkbank одобрить его в разделе Settings -> Personal access tokens -> Pending requests, либо переходите к варианту B.

Вариант B: classic PAT (запасной вариант, если организация не одобряет fine-grained tokens)

Classic PAT не подлежат описанному выше шагу одобрения организацией, поэтому это более быстрый путь, если ваша организация ограничивает fine-grained tokens:

1. GitHub -> Settings -> Developer settings -> Tokens (classic) -> Generate new token.

2. Область действия: repo (у classic-токенов нет области только для содержимого для приватных репозиториев).

3. Если организация starkbank требует SSO, нажмите Configure SSO рядом с новым токеном и Authorize его для starkbank — неавторизованный токен будет давать 404 на ресурсах starkbank точно так же, как и неодобренный fine-grained токен.

В любом случае, после установки запустите инструмент diagnose_github_access (см. раздел 8), чтобы убедиться, что токен действительно работает, прежде чем полагаться на него.

4. Аутентификация с GCP (ADC)

gcloud auth login
gcloud auth application-default login

Вам не нужно указывать проект здесь — MCP получает project при каждом вызове GCP-инструмента. Используйте analyze_ticket / resolve_project, чтобы получить рекомендации по проектам.

5. Учётные данные Stark Bank API (ECDSA)

API-вызовы аутентифицируются с помощью ECDSA (secp256k1), а не статических API-ключей. См. официальную документацию: Authentication.

1. Сгенерируйте ключевую пару (если ещё не сделали этого) и зарегистрируйте только публичный ключ в Web Banking (Integrations → Project) для среды development.

2. Храните приватный ключ PEM на своей машине — никогда не коммитьте его и не помещайте публичный ключ в этот репозиторий (MCP не нужен публичный ключ для подписи запросов).

3. Запомните Project ID, показанный в Web Banking после создания/регистрации проекта.

4. Укажите MCP пути к PEM и Project ID через переменные окружения (см. шаг 6 / раздел 11).

Рекомендуемое расположение приватного ключа (вне репозитория):

mkdir -p ~/.config/mcp-stark-brain
chmod 700 ~/.config/mcp-stark-brain
# copy your privateKey.pem there, then:
chmod 600 ~/.config/mcp-stark-brain/privateKey.pem

Базовые URL по умолчанию:

6. Сборка пакета (wheel)

Из корня репозитория всегда явно указывайте интерпретатор Python 3.12 — не запускайте просто uv build, полагаясь на тот Python, который случайно окажется первым в вашем PATH:

rm -rf dist  # avoid mixing wheels from a previous version/build
uv build --python 3.12 -o dist

В результате в dist/ появляются устанавливаемые артефакты (точная версия в имени файла берётся из version в pyproject.toml, сейчас это 0.2.0):

dist/
  mcp_stark_brain-0.2.0-py3-none-any.whl
  mcp_stark_brain-0.2.0.tar.gz

Распространите .whl среди разработчиков (или в общем месте).

Без uv: создайте venv с помощью python3.12 -m venv .venv312, активируйте его, затем pip install build && python -m build -o dist. Сначала проверьте python3.12 --version — если эта команда не найдена, установите Python 3.12 перед продолжением; не собирайте пакет с другой основной/минорной версией.

7. Установка MCP в IDE

Установите wheel как изолированный инструмент, снова явно указав Python 3.12, чтобы окружение инструмента соответствовало тому, в котором он был собран/протестирован. Используйте glob, чтобы не редактировать номер версии вручную (и не рисковать установкой устаревшего wheel, оставшегося от предыдущей сборки):

# with uv (recommended)
uv tool install --python 3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

# or with pipx
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

Это добавляет команду mcp-stark-brain в ваш PATH.

Затем добавьте сервер в MCP-конфигурацию вашей IDE (например, Cursor ~/.cursor/mcp.json или проектный .cursor/mcp.json):

{
  "mcpServers": {
    "stark-brain": {
      "command": "mcp-stark-brain",
      "env": {
        "ALEXANDRIA_GITHUB_PAT": "<your-personal-fine-grained-PAT>",
        "STARKBANK_PRIVATE_KEY_PATH": "/Users/you/.config/mcp-stark-brain/privateKey.pem",
        "STARKBANK_PROJECT_ID": "<your-project-id>",
        "STARKBANK_DEV_BASE_URL": "https://development.api.starkbank.com",
        "STARKBANK_SANDBOX_BASE_URL": "https://sandbox.api.starkbank.com"
      }
    }
  }
}

Перезапустите/перезагрузите IDE, чтобы она подхватила новый MCP-сервер.

Хотите собственную иконку рядом с stark-brain в списке Tools & MCP (как у официального MCP github с логотипом)? Смотрите cursor-plugin/README.md — там опциональная обёртка, которая упаковывает эту же конфигурацию как локальный плагин Cursor с logo. Чисто косметика — пропустите, если не важно.

8. Обновление уже установленного MCP

Всякий раз, когда этот репозиторий меняется (новые инструменты, исправления ошибок, исправления настроек по умолчанию и т.д.), нужен новый пакет. Команда зависит от того, как вы его изначально установили — использование не той команды является самым частым источником путаницы «почему моё исправление не отображается?», поэтому выберите ту, что соответствует шагу 6:

# 1. Pull the latest source and rebuild the bundle (repo maintainer, or you if you
#    build it yourself). Always clean dist/ first to avoid mixing old/new wheels.
git pull
rm -rf dist
uv build --python 3.12 -o dist

# 2a. If you installed with `uv tool install`, use --reinstall (uv tool upgrade
#     does NOT work for local wheel paths, only for PyPI-published packages):
uv tool install --python 3.12 --reinstall ./dist/mcp_stark_brain-*-py3-none-any.whl

# 2b. If you installed with pipx, uninstall + reinstall (pipx has no local-wheel
#     upgrade command either):
pipx uninstall mcp-stark-brain
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

Затем добейтесь, чтобы Cursor действительно перезапустил процесс сервера — список инструментов, который вы видите, это то, что конкретный дочерний процесс stdio объявил при запуске, поэтому одной переустановки на диске недостаточно для обновления:

1. Сначала убедитесь, что переустановка действительно применилась (вне Cursor, в обычном терминале):

   uv tool list | grep -A2 mcp-stark-brain   # confirm the version bumped
   which mcp-stark-brain

2. Выключите/включите сервер в Cursor — это официально поддерживаемый способ перезапустить отдельный MCP-сервер без выхода из всего приложения: Cmd+Shift+J -> Tools & MCP -> найдите stark-brain -> переключите его в off, подождите пару секунд, переключите в on.

3. Откройте новый чат. Чат, открытый до переключения, может продолжать показывать старый список инструментов даже после перезапуска сервера.

4. Если инструменты всё ещё выглядят устаревшими, значит, Shared Process в Cursor — единый фоновый процесс на экземпляр приложения, который размещает все дочерние процессы MCP (не на окно, поэтому Developer: Reload Window не перезапускает его) — всё ещё держит в памяти старый дочерний процесс. Полностью завершите приложение (Cmd+Q, а не просто закройте окно) и откройте его снова; это убьёт Shared Process и вместе с ним все дочерние процессы MCP.

5. Чтобы подтвердить на уровне протокола, а не гадать: Cmd+Shift+U -> выпадающий список MCP Logs -> stark-brain -> проверьте, что ответ tools/list действительно включает новое имя инструмента. Если его там тоже нет, проблема в установленном пакете, а не в кэше Cursor — вернитесь к шагу 1.

6. Когда новые инструменты появятся, запустите инструмент status, чтобы убедиться, что обновление применилось (проверьте, что docs_mode, repo, ref, embed_model отражают ожидаемые значения).

7. Если изменилось только содержимое документации (а не код), переустанавливать ничего не нужно — просто вызовите refresh_docs() из IDE.

При обновлении вам не нужно заново генерировать PAT или повторно выполнять gcloud auth; эти учётные данные не зависят от установленной версии.

9. Первый запуск и использование

• При первом вызове инструмента документации сервер загружает содержимое alexandria и строит локальный индекс (это может занять некоторое время, пока модель эмбеддингов загрузится один раз).

• Используйте refresh_docs для повторной синхронизации после изменений документации (инкрементально: повторно обрабатываются только изменённые файлы).

• status сообщает режим документации, количество индексированных файлов, лимит скорости и настроены ли учётные данные Stark Bank API (starkbank_api_configured).

• Инструменты Stark Bank API по умолчанию используют среду development. Передавайте environment="sandbox" только тогда, когда пользователь явно просит использовать песочницу.

Доступные инструменты:

10. Удалённый и локальный режимы

• remote (по умолчанию): документация загружается из GitHub через ваш PAT. Эффективно (tarball = 1 запрос на обновление), но расходует ваш бюджет GitHub API.

• local: документация читается из каталога, который вы клонировали сами; ноль использования API.

Когда лимит частоты запросов GitHub близок к исчерпанию, сервер предупреждает вас и предлагает переключиться. Чтобы переключиться:

# clone the repo once (your own credentials)
git clone git@github.com:starkbank/alexandria.git ~/repos/alexandria

Затем либо укажите это в mcp.json:

"env": {
  "ALEXANDRIA_GITHUB_PAT": "<pat>",
  "STARK_BRAIN_DOCS_MODE": "local",
  "STARK_BRAIN_DOCS_PATH": "/Users/you/repos/alexandria"
}

или переключитесь во время выполнения через инструмент:

set_docs_source(mode="local", path="/Users/you/repos/alexandria")
refresh_docs()

11. Справочник конфигурации (переменные окружения)

См. .env.example.

12. Устранение неполадок

• configuration error: ALEXANDRIA_GITHUB_PAT is required — укажите PAT в env вашего mcp.json или переключитесь в режим local.

• GitHub 401 — PAT недействителен/истёк. Перегенерируйте его.

• GitHub 404 («Repo or ref not found»), даже если репозиторий существует — для частных репозиториев GitHub возвращает 404 и когда ресурс действительно не существует, и когда ваш токен не может его видеть, так что это почти всегда проблема токена/доступа, а не неправильные ALEXANDRIA_REPO/ALEXANDRIA_REF. Самая частая причина: fine-grained PAT, всё ещё ожидающий одобрения администратора организации (проверьте https://github.com/settings/personal-access-tokens — если там указано «Pending», см. раздел 3 с шагом одобрения или запасной вариант с классическим PAT). Запустите diagnose_github_access() для живой проверки, которая точно укажет на это.

• GitHub 403 / превышен лимит запросов — проверьте разрешения PAT или клонируйте репозиторий и используйте режим local.

• GCP credentials not found — выполните gcloud auth application-default login.

• Ошибки разрешений Datastore/Logging — вы выполнили запрос к проекту, к которому у вас нет доступа; выберите другой project или запросите доступ.

• Медленная загрузка модели при первом запуске — модель эмбеддингов кэшируется после первого использования в STARK_BRAIN_CACHE_DIR.

• Недавно добавленный инструмент не появляется после переустановки — это устаревший процесс на стороне Cursor, а не неправильная установка (см. пошагово раздел 8): запущенный MCP-подпроцесс сам по себе не подхватывает переустановку на диске. Переключите сервер выкл/вкл в Tools & MCP, откройте новый чат, и если этого всё ещё недостаточно, полностью закройте (Cmd+Q) и снова откройте Cursor.

• STARKBANK_PRIVATE_KEY_PATH is not set / инструменты API не работают — укажите абсолютный путь к вашему PEM и STARKBANK_PROJECT_ID в mcp.json (см. раздел 5). Убедитесь, что status().starkbank_api_configured равно true.

• Stark Bank API 401 / недействительная подпись — неправильный Project ID, PEM не зарегистрирован для этого окружения или рассинхронизация часов. Убедитесь, что публичный ключ зарегистрирован в соответствующем окружении Web Banking (development vs sandbox).

13. Примечания по безопасности

• Ваш PAT отправляется только в заголовке Authorization и никогда не логируется.

• Приватный ключ Stark Bank читается с диска в момент запроса и никогда не логируется.

• Ключи сервисных аккаунтов не распространяются; доступ к GCP — это ваша личная ADC-идентичность.

• GCP project передаётся в каждом вызове — нет общего/захардкоженного проекта.

• Клиент отклоняет production-хосты Stark Bank API.

• .env, *.pem, keys/ и локальный кэш игнорируются Git.

14. Разработка

Исходные файлы расположены плоской структурой в src/ (без дополнительной вложенности src/mcp_stark_brain/). Конфигурация сборки в pyproject.toml поставляет их как импортируемый пакет mcp_stark_brain в wheel (packages = ["src"] + sources = {"src" = "mcp_stark_brain"}), поэтому точки входа и внутренние импорты остаются без изменений независимо от структуры на диске.

Такое переименование несовместимо с установками в режиме разработки editable/dev-mode (ограничение hatchling/pip), поэтому uv sync настроен с tool.uv.package = false: он устанавливает только зависимости, а не сам проект. Файлы conftest.py и scripts/smoke_test.py используют devtools/bootstrap.py, чтобы import mcp_stark_brain работал напрямую с src/ для тестов и локальных скриптов, без необходимости шага установки.

uv python install 3.12
uv sync --extra dev --python 3.12
uv run ruff check .
uv run pytest
uv run python scripts/smoke_test.py

Чтобы реально попробовать сервер локально (без сборки wheel):

uv run --python 3.12 python -c "from devtools.bootstrap import ensure_importable; ensure_importable(); from mcp_stark_brain.server import main; main()"