DualStream MCP Server

저희의 첫 오픈소스 프로젝트입니다! DualStream용 공식 Model Context Protocol 서버입니다. DualStream은 단일 파이프라인에서 데스크톱(16:9) 및 모바일(9:16) 스트림을 동시에 제작하는 스트리밍 스튜디오입니다.

이 서버를 사용하면 Claude 같은 AI 어시스턴트가 여러분의 DualStream 스튜디오를 운영할 수 있습니다. 장면 전환, 인스턴트 리플레이 클립 저장, 처음부터 전체 장면 레이아웃 구성, 알림과 위젯 스타일 변경, 스트림에서 일어나는 일에 반응하기 등이 가능합니다. 모든 작업은 사용자의 명시적 승인 아래 로컬 머신에서 실행되며, 모든 변경 사항은 데스크톱 및 모바일 캔버스 양쪽에 반영됩니다.

AI assistant (Claude Code, Claude Desktop, or any MCP client)
        |  MCP over stdio
        v
DualStream MCP server  (this package)
        |  JSON-RPC over WebSocket, 127.0.0.1 only
        v
DualStream desktop app

요청할 수 있는 것

연결이 완료되면 자연어로 어시스턴트에게 말할 수 있습니다.

• "내 BRB 장면으로 전환해 줘"

• "지난 30초를 클립으로 저장해 줘"

• "MAIN이라는 장면을 만들어 줘. 웹캠은 오른쪽 아래에 두고 원형으로 크롭하고, 기본 디스플레이는 그 뒤에 전체 화면으로 깔아 줘"

• "자선 스트리밍용 시작 전 장면을 내 브랜드 색상으로 만들어 줘, 두 캔버스 모두"

• "내 알림이 이 팔레트에 맞게 스타일을 바꿔 줘"

• "카메라를 조금 위로 움직이고 부드러운 그림자를 넣어 줘"

어시스턴트는 실제 하드웨어(카메라, 디스플레이, 창, 마이크)를 찾아내고, 데스크톱 및 모바일 캔버스 레이아웃을 독립적으로 구성하며, 원하는 모습이 될 때까지 사용자와 함께 반복 조정합니다.

Related MCP server: ATEM MCP Server

시작하기 전에

설치할 항목이 세 가지 있습니다. 모두 일반적인 다운로드 후 설치 프로그램을 실행하는 방식입니다.

1. DualStream 데스크톱 앱 (Windows 또는 macOS): 이 서버가 제어하는 스튜디오입니다.

2. Node.js: 크고 초록색인 LTS 버튼(버전 22 이상)을 선택하세요. 이것은 서버를 실행하는 런타임이며, 직접 다룰 필요는 없습니다.

3. MCP를 지원하는 AI 어시스턴트(예: Claude Desktop 또는 Claude CLI).

설치

1단계: 이 프로젝트를 컴퓨터에 가져오기

이 GitHub 페이지 상단의 초록색 Code 버튼을 클릭하고 Download ZIP을 선택한 다음, 기억할 만한 곳(예: 내 문서 폴더)에 압축을 풉니다. (git에 익숙하다면 git clone으로도 가능합니다.)

2단계: 빌드하기

압축을 푼 폴더에서 터미널을 엽니다.

• Windows: 파일 탐색기에서 폴더를 열고, 주소 표시줄을 클릭하고, cmd를 입력한 다음 Enter 키를 누릅니다.

• macOS: 폴더를 마우스 오른쪽 버튼으로 클릭하고 폴더에 새 터미널을 선택합니다(또는 폴더를 터미널로 드래그합니다).

그런 다음 두 명령을 차례로 실행합니다.

npm install
npm run build

각 명령은 텍스트를 출력하고 프롬프트로 돌아옵니다. 그게 전부입니다. 서버가 빌드되었습니다.

3단계: 어시스턴트에 알려 주기

1단계의 폴더 전체 경로가 필요합니다. Windows 파일 탐색기에서 주소 표시줄을 클릭해 복사합니다(C:\Users\you\Documents\DualStreamMCP 같은 형태입니다). macOS에서는 폴더를 마우스 오른쪽 버튼으로 클릭하고 Option을 누른 채 경로 이름 복사를 선택합니다.

Claude Desktop: 설정 → 개발자 → 구성 편집을 열고 다음을 추가합니다(경로를 자신의 것으로 바꾸세요. Windows에서는 표시된 대로 이중 백슬래시를 사용하세요):

{
  "mcpServers": {
    "dualstream": {
      "command": "node",
      "args": ["C:\\Users\\you\\Documents\\DualStreamMCP\\dist\\index.js"]
    }
  }
}

Claude CLI: 명령 하나입니다(경로를 자신의 것으로 바꾸세요):

claude mcp add dualstream -- node "C:\Users\you\Documents\DualStreamMCP\dist\index.js"

다른 MCP 클라이언트도 같은 방식으로 작동합니다. node <folder>/dist/index.js를 stdio 서버로 실행하세요.

4단계: 인사해 보기

어시스턴트를 다시 시작하고, DualStream이 실행 중인지 확인한 다음 *"DualStream에서 지금 어떤 장면이 송출되고 있나요?"*라고 물어보세요. 처음에는 DualStream이 승인 프롬프트를 표시할 것입니다. 이것은 보안 모델이 작동하고 있기 때문입니다(아래 참조). 승인하면 완료입니다.

첫 연결 및 보안

DualStream 앱은 127.0.0.1에만 바인딩된 소형 제어 서버를 실행합니다. 네트워크에서 접근할 수 있는 것은 없으며, 이 MCP 서버는 앱과 같은 머신에서 실행되어야 합니다. 클라우드 구성 요소는 없습니다. 지능은 사용자가 연결하는 AI 어시스턴트가 제공하며, 스트림은 사용자의 통제를 벗어나지 않습니다.

페어링은 자동입니다. 앱이 구성 디렉터리에 페어링 토큰을 게시하면 이 서버가 자체적으로 가져옵니다. 비밀번호를 입력할 필요가 없습니다. 어시스턴트가 처음 연결되면 DualStream이 클라이언트를 지정하는 동의 프롬프트를 표시합니다. 허용, 항상 허용 또는 거부 중에서 선택합니다. 승인하기 전에는 연결이 어떤 작업도 수행할 수 없습니다. 앱의 설정, 일반, 외부 제어에서 연결된 모든 클라이언트를 확인하고, 언제든지 해당 클라이언트의 연결을 끊거나 기억된 승인을 취소할 수 있습니다.

연결을 거부하면 서버가 해당 연결을 닫습니다. 앱 설정에서 페어링 토큰을 재설정하면 연결된 모든 클라이언트가 연결 해제되고 다시 페어링해야 합니다.

도구

장면 및 클립

장면 구성

소스 단위로 장면을 만들고 편집합니다. 데스크톱(1920x1080) 및 모바일(1080x1920) 캔버스의 레이아웃은 독립적으로 제어되므로, 데스크톱의 작은 원형 페이스캠은 모바일에서 전체 너비의 정사각형 카메라가 될 수 있습니다.

레시피

레시피는 DualStream에서 공유할 수 있는 장면 템플릿입니다. 두 캔버스 모두를 위한 배경과 배치된 소스로 구성되며 디스크에 JSON으로 저장됩니다.

위젯

AI 카드

자동화

자동화는 스트림 이벤트 트리거(레이드, 큰 응원, 하이프 트레인 종료)를 어시스턴트의 상시 지시와 연결합니다. 일치하는 이벤트가 발생하면 DualStream은 지시를 첨부하여 어시스턴트에게 중계하고, 어시스턴트는 카드를 작성하고 게시합니다. 활성화된 자동화와 일치하는 이벤트만 앱을 떠나며, 어시스턴트는 세션을 열어 둔 동안에만 듣습니다. 전체 문서 형식, 이벤트 용어, 리허설 흐름은 contract/automations-v1.md에 있습니다.

일반적인 라이브 세션은 이렇게 진행됩니다. 어시스턴트에게 라이브를 시작한다고 말하면, 어시스턴트는 자동화를 읽은 다음 wait_for_event를 반복합니다. 대기에는 비용이 들지 않으며, 처리되는 각 이벤트는 짧은 교환 하나입니다(레이더를 환영하고, 큰 후원자에게 감사 인사를 전하고, 카드를 게시합니다).

도구 오류는 retryable 플래그가 포함된 구조화된 JSON입니다. 따라서 어시스턴트는 "1초 후 다시 시도" 상황(리플레이 버퍼가 아직 준비 중이거나 연결이 승인을 기다리는 중)과 "실제로 문제가 있는" 상황을 구분할 수 있습니다.

구성

앱과 이 서버가 동일한 사용자 계정으로 실행되면 구성 없이도 모든 것이 작동합니다. 다음 환경 변수는 특수한 구성에서 사용됩니다.

디스커버리는 앱의 구성 디렉터리에서 ws-control.json을 읽습니다(Windows에서는 %APPDATA%\app.dualstream.io\, macOS에서는 ~/Library/Application Support/app.dualstream.io/). 앱은 시작할 때마다 컨트롤 서버가 준비 상태를 보고하기 전에 이 파일을 작성합니다.

문제 해결

도구가 app_not_running을 반환합니다. DualStream 앱이 열려 있지 않거나 시작이 완료되지 않았습니다. 앱을 실행하세요. 앱이 가동되는 순간 서버는 자동으로 다시 연결됩니다.

도구가 consent_pending을 반환합니다. 연결이 사용자의 승인을 기다리고 있습니다. DualStream 내부의 동의 프롬프트(또는 설정 > 일반 > 외부 제어)에서 승인하세요.

도구가 authentication_required 또는 authentication_failed를 반환합니다. 앱에서 인증이 활성화되어 있지만 이 서버가 토큰을 얻지 못했습니다. 앱과 서버가 같은 사용자로 실행되고 있는지 확인하세요. 최근에 페어링 토큰을 재설정했다면 재연결이 이를 자동으로 처리합니다. 환경 변수에 설정된 오래된 DUALSTREAM_CONTROL_PASSWORD도 이 문제를 일으킬 수 있습니다.

다른 문제가 있습니다. 먼저 get_connection_status를 호출하세요. 이 함수는 '앱이 실행 중이 아님'을 인증, 동의, 프로토콜 문제와 구분해 줍니다. 서버는 stderr에 한 줄 JSON으로 로그를 기록합니다. 자세한 내용을 보려면 DUALSTREAM_MCP_LOG_LEVEL=debug로 설정하세요.

설계 노트

• 설계상 로컬 전용입니다. 컨트롤 플레인은 루프백 전용입니다. 호스팅된 커넥터나 원격 커넥터는 이에 도달할 수 없으며, 절대 도달해서도 안 됩니다.

• 이벤트 기반, 타이머 없음. 진행 중인 요청은 서버 응답 또는 소켓 종료가 있어야만 해소되며, 실제 경과 시간에 따른 타임아웃은 없습니다. 재연결은 앱이 시작할 때 다시 쓰는 디스커버리 파일을 감시함으로써 트리거되며, 폴링 루프는 없습니다.

• stdout은 프로토콜 채널입니다. 모든 로깅은 한 줄 JSON으로 stderr에 기록됩니다.

• 계약 고정. 응답은 번들된 컨트롤 계약(contract/ 참조)에 대해 검증됩니다. 더 새로운 프로토콜 버전을 사용하는 앱은 조용히 오작동하는 대신 업그레이드 메시지와 함께 명확하게 실패합니다.

• 동의는 서버 측에서 강제됩니다. 승인 게이트는 이 패키지가 아닌 DualStream 앱에 있습니다. 수정된 클라이언트는 얻을 수 있는 것이 없습니다.

contract/ 디렉터리에는 어시스턴트가 직접 사용할 수 있는 작성 참조 자료도 포함되어 있습니다: 레시피 매니페스트 형식, 장면 구성 가이드(모바일 캔버스의 레이아웃 패턴 포함), 자동화 형식, 그리고 PROTOCOL.md: 계약 픽스처에서 생성된 전체 메서드, 이벤트 및 오류 코드 참조입니다.

개발

npm run typecheck   # strict TypeScript over src and tests
npm test            # unit + full MCP round-trips against a wire-faithful mock of the app
npm run build       # emit dist/
npm run smoke       # live end-to-end against a running DualStream app
                    # (switches a scene and back, saves one 10-second clip pair)

test/의 목 컨트롤 서버는 페어링 핸드셰이크와 동의 흐름을 포함한 실제 와이어 프로토콜을 구현하며, 인증 알고리즘을 독립적으로 구현하므로 테스트 스위트가 클라이언트를 진정으로 교차 검증합니다.

DualStream 소개

DualStream은 데스크톱과 모바일 플랫폼에서 동시에 라이브 방송하는 크리에이터를 위한 스트리밍 스튜디오입니다. 하나의 파이프라인, 두 개의 캔버스, 모든 장면과 위젯이 두 플랫폼 모두를 위해 네이티브로 렌더링됩니다. Windows 또는 macOS용은 dualstream.gg에서 다운로드하세요.

라이선스

Apache-2.0