Serial Bridge

Serial Bridge는 로컬 Operator와 MCP Agent 간에 두 개의 직렬 콘솔을 공유하는 허브입니다. OS에 종속되지 않습니다. requirements.txt의 Python 패키지를 설치하고 Python 3.10 이상이 설치된 모든 호스트에서 실행할 수 있습니다. 허브는 serial_bridge/ 패키지에 있으며, python -m serial_bridge 또는 루트의 app.py shim으로 시작합니다.

설치 및 시작

Python 3.10 이상을 권장합니다.

python -m pip install -r requirements.txt
python -m serial_bridge

아래 셸 스니펫은 PowerShell($env:NAME = "...")을 사용합니다. bash나 zsh에서는 동일한 이름을 export NAME=...으로 설정하세요.

허브는 수신 대기 중일 때 콘솔을 http://127.0.0.1:8765/로 엽니다. 루트의 app.py shim도 동일합니다. 브라우저 탭을 열지 않고 시작하려면:

$env:SERIAL_BRIDGE_OPEN_UI = "off"
python -m serial_bridge

또는 --no-open-ui를 전달하세요. 환경 변수가 이를 비활성화할 때 --open-ui로 강제로 열 수 있습니다. SERIAL_BRIDGE_OPEN_UI를 설정 해제하면 기본적으로 열립니다. 0, false, no, off(대소문자 무시)만이 이를 비활성화합니다.

첫 부팅 시 허브는 serial_bridge.token 파일에 Access Token을 자동 생성합니다. 포트 바인딩 구성 파일 옆에 생성됩니다(SERIAL_BRIDGE_TOKEN_FILE로 경로를 재정의할 수 있음). 이 시크릿 파일을 커밋하지 마세요.

Setup(http://127.0.0.1:8765/setup)을 허브 호스트에서 열어 Hub URL을 복사하고, Access Token을 확인 및 회전시키고, Cursor mcpServers 스니펫을 붙여넣으세요. Setup은 루프백(127.0.0.1 / ::1)에서만 접근할 수 있습니다.

또는 Hub를 시작하기 전에 SERIAL_BRIDGE_TOKEN을 설정하여 동일한 시크릿을 MCP 클라이언트에 제공할 수 있습니다. 환경 변수는 해당 프로세스 수명 동안 파일을 재정의합니다. 토큰을 회전시키면 파일은 재작성되지만, 환경 변수가 설정 해제되거나 허브가 재시작될 때까지 경고가 표시됩니다.

MCP 인증은 루프백에서도 필수입니다. 토큰을 소스 제어, 정적 프론트엔드 파일, URL 또는 로그에 넣지 마세요.

허브는 0.0.0.0:8765에서 수신 대기하므로 로컬 네트워크에서도 접근 가능합니다. 적절한 호스트 방화벽과 강력한 토큰을 사용하세요. 원격 Agent는 모드를 변경하거나 포트 바인딩을 수정할 수 없습니다.

MCP

Setup(/setup)에서 Hub 호스트의 Cursor 구성을 복사해 붙여넣으세요. 수동 연결:

Agent의 Streamable HTTP MCP 연결을 다음과 같이 구성하세요:

URL: http://<hub-host>:8765/mcp
Authorization: Bearer <SERIAL_BRIDGE_TOKEN>

/mcp를 정확히 사용하세요. Web UI는 /에 있습니다. MCP Server는 다음을 노출합니다:

• serial_status: 현재 모드와 각 Target의 포트 바인딩, 열림 상태, 사용 중 여부를 읽습니다.

• serial_exec: 하나의 텍스트 명령을 보내고 유휴 간격, 선택적 프롬프트 일치 또는 60초 제한시간까지 출력을 캡처합니다.

• serial_send: 출력을 기다리지 않고 텍스트 줄 또는 원시 페이로드를 보냅니다.

상태 확인 및 Exec 사용법:

1. Web UI를 로컬에서 열고 Bridge 모드로 전환하세요.

2. MCP 클라이언트를 위 URL에 Bearer 헤더로 연결하세요.

3. 인자 없이 serial_status를 호출하여 mode가 bridge이고 의도한 Target이 열려 있는지 확인하세요.

4. {"target":"linux","cmd":"uname -a"} 또는 {"target":"rtos","cmd":"help"}로 serial_exec를 호출하세요.

5. 장치에 안정적인 프롬프트가 있다면 선택적으로 prompt를 전달하세요. prompt_is_regex는 프롬프트 값이 정규 표현식일 때만 true로 설정하세요.

serial_exec는 Target 이름 linux와 rtos를 사용하며 직렬 장치 이름을 사용하지 않습니다. 캡처된 output과 함께 timed_out, truncated, aborted 플래그를 반환합니다.

serial_exec 출력과 live/*.log 기록은 일반 텍스트이며 ANSI 이스케이프 시퀀스가 제거됩니다. Web UI는 이스케이프 시퀀스를 해석하여 색상을 표시합니다.

포트 바인딩

포트 바인딩은 Target을 직렬 장치 경로와 보드율에 할당합니다. 기본 제공 값은 Windows 스타일입니다(linux는 COM3, rtos는 COM6, 둘 다 115200). Linux나 macOS에서는 /dev/ttyUSB0 같은 경로로 설정하세요.

시작 전에 환경 변수로 재정의하세요:

$env:SERIAL_BRIDGE_LINUX_PORT = "COM8"
$env:SERIAL_BRIDGE_LINUX_BAUD = "57600"
$env:SERIAL_BRIDGE_RTOS_PORT = "COM9"
$env:SERIAL_BRIDGE_RTOS_BAUD = "115200"
python -m serial_bridge

동일한 CLI 플래그는 --linux-port, --linux-baud, --rtos-port, --rtos-baud입니다. SERIAL_BRIDGE_CONFIG 또는 --config는 JSON 구성 파일을 선택합니다. 로드 순서는 기본 제공 값, 환경/CLI 값, 저장된 파일 순서입니다. 저장된 파일 값이 우선합니다.

Operator만 포트 바인딩을 편집할 수 있으며, CRT 모드에서만 허브가 포트를 해제한 상태에서 가능합니다. Web UI는 Target별 드롭다운에 감지된 직렬 포트를 나열합니다. 어댑터를 연결한 후 Scan을 사용하여 다시 열거하세요. Web UI에서 변경한 사항은 재시작 후에도 유지됩니다.

라이브 디렉터리

라이브 디렉터리는 허브가 Target별 Bridge 세션 로그와 bridge_status.json을 기록하는 곳입니다. 기본값은 프로젝트 루트 옆의 <app-dir>/live/입니다(serial_bridge.json 및 루트 app.py shim과 같은 디렉터리).

시작 전에 재정의하세요:

$env:SERIAL_BRIDGE_LIVE_DIR = "D:\logs\serial-bridge"
python -m serial_bridge

또는 --live-dir를 전달하세요. 로드 순서는 포트 바인딩과 일치합니다: 기본 제공 값, 환경/CLI 값, 저장된 구성 파일 순서입니다. Web UI 저장이 우선합니다.

Operator가 Bridge 모드에 들어갈 때마다 허브는 <TargetName>-YYYY-MM-DD-HHMMSS.log 형식으로 새 로그 파일을 생성합니다(로컬 시간, 24시간제). 두 번째 Bridge 세션은 새 파일을 생성합니다. 이전 로그는 그대로 유지되며 Live Directory나 Target 이름을 변경해도 이동되지 않습니다.

Live Directory는 CRT 모드에서만 Web UI Bindings 패널에서 편집할 수 있습니다(포트 바인딩과 동일한 루프백 전용 쓰기 경로). 바닥글에는 현재 세션 로그 파일 이름과 함께 구성된 디렉터리가 표시됩니다.

Bridge 모드와 CRT 모드

• Bridge 모드: 허브가 구성된 직렬 포트를 소유합니다. Operator와 Agent는 동일한 라이브 기록을 통해 명령을 보내고 관찰할 수 있습니다.

• CRT 모드: 허브가 포트를 해제하여 SecureCRT 또는 다른 전용 직렬 클라이언트가 사용할 수 있게 합니다. MCP Exec 및 Send는 Operator가 Bridge 모드로 돌아올 때까지 실패합니다.

Bridge 모드로 들어가기 전에 SecureCRT를 연결 해제하세요. CRT 모드로 전환하면 진행 중인 Exec이 중단되고 부분 출력이 반환될 수 있습니다.

원시 전송 경고

raw_hex와 함께 serial_send를 사용하면 텍스트 줄 바꿈이나 자동 줄 끝 없이 임의의 바이트를 기록합니다. 이는 전체 콘솔 권한입니다: 제어 바이트가 부팅을 방해하거나, 프로세스를 종료하거나, 장치 상태를 변경하거나, 세션을 응답 없게 만들 수 있습니다. 명령에는 serial_exec를 선호하고, 정확한 바이트 시퀀스와 장치 영향을 이해하는 경우에만 원시 페이로드를 사용하세요.