Archery MCP 2FA

Постоянный патч, добавляющий поддержку двухфакторной аутентификации (2FA) Archery TOTP для @seaxlab/archery-mcp.

Этот проект не подключается напрямую к базе данных и не обходит механизмы прав доступа, десенсибилизации, ограничения частоты запросов или аудита Archery. Он лишь расширяет процесс входа, позволяя учётным записям Archery с включённым TOTP проходить аутентификацию через MCP-сервис.

Текущий патч применим только к @seaxlab/archery-mcp@3.0.2. Перед обновлением вышестоящей зависимости убедитесь, что патч по-прежнему совместим, и заново сгенерируйте файл патча.

Возможности

• Автоматический вход при запуске с использованием учётной записи и пароля Archery из конфигурации.

• При обнаружении запроса TOTP — интерактивный запрос 6-значного кода в терминале.

• При отсутствии интерактивного терминала — предоставление MCP-инструментов для завершения аутентификации.

• Повторное использование одной и той же сессии Archery после успешной аутентификации.

• Код TOTP используется только для текущего запроса и не записывается в файл конфигурации или кэш метаданных.

• Автоматическое применение патча после установки зависимостей с помощью patch-package.

Related MCP server: auth-vault

Требования к окружению

• Node.js 24 или новее.

• npm 10 или новее.

• Доступный сервис Archery; вышестоящий пакет указывает поддержку Archery v1.8.5.

• Учётная запись Archery с включённым TOTP или обычная учётная запись с паролем.

Быстрый старт

1. Получение проекта и установка зависимостей

git clone <repository-url>
cd archery-mcp-2fa
npm ci

После завершения npm ci скрипт postinstall автоматически применит патч 2FA из patches/.

2. Подготовка файла конфигурации

Можно создать конфигурацию на основе примера, предоставляемого вышестоящим пакетом:

mkdir -p ~/.config/archery-mcp
cp node_modules/@seaxlab/archery-mcp/config.example.toml \
  ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

Отредактируйте ~/.config/archery-mcp/pro.toml, заполнив как минимум следующее:

env = "pro"

[server]
host = "127.0.0.1"
port = 3000

[archery]
base_url = "https://archery.example.com"
username = "mcp_service"
password = "replace-with-a-strong-password"

[query]
default_limit = 100
max_limit = 500

[cache]
enabled = true
ttl_seconds = 604800
exclude_instance_names = []
exclude_instance_ids = []

Файл конфигурации содержит пароль в открытом виде — всегда ограничивайте права доступа к файлу и не коммитьте реальную конфигурацию в репозиторий.

Полное описание параметров конфигурации см. в node_modules/@seaxlab/archery-mcp/README.md и config.example.toml после установки вышестоящего проекта.

3. Запуск сервиса

Укажите файл конфигурации через аргумент командной строки:

npm start -- --config ~/.config/archery-mcp/pro.toml

Также можно использовать переменные окружения:

ARCHERY_MCP_CONFIG=~/.config/archery-mcp/pro.toml npm start

Адрес MCP по умолчанию:

http://127.0.0.1:3000/mcp

Адрес проверки работоспособности:

http://127.0.0.1:3000/health

Процесс аутентификации TOTP

Интерактивный терминал

Если у учётной записи включён TOTP, при запуске терминал выведет запрос:

archery-mcp [env=pro] Archery requires TOTP authentication
请输入当前 6 位 TOTP 验证码:

Введите код, отображаемый в текущий момент в приложении-аутентификаторе. После успешной аутентификации сервис начнёт прослушивать порт:

archery-mcp [env=pro] TOTP authentication succeeded
archery-mcp [env=pro] listening on http://127.0.0.1:3000/mcp

При неверном коде можно сразу повторить попытку. После истечения сессии Archery или перезапуска процесса потребуется повторная аутентификация.

Без интерактивного терминала

Когда сервис запускается контейнером, фоновой задачей или менеджером процессов и интерактивный терминал отсутствует, сервис всё равно запускается и регистрирует следующие MCP-инструменты:

Шаги аутентификации:

1. Вызовите archery_auth_status.

2. Если возвращено two_factor_required: true, запросите у пользователя 6-значный код, отображаемый в текущий момент в аутентификаторе.

3. Вызовите archery_submit_otp с параметром { "otp": "123456" }.

4. Убедившись, что возвращено authenticated: true, вызывайте инструменты запросов или SQL-аудита.

За исключением двух указанных выше инструментов аутентификации, остальные MCP-инструменты идентичны вышестоящему @seaxlab/archery-mcp.

Конфигурация MCP-клиента

Подключитесь с помощью MCP-клиента, поддерживающего Streamable HTTP:

{
  "mcpServers": {
    "archery": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Codex можно настроить в ~/.codex/config.toml:

[mcp_servers.archery]
url = "http://127.0.0.1:3000/mcp"

Claude Code можно добавить через командную строку:

claude mcp add --transport http archery http://127.0.0.1:3000/mcp

Структура проекта

.
├── patches/
│   └── @seaxlab+archery-mcp+3.0.2.patch  # TOTP 支持补丁
├── package.json                           # 依赖和启动脚本
├── package-lock.json                      # 锁定依赖版本
└── README.md

Часто используемые команды

Не запускайте сервис напрямую через npx -y @seaxlab/archery-mcp@3.0.2 — в этом случае будет запущен официальный npm-пакет без патча 2FA из этого проекта.

Замечания по безопасности

• По умолчанию сервис прослушивает только 127.0.0.1. HTTP-эндпоинт MCP сам по себе не имеет аутентификации и не должен быть напрямую доступен из публичной сети.

• Для доступа с других машин добавьте на уровне обратного прокси TLS, аутентификацию доступа и контроль сетевого доступа.

• Пароль Archery хранится в TOML-конфигурации — установите chmod 600 и используйте выделенную служебную учётную запись с минимальными правами.

• Не коммитьте реальные пароли, коды TOTP, сессионные cookie, внутренние адреса Archery или производственные конфигурации в репозиторий, Issue или журналы.

• Код TOTP передаётся через MCP-запросы. При использовании удалённого MCP-клиента убедитесь, что канал связи доверенный и зашифрованный.

Совместимость и обслуживание

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

1. Обновить версию @seaxlab/archery-mcp в package.json.

2. Выполнить npm install и проверить конфликты патча.

3. Заново реализовать и проверить изменения 2FA в node_modules/@seaxlab/archery-mcp.

4. Выполнить npx patch-package @seaxlab/archery-mcp для генерации нового патча.

5. Проверить процесс аутентификации отдельно в интерактивном терминале и без него.

Вклад

Приветствуются Issue и Pull Request. Перед отправкой кода убедитесь, что в нём нет реальных учётных записей, паролей, кодов, cookie, внутренних доменных имён или другой чувствительной информации.

Благодарности и заявление

Этот проект создаёт патч на основе публично выпущенного пакета @seaxlab/archery-mcp и не является официальным проектом Archery или мейнтейнеров вышестоящего пакета. Права на Archery и связанные наименования принадлежат их соответствующим владельцам.