2026-10-02
Grok Bot을 Codex에 연결하기 ② — 실제 구현과 77개 테스트
Node.js stdio 서버의 모듈 구조, 읽기·쓰기 권한, 접수와 완료의 구분을 설명하고 초기 실서버 검증과 2026년 10월 2일 회귀 테스트 결과를 분리해 기록했다.
1편: Windows MCP 제작 계획에서 정한 범위를 실제 Node.js 서버로 옮겼다. 결과물은 설치된 Windows Grok Bot의 현재 계정을 사용하는 로컬 stdio MCP다. 자체 로그인 서비스나 원격 웹 서버는 만들지 않았다.
이 글에서는 코드로 확인한 동작, 초기 실서버 검증 기록, 이번 재실행 결과를 구분한다. 2026년 10월 2일 글을 준비하면서 실행한 것은 실제 계정과 네트워크를 사용하지 않는 회귀 테스트다.
구현 환경과 모듈 구조
초기 호환성 대상은 Windows의 Grok Bot 0.56.1이었다. 프로젝트는 Node.js 22 이상을 요구하며, 초기 검증과 이번 회귀 테스트 모두 Node.js 24.14.0에서 수행했다. 외부 npm 의존성은 없다.
참고한 원본 저장소의 도구 구성을 바탕으로 Windows용 인증 접근과 통신·검증 계층을 분리했다.
| 모듈 | 역할 |
|---|---|
server.mjs |
실행 진입점과 진단 모드 |
src/native-auth.mjs |
기존 앱의 현재 인증 상태를 읽는 Windows 전용 어댑터 |
src/gateway.mjs |
Gateway 목적지 검사와 요청·응답 처리 |
src/backend.mjs |
서비스 Backend의 허용된 호출 처리 |
src/tools.mjs |
11개 도구의 스키마, 입력 검사, 읽기·쓰기 정책 |
src/mcp.mjs |
초기화, 도구 목록, 호출, 취소와 stdio 처리 |
src/errors.mjs |
외부에 반환해도 되는 오류 형태 정리 |
위 파일명은 이번 구현의 구조이지, 원본 저장소와 파일별로 동일하다는 뜻은 아니다. 설치된 앱 번들이나 실제 인증 자료를 프로젝트에 포함하지 않는다.
Windows 인증 어댑터의 역할을 좁혔다
인증 어댑터는 기존 앱의 현재 계정과 연결 상태를 요청 시 다시 읽는다. 필요한 인증 정보는 같은 Windows 사용자 환경에서 메모리 안에서 처리하며, 별도의 인증 저장소를 만들지 않는다. 이 글에는 토큰 추출 절차나 복호화 코드를 싣지 않는다.
구현의 중요한 성질은 다음과 같다.
- 자체 OAuth 로그인과 refresh token 사용·갱신을 하지 않는다.
- 기존 앱의 인증 파일을 수정하지 않는다.
- 앱이 로그아웃된 상태에서 다른 저장 계정을 임의로 선택하지 않는다.
- 확인 도중 계정이 달라지면 요청을 중단한다.
- 만료·형식 불일치·연결 정보 오류를 구분해 반환한다.
- 진단 결과에 토큰이나 계정 식별자를 노출하지 않는다.
인증이 만료되면 기존 앱에서 로그인과 연결을 갱신해야 한다. 이 제약은 누락된 자동화가 아니라, 인증 갱신의 책임을 두 프로그램이 동시에 갖지 않도록 한 선택이다.
하나의 API로 모든 일을 처리하지 않는다
도구마다 실제 통신 계층이 다르다. 봇 목록과 대화 조회는 Gateway를 사용하고, 메시지 전송·접수 상태·사용량 등은 Backend를 사용한다. 봇 생성은 선택한 실행 방식에 따라 경로가 갈린다.
따라서 “앱 인증을 가져와서 API 하나를 호출한다”는 설명만으로는 부족했다. 각 도구가 어떤 서비스에 어떤 결과를 기대하는지 명시해야 했다.
네트워크 구현에는 목적지와 메서드 제한, 리디렉션 거부, 응답 크기 제한을 넣었다. 도구 인자에서 임의 URL이나 임의 서버 메서드를 받을 수 있는 범용 프록시로 만들지 않았다.
이 제한은 허용된 서비스와 통신 범위를 좁히는 장치다. 사용자 계정 자체의 권한이나 원격 서비스의 신뢰성을 보증하는 것은 아니다.
도구 11개, 관찰 모드에서는 7개
| 분류 | 도구 |
|---|---|
| 읽기 | connection_status, list_bots, search_bots, get_send_status, get_transcript, search_messages, check_usage |
| 쓰기 | create_bot, send_message, delete_bot, interrupt_bot |
GROK_BOT_READ_ONLY=1이면 읽기 도구 7개만 목록에 노출한다. 숨긴 쓰기 도구 이름을 직접 호출하더라도 서버에서 거절한다. 도구 설명에 읽기 전용이라고 표시하는 것과 실제 실행 경로에서 차단하는 것을 함께 구현했다.
중요하게도 기본값은 전체 도구를 제공하는 모드다. 관찰만 하고 싶다면 읽기 전용 모드를 명시해야 한다.
삭제는 대상 하나와 명시적인 확인값을 요구한다. 메시지 전송은 대상 봇이 가진 권한으로 후속 작업을 일으킬 수 있고, 중단 요청도 이미 실행된 행동을 되돌리지는 않는다.
접수와 완료를 응답에서 분리했다
메시지 전송이 받아들여졌을 때의 핵심 필드는 다음과 같다. 아래는 의미를 보여주는 예시이며 실제 계정의 응답 원문이 아니다.
{
"accepted": true,
"replyComplete": false
}
전송 결과에는 요청을 식별하는 clientNonce도 포함한다. 접수 여부가 불확실하면 이 값으로 상태를 확인하고, 실제 답변은 대화 조회로 확인한다.
쓰기는 자동 재시도하지 않는다. 네트워크 timeout은 원격 작업 실패의 증거가 아닐 수 있기 때문이다. 같은 요청이 이미 반영됐는지 확인하지 않고 반복하면 메시지나 작업을 중복시킬 수 있다.
또한 clientNonce가 있다는 사실을 완전한 exactly-once 실행 보장으로 설명하지 않는다. 이 서버에는 영구 중복 방지 저장소가 없고, 원격 서비스의 동작까지 자체적으로 보장하지도 않는다.
stdio도 테스트 대상이다
이 서버는 호스트가 실행하는 Node.js 프로세스다. 직접 터미널에서 계속 켜두지 않아도 되지만 Node.js가 없어도 실행되는 것은 아니다. 현재 구현은 HTTP 수신 포트를 열지 않는다.
표준출력은 MCP 응답 전용으로 유지한다. 일반 로그가 섞이면 메시지 해석이 깨질 수 있으므로, “함수가 성공했는가” 외에 실제 자식 프로세스의 입출력도 검사했다.
검사 항목에는 초기화 전 호출 거부, 프로토콜 버전 협상, 요청 ID 보존, 취소 전달, 동시 실행 제한, 잘못된 JSON, 분할된 UTF-8 입력과 과도하게 큰 입력 이후의 복구가 포함된다.
대화 조회에도 범위를 표시했다. 페이지 크기는 기본 50개·최대 200개이고, search_messages는 한 페이지 안에서 수행하는 문자열 검색이다. 이를 모든 봇의 전체 대화 검색으로 설명하지 않는다.
실제로 확인한 테스트 결과
| 시점·종류 | 결과 | 의미와 한계 |
|---|---|---|
| 2026-09-19 초기 단위·회귀 검사 | 77개 통과 | 가짜 인증과 모의 응답 기반 |
| 같은 날짜 초기 읽기 실서버 검사 | MCP 초기화 및 읽기 도구 7종 통과 | 당시 환경에서의 연결 확인 |
| 초기 실서버 검사 전후 비교 | 대상 인증 파일 3개의 해시 동일 | 그 검사 동안 파일 내용이 바뀌지 않았다는 기록 |
| 초기 생성·전송·삭제·중단 검사 | 모의 응답 기반 검증 | 실제 봇을 바꾸는 전체 종단 간 검사와는 다름 |
| 2026-10-02 회귀 검사 재실행 | 77개 통과, 실패·취소·건너뜀 0개 | 이번 글 작성 중 직접 재실행한 결과 |
이번 재실행 명령은 다음과 같다.
node --test --test-reporter=spec test/*.test.mjs
테스트는 임시 fixture와 가짜 자격 증명을 사용한다. 실제 Grok Bot 계정 조회, 토큰 갱신, 메시지 전송은 이번 재실행에 포함하지 않았다.
테스트의 초점은 정상 응답만이 아니었다. 로그아웃 후 다른 계정으로 대체하지 않는지, 만료된 인증에서 멈추는지, 실패한 쓰기를 다시 보내지 않는지, 서버 오류 본문에 민감 정보가 있어도 그대로 반환하지 않는지를 함께 확인했다.
초기 실서버 결과는 프로젝트 README에 남아 있는 당시 기록이다. 오늘 같은 서비스를 다시 호출한 결과나 모든 향후 버전의 호환성으로 확대 해석하면 안 된다.
구현 완료와 운영 검증 완료는 다르다
초기 검증 뒤에는 별도의 사용자 요청으로 실제 메시지를 보내고 응답을 확인하는 실험도 했다. 그 경험은 다음 편에서 다룬다. 그것이 봇 생성·삭제·중단까지 모두 실서버에서 검증했다는 뜻은 아니다.
남아 있는 검증 항목은 장시간 사용 중의 실제 인증 갱신, 앱 업데이트 이후의 호환성, 계정 전환과 요청이 겹치는 실제 환경, 장기 부하다. 비공식 내부 API 연동이므로 버전 변경에 따른 유지보수도 필요하다.
이 버전에서 완성한 것은 로컬 MCP 브리지와 그 경계에 대한 테스트다. 독립 실행 대시보드나 Sites 배포까지 완성한 것으로 묶지 않는다.
기록과 출처
- 직접 확인: 현재 프로젝트의 소스, 테스트, README와 NOTICE.
- 이번 재실행: 2026-10-02, Windows / Node.js 24.14.0, 77개 테스트 통과.
- 초기 실서버 결과: README의 2026-09-19 검증 기록.
- 참고 구현: 원본 고정 커밋, MIT. 이번 글은 Windows용 별도 구현을 설명한다.