douyin-dm-mcp

Playwright로 구축된 Douyin 웹 다이렉트 메시지용 Model Context Protocol 서버 및 로컬 HTTP API입니다. 두 인터페이스 모두 동일한 영구 로컬 브라우저 프로필을 재사용하며, 현재 렌더링된 대화와 메시지를 읽고, 명시적으로 활성화된 경우에만 개별 메시지를 전송합니다.

이 프로젝트는 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에 대해 동시에 실행할 수 없습니다.

• 모든 페이지 작업은 직렬화되어 대화 간 읽기 또는 전송을 방지합니다.

• 이 프로젝트는 브라우저 지문을 수정하거나, 검증 챌린지를 우회하거나, Douyin의 비공개 WebSocket/Protobuf 인터페이스를 호출하지 않습니다.

• 로그는 stderr에 기록되며 메시지 본문, 쿠키 및 비밀번호 필드를 삭제합니다.

Related MCP server: dy-mcp

현재 제한 사항

Douyin의 렌더링된 대화 DOM은 지원되는 안정적인 대화 ID, 사용자 ID, sec_uid 또는 안정적인 프로필 링크를 노출하지 않습니다. 따라서:

• conversationKey는 불투명하며 최신 list_conversations 스냅샷에 대해서만 유효합니다.

• list_conversations를 호출하면 새 키가 생성되고 이전 스냅샷의 모든 키가 즉시 만료됩니다.

• 모든 대화는 stableKey: false를 반환합니다. 중복 닉네임은 추가로 targetable: false를 반환합니다.

• read_messages 또는 send_message를 호출하기 전에 list_conversations를 호출한 다음 해당 정확한 결과의 키를 사용하십시오.

• 대화 목록에는 브라우저에 현재 렌더링된 항목만 포함됩니다. complete는 항상 false입니다.

• 퍼지 닉네임 일치, 대량 전송, 낯선 사람 검색 및 검색-전송 대체는 의도적으로 지원되지 않습니다.

자세한 라이브 페이지 증거는 RESEARCH.md에 기록되어 있습니다.

요구 사항

• Node.js 20 이상

• npm

• 초기 QR 코드 로그인을 위해 Chromium을 표시할 수 있는 데스크톱 환경

설치

npm install
npx playwright install chromium
npm run build

구성

이 변수들은 프로세스 환경에서 읽습니다. 프로젝트는 .env를 로드하지 않습니다. .env.example을 참조로 사용한 다음 셸에서 값을 내보내거나 MCP 클라이언트 env 블록에 설정하십시오.

브라우저 데이터는 다음 위치에 저장됩니다:

.data/profiles/<DOUYIN_PROFILE>

이 디렉터리에는 인증 데이터가 포함되어 있습니다. 커밋하거나 공유하지 마십시오.

로그인

첫 사용 또는 세션 만료 시 다음을 실행하십시오:

npm run login

Douyin으로 표시된 QR 코드를 스캔하십시오. 로그인 후 스크립트는 구조화된 상태를 출력하고 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"
      }
    }
  }
}

승인된 실제 전송을 위해 해당 MCP 프로세스에 대해 DOUYIN_ALLOW_SEND를 true로 설정하고 다시 시작하십시오. 전송을 전역적으로 활성화된 상태로 두지 마십시오.

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}'

루프백 액세스에는 API 키가 필요하지 않습니다. DOUYIN_API_KEY가 최소 16자로 설정되지 않으면 다른 호스트에 바인딩이 거부됩니다. 구성된 경우 모든 /api/v1/* 요청에 키를 보내십시오:

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

API는 MCP와 동일한 구조화된 성공 및 Douyin 오류 객체를 반환합니다. 요청 구문 분석 오류는 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: 검증된 발신자 측 DOM 증거에서 incoming 또는 outgoing

• 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는 정확한 닉네임만 허용하며 일치 항목이 없거나 여러 개 발견되면 계속 진행을 거부합니다.

MCP 또는 HTTP API가 이미 동일한 프로필 잠금을 보유하고 있는 동안 CLI를 실행하지 마십시오.

개발

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 라이선스에 따라 라이선스가 부여됩니다.