douyin-dm-mcp

Сервер Model Context Protocol и локальный HTTP API для прямых сообщений Douyin в веб-версии, созданный на основе Playwright. Оба интерфейса используют один и тот же постоянный локальный профиль браузера, читают текущие отображаемые диалоги и сообщения и отправляют отдельные сообщения только при явном включении.

Проект использует текущую отдельную страницу чата Douyin:

https://www.douyin.com/chat?isPopup=1

Проверка входа и состояния аккаунта по-прежнему использует главную страницу Douyin. /messages в настоящее время возвращает страницу 404 и не используется для автоматизации.

Границы безопасности

• DOUYIN_ALLOW_SEND по умолчанию имеет значение false, поэтому реальная отправка отключена по умолчанию.

• send_message по умолчанию использует dryRun: true. Пробные запуски проверяют текущий снимок без открытия диалога или изменения состояния страницы.

• Реальная отправка требует как отключения пробного режима, так и DOUYIN_ALLOW_SEND=true.

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

• Дублирующиеся никнеймы помечаются как targetable: false и отклоняются как инструментами MCP, так и CLI на основе никнеймов.

• Если после нажатия кнопки отправки результат не может быть подтвержден, сервер возвращает SEND_STATUS_UNKNOWN и не выполняет автоматические повторные попытки.

• Каждый профиль браузера имеет эксклюзивную блокировку файловой системы, чтобы предотвратить повреждение профиля одновременными экземплярами Chromium. MCP, HTTP API и операторский CLI не могут работать одновременно с одним и тем же DOUYIN_PROFILE.

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

• Проект не изменяет отпечатки браузера, не обходит проверочные задачи и не вызывает частные WebSocket/Protobuf интерфейсы Douyin.

• Журналы записываются в stderr и скрывают тела сообщений, файлы cookie и поля паролей.

Related MCP server: dy-mcp

Текущие ограничения

DOM отображаемых диалогов Douyin не предоставляет поддерживаемый стабильный идентификатор диалога, идентификатор пользователя, sec_uid или стабильную ссылку на профиль. Поэтому:

• conversationKey непрозрачен и действителен только для последнего снимка list_conversations.

• Вызов list_conversations создает новые ключи и немедленно делает недействительными все ключи из предыдущего снимка.

• Каждый диалог возвращает stableKey: false; дублирующиеся никнеймы дополнительно возвращают targetable: false.

• Вызывайте list_conversations перед вызовом read_messages или send_message, затем используйте ключ из этого точного результата.

• Список диалогов содержит только элементы, которые в данный момент отображаются браузером; complete всегда имеет значение false.

• Нечеткое сопоставление никнеймов, массовая отправка, поиск незнакомцев и резервные варианты поиска для отправки намеренно не поддерживаются.

Подробные доказательства с живой страницы записаны в RESEARCH.md.

Требования

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

• npm

• Графическое окружение, способное отображать Chromium для первоначального входа по QR-коду

Установка

npm install
npx playwright install chromium
npm run build

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

Эти переменные считываются из окружения процесса. Проект не загружает .env. Используйте .env.example в качестве справки, затем экспортируйте значения в вашей оболочке или задайте их в блоке env клиента MCP.

Данные браузера хранятся в:

.data/profiles/<DOUYIN_PROFILE>

Этот каталог содержит данные аутентификации. Не коммитьте и не передавайте его.

Вход

Для первого использования или истекшей сессии выполните:

npm run login

Отсканируйте отображаемый QR-код с помощью Douyin. После входа скрипт выводит структурированный статус, безопасно закрывает Chromium и сохраняет аутентифицированную сессию в постоянном профиле.

Проверьте текущую сессию:

npm run status

Пример успешного результата:

{
  "ok": true,
  "browserRunning": true,
  "loggedIn": true,
  "currentUrl": "https://www.douyin.com/jingxuan"
}

Запуск MCP-сервера

Скомпилированная точка входа:

node dist/index.js

Пример для Codex CLI:

codex mcp add douyin-dm -- node /absolute/path/to/douyin-dm-mcp/dist/index.js

Общая конфигурация MCP-клиента:

{
  "mcpServers": {
    "douyin-dm": {
      "command": "node",
      "args": ["/absolute/path/to/douyin-dm-mcp/dist/index.js"],
      "env": {
        "DOUYIN_PROFILE": "default",
        "DOUYIN_ALLOW_SEND": "false"
      }
    }
  }
}

Для авторизованной реальной отправки установите DOUYIN_ALLOW_SEND в true для этого процесса MCP и перезапустите его. Не оставляйте отправку глобально включенной.

Не запускайте этот процесс, пока HTTP API или CLI уже удерживают блокировку того же профиля.

Запуск HTTP API

Запуск из исходников:

npm run api

Или запуск скомпилированной точки входа:

node dist/api.js

Не запускайте этот процесс, пока MCP или CLI уже удерживают блокировку того же профиля.

Базовый URL по умолчанию: http://127.0.0.1:3000. Неаутентифицированная проверка работоспособности:

curl http://127.0.0.1:3000/health

Маршруты API:

POST-запросы требуют Content-Type: application/json. Отправка остается пробной по умолчанию. Реальная отправка по-прежнему требует как "dryRun": false, так и DOUYIN_ALLOW_SEND=true.

Пример:

curl "http://127.0.0.1:3000/api/v1/conversations?limit=20"

curl -X POST http://127.0.0.1:3000/api/v1/messages/read \
  -H "Content-Type: application/json" \
  -d '{"conversationKey":"fallback:...:0","limit":20}'

Доступ через loopback не требует ключа API. Привязка к любому другому хосту отклоняется, если DOUYIN_API_KEY не установлен как минимум из 16 символов. При настройке отправляйте его в каждом запросе /api/v1/*:

curl http://127.0.0.1:3000/api/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY"

API возвращает те же структурированные объекты успеха и ошибок Douyin, что и MCP. Ошибки разбора запросов используют INVALID_REQUEST, INVALID_JSON, UNSUPPORTED_MEDIA_TYPE или PAYLOAD_TOO_LARGE; ошибки аутентификации используют UNAUTHORIZED.

Инструменты MCP

browser_status

Проверяет, аутентифицирован ли постоянный профиль браузера Douyin.

Входные данные: нет.

list_conversations

Открывает отдельную страницу чата и возвращает текущие отображаемые диалоги с непрозрачными значениями conversationKey для нового снимка.

{
  "limit": 20
}

Поля диалога:

• conversationKey

• stableKey, в настоящее время всегда false

• position

• nickname

• preview

• timestamp

• targetable, false, когда дублирующиеся никнеймы делают безопасный выбор невозможным

read_messages

Читает текущие видимые сообщения из диалога, возвращенного list_conversations.

{
  "conversationKey": "fallback:550e8400-e29b-41d4-a716-446655440000:0",
  "limit": 20
}

Поля сообщения:

• direction: incoming или outgoing, на основе проверенных доказательств DOM со стороны отправителя

• type: text или unsupported для нераспознанных типов сообщений

• content: видимый текст или null, если пусто

Диалоги с targetable: false отклоняются.

send_message

Отправляет одно сообщение в проверенный диалог.

{
  "conversationKey": "fallback:550e8400-e29b-41d4-a716-446655440000:0",
  "text": "Test message",
  "dryRun": true
}

Реальная отправка требует всех следующих условий:

1. DOUYIN_ALLOW_SEND=true.

2. dryRun=false.

3. Целевой никнейм уникален в текущем снимке.

4. Позиция диалога и точный никнейм по-прежнему совпадают со снимком.

5. Заголовок открытого чата точно совпадает с целевым никнеймом.

6. Сообщение не имеет ведущих или завершающих пробелов.

7. Логический текст редактора Slate точно совпадает с запрошенным текстом.

После нажатия кнопки отправки сервер ожидает новое исходящее сообщение с точным каноническим текстом. Если подтверждение не удается, он возвращает SEND_STATUS_UNKNOWN; вызывающие должны вручную проверить диалог вместо автоматических повторных попыток. Минимальный интервал отправки сохраняется при обновлениях списка диалогов.

Операторский CLI

Список текущих отображаемых диалогов:

npm run chat -- list

Чтение сообщений по точному уникальному никнейму:

npm run chat -- read "Exact nickname"

Реальная отправка также требует DOUYIN_ALLOW_SEND. Пример для PowerShell:

$env:DOUYIN_ALLOW_SEND="true"
npm run chat -- send "Exact nickname" "Test message"
Remove-Item Env:DOUYIN_ALLOW_SEND

CLI принимает только точные никнеймы и отказывается продолжать, если совпадений нет или найдено несколько.

Не запускайте CLI, пока MCP или HTTP API уже удерживают блокировку того же профиля.

Разработка

npm run lint
npm test
npm run build
npm run smoke:mcp

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

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

src/
  browser/          Browser lifecycle, profile locking, and operation serialization
  douyin/           DouyinService, centralized selectors, and page objects
  index.ts          MCP stdio server
  api.ts            HTTP API process entry point
  api/              Versioned HTTP routes, validation, and authentication
scripts/
  login.ts          QR-code login
  status.ts         Authentication status check
  chat.ts           Operator CLI
  mcp-smoke.ts      MCP transport smoke check
tests/unit/         Repeatable behavioral tests
RESEARCH.md         Live-page evidence and engineering research

Лицензия

Лицензировано по разрешительной лицензии MIT.