OMX - MCP Servers

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편	Skill System	워크플로우를 어떻게 정의하나
4편	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편 (본문)	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편	State & Lifecycle	상태를 어떻게 유지하나
7편	Team Orchestration	Team 모드는 어떻게 동작하나
8편	Native & Spark	Rust 네이티브 도구는 뭔가

---

• OMX MCP Servers는 에이전트에게 상태 저장·메모리·코드 인텔리전스·실행 추적·팀 조율 기능을 제공하는 5개 분리된 MCP 서버 세트
• config.toml의 [mcp_servers] 섹션으로 등록되며, 세션 시작 시 stdio 기반으로 자동 시작되는 Node.js 프로세스
• OMC의 1개 통합 서버(“t”, 30+ 도구)와 달리, 관심사별로 5개 서버를 분리하여 독립적으로 활성화/비활성화할 수 있는 구조

해당 개념이 필요한 이유

• 4편에서 에이전트의 정의와 라우팅을 이해했음
• 하지만 에이전트가 작업 중에 상태 저장, 메모리 관리, 코드 분석, 실행 추적이 필요하며, Codex CLI 기본 도구로는 이런 작업이 비효율적이거나 불가능
• OMX는 5개 MCP 서버를 제공하여 이 간극을 메움 — 3-Plane 아키텍처의 State Plane에 해당

AS-IS (OMC — 1개 통합 MCP 서버)

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant T as MCP 서버 "t" (통합)
    participant FS as 파일시스템

    CC->>T: mcp__t__state_write(...)
    CC->>T: mcp__t__lsp_diagnostics(...)
    CC->>T: mcp__t__notepad_write(...)
    T->>FS: 모든 도구가 1개 프로세스에서 처리
    Note over T: 30+ 도구, 단일 프로세스<br/>esbuild → bridge/mcp-server.cjs

TO-BE (OMX — 5개 분리 MCP 서버)

sequenceDiagram
    autonumber
    participant CX as Codex CLI (LLM)
    participant ST as omx_state
    participant MM as omx_memory
    participant CI as omx_code_intel
    participant TR as omx_trace
    participant TM as omx_team_run

    CX->>ST: state_write(mode: "ralph", ...)
    CX->>MM: project_memory_read(section: "techStack")
    CX->>CI: lsp_diagnostics(file: "src/main.ts")
    CX->>TR: trace_timeline(last: 10)
    CX->>TM: omx_run_team_start(...)
    Note over ST,TM: 관심사별 분리, 개별 비활성화 가능<br/>tsc → dist/mcp/*.js (stdio)

MCP 서버 등록과 부트스트래핑

config.toml 등록 (소스: src/config/generator.ts)

omx setup 시 buildMergedConfig()가 5개 서버를 config.toml에 등록한다.

[mcp_servers.omx_state]
command = "node"
args = ["/path/to/dist/mcp/state-server.js"]
enabled = true
startup_timeout_sec = 5
 
[mcp_servers.omx_code_intel]
command = "node"
args = ["/path/to/dist/mcp/code-intel-server.js"]
enabled = true
startup_timeout_sec = 10   # 가장 긴 timeout

서버	등록 이름	소스	startup timeout
State	omx_state	dist/mcp/state-server.js	5초
Memory	omx_memory	dist/mcp/memory-server.js	5초
Code Intel	omx_code_intel	dist/mcp/code-intel-server.js	10초
Trace	omx_trace	dist/mcp/trace-server.js	5초
Team	omx_team_run	dist/mcp/team-server.js	5초

자동 시작과 비활성화 (소스: src/mcp/bootstrap.ts)

각 서버는 autoStartStdioMcpServer()로 stdio 기반 부트스트래핑된다. 환경변수로 개별 또는 전체 비활성화 가능하다.

환경변수	대상
OMX_MCP_SERVER_DISABLE_AUTO_START=1	전체 5개 서버 비활성화
OMX_STATE_SERVER_DISABLE_AUTO_START=1	state 서버만
OMX_MEMORY_SERVER_DISABLE_AUTO_START=1	memory 서버만
OMX_CODE_INTEL_SERVER_DISABLE_AUTO_START=1	code-intel 서버만
OMX_TRACE_SERVER_DISABLE_AUTO_START=1	trace 서버만
OMX_TEAM_SERVER_DISABLE_AUTO_START=1	team 서버만

빌드 프로세스

src/mcp/*.ts  →  tsc (TypeScript 컴파일)  →  dist/mcp/*.js

OMC는 esbuild → bridge/mcp-server.cjs 단일 번들이었지만, OMX는 tsc로 각 서버를 개별 JS 파일로 컴파일한다. 서버별 독립 실행이 가능한 구조다.

omx_state — 워크플로우 상태 관리 (5개 도구)

도구 목록

도구	역할	필수 파라미터
state_read	모드별 상태 읽기	mode
state_write	모드별 상태 쓰기/업데이트	mode
state_clear	모드별 상태 삭제	mode
state_list_active	현재 활성 모드 목록	(없음)
state_get_status	모드별 상세 상태 조회	(없음, mode는 선택)

지원 모드 (6개)

const SUPPORTED_MODES = [
  "autopilot", "team", "ralph", "ultrawork", "ultraqa", "ralplan"
] as const;

state_write 상세 — 핵심 도구

state_write({
  mode: "ralph",           // 필수: 6개 모드 중 하나
  active: true,            // 활성 상태
  iteration: 1,            // 현재 반복 횟수
  max_iterations: 10,      // 최대 반복
  current_phase: "executing",  // 현재 단계
  task_description: "refactor API",
  started_at: "2026-03-19T...",
  state: { ... }           // 추가 커스텀 필드
})

동작 방식:

• 기존 상태와 deep merge (기존 필드 보존)
• Atomic write: 임시 파일 생성 → rename (데이터 손실 방지)
• Write-lock queue: 동일 파일에 대한 동시 쓰기를 Promise 체인으로 직렬화
• Ralph 모드는 validateAndNormalizeRalphState()로 phase를 추가 검증

상태 파일 저장 구조

.omx/state/
├── {mode}-state.json              # Root scope (글로벌)
├── session.json                   # 현재 세션 마커
└── sessions/
    ├── {sessionId1}/
    │   └── {mode}-state.json      # 세션 스코프
    └── {sessionId2}/
        └── {mode}-state.json

스코프 우선순위 (소스: src/mcp/state-paths.ts)

읽기 시 (state_read):

1. 명시적 session_id 제공 → 해당 세션 경로만
2. 현재 세션 존재 (session.json) → 세션 우선, root 폴백
3. 세션 없음 → root만

쓰기 시 (state_write):

• 항상 effective scope에 기록 (명시 > 현재 세션 > root)

omx_memory — 프로젝트 메모리와 노트패드 (8개 도구)

Project Memory (4개 도구) — .omx/project-memory.json

도구	역할
project_memory_read	전체 또는 섹션별 읽기 (techStack, build, conventions, structure, notes, directives)
project_memory_write	전체 교체 또는 deep merge
project_memory_add_note	타임스탬프 메모 추가 (카테고리: build/test/deploy/env/architecture)
project_memory_add_directive	우선순위 지시 추가 (high/normal)

크로스 세션 동작: 프로젝트당 1개 파일, 세션 스코핑 없음 — 모든 세션이 같은 메모리를 공유한다.

interface ProjectMemory {
  techStack?: string;
  build?: string;
  conventions?: string;
  structure?: string;
  notes?: Array<{ category: string; content: string; timestamp: string }>;
  directives?: Array<{ directive: string; priority: string; timestamp: string }>;
}

Notepad (4개 도구) — .omx/notepad.md

마크다운 기반 세션 노트로, 3개 섹션으로 구분된다.

도구	대상 섹션	동작
notepad_read	전체 또는 섹션별	읽기
notepad_write_priority	## PRIORITY	교체 (단일 컨텍스트 블록, 최대 500자)
notepad_write_working	## WORKING MEMORY	추가 (타임스탬프 엔트리, 자동 정리 대상)
notepad_write_manual	## MANUAL	추가 (영구 보존, 자동 정리 안 됨)

추가 유틸리티: notepad_prune (N일 이전 WORKING MEMORY 정리, 기본 7일), notepad_stats (통계)

## PRIORITY
현재 최우선 컨텍스트 (세션마다 교체됨)
 
## WORKING MEMORY
[2026-03-19T10:00:00Z] API 리팩터 진행 중
[2026-03-19T11:30:00Z] 테스트 통과 확인
 
## MANUAL
프로젝트별 영구 메모 (자동 정리 안 됨)

omx_code_intel — 코드 인텔리전스 (9개 도구)

Codex CLI에는 Claude Code 같은 빌트인 LSP 도구가 없다. OMX는 CLI 도구(tsc, ast-grep, grep)를 래핑하여 실용적 코드 인텔리전스를 제공한다.

도구 분류

카테고리	도구	구현 방식
진단	lsp_diagnostics	tsc --noEmit 실행 → 파일별 필터링
진단	lsp_diagnostics_directory	프로젝트 전체 타입 체크 → 파일별 그룹핑
심볼 검색	lsp_document_symbols	Regex 기반 추출 (15+ 언어 지원)
심볼 검색	lsp_workspace_symbols	워크스페이스 전체 심볼 검색 (6단계 깊이, 최대 50개)
심볼 검색	lsp_hover	위치 기반 단어 추출 + 로컬 정의 찾기
참조	lsp_find_references	grep -rn -w로 심볼 참조 찾기
서버 상태	lsp_servers	tsc, ast-grep, grep 가용성 확인
AST	ast_grep_search	ast-grep CLI 패턴 매칭 ($NAME, $$$ARGS 메타변수)
AST	ast_grep_replace	AST 기반 코드 치환 (기본 dry-run)

OMC LSP 도구와의 비교

항목	OMC	OMX
구현 방식	Claude Code 빌트인 LSP 도구	CLI 도구 래핑 (tsc, ast-grep, grep)
LSP 프로토콜	진정한 LSP 프로토콜 사용	미사용 — CLI 출력 파싱
진단	lsp_diagnostics (빌트인)	tsc --noEmit → JSON 파싱
심볼	lsp_document_symbols (LSP)	Regex 기반 추출
hover	lsp_hover (LSP)	Regex 기반 근사치
AST	ast_grep_search/replace (빌트인)	ast-grep CLI 래핑
언어 지원	LSP 서버 의존	TS, Python, Go, Rust 등 15+ (regex 패턴)

omx_trace — 실행 추적 (2개 도구)

도구

도구	역할	주요 파라미터
trace_timeline	시간순 에이전트 활동 타임라인	last (최근 N개), filter (all/turns/modes)
trace_summary	집계 통계 (턴 수, 모드 사용량, 토큰 소비)	(없음)

데이터 소스

graph LR
    subgraph 현재세션["현재 세션 데이터"]
        TL[".omx/logs/turns-*.jsonl"]
        MS[".omx/state/{mode}-state.json"]
        MT[".omx/metrics.json"]
    end

    subgraph 히스토리["세션 히스토리 (별도 모듈)"]
        RL[".codex/sessions/rollout-*.jsonl"]
    end

    TL --> TT["trace_timeline"]
    MS --> TT
    MT --> TS["trace_summary"]
    TL --> TS

    RL --> SH["session-history/search.ts<br/>(searchSessionHistory)"]

    style TT fill:#e8f0fe
    style TS fill:#e8f0fe
    style SH fill:#fef7e0

• trace_timeline/summary: 현재 세션의 .omx/logs/ 로그 + 모드 상태 + 메트릭스
• session-history: 과거 세션의 .codex/sessions/rollout-*.jsonl 검색 (trace 서버와 독립)

omx_team_run — Team 조율 (4개 도구 + deprecated)

현존 도구 (4개)

도구	역할
omx_run_team_start	tmux worker 스폰 (codex/claude/gemini), jobId 즉시 반환
omx_run_team_status	논블로킹 상태 확인
omx_run_team_wait	블로킹 폴링 + 자동 nudge + 이벤트 모드
omx_run_team_cleanup	worker pane 정리 (leader/HUD 보존)

Deprecated 도구 — CLI 선호 이유

20+ 팀 조작 도구(team_send_message, team_broadcast, team_create_task 등)가 hard-deprecated 되었다. 호출 시 code: "deprecated_cli_only" 에러와 함께 CLI 대안 힌트를 반환한다.

Deprecation 이유:

• MCP 프로토콜의 상태비저장 특성 — team의 tmux 세션/런타임 생명주기와 호환 불가
• CLI 인터옵 필요 — tmux 세션 관리, 런타임 상태 업데이트에 CLI 컨텍스트 필수
• 대안: omx team api ... CLI 명령으로 동일 기능 수행

MCP workingDirectory Hardening — 보안

경로 검증 다계층 (소스: src/mcp/state-paths.ts)

계층	검증 내용
NUL 바이트	\0 포함 시 거부
Path Traversal	.. 시퀀스 차단
Mode Segment	^[A-Za-z0-9_-]{1,64}$ 패턴 강제 (경로 구분자 불허)
Session ID	^[A-Za-z0-9_-]{1,64}$ 패턴 강제
Allowlist	OMX_MCP_WORKDIR_ROOTS 설정 시 허용 루트 외 거부

OMX_MCP_WORKDIR_ROOTS — 디렉토리 샌드박싱

# Unix: 콜론 구분
export OMX_MCP_WORKDIR_ROOTS="/home/user/projects:/tmp/sandbox"
 
# Windows: 세미콜론 구분
set OMX_MCP_WORKDIR_ROOTS="C:\projects;D:\sandbox"

설정 시 MCP 서버가 허용된 루트 하위 디렉토리에서만 동작한다. isWithinRoot() 함수가 상대 경로 계산으로 탈출 여부를 검증한다.

OMC MCP와의 전체 비교

항목	OMC	OMX
서버 수	1개 “t” (통합)	5개 (관심사 분리)
등록 방식	.mcp.json	config.toml
빌드 방식	esbuild → 단일 .cjs	tsc → 개별 .js
총 도구 수	30+	28개 (state 5 + memory 8 + code-intel 9 + trace 2 + team 4)
비활성화	불가 (서버 통합)	개별/전체 환경변수
LSP 구현	Claude Code 빌트인	CLI 래핑 (tsc, ast-grep, grep)
상태 스코핑	단일 scope	세션 스코프 (session.json 기반)
크로스 세션	notepad + project-memory	project-memory.json + notepad.md (구조 동일)
보안	없음	workdir allowlist + path validation

참고 문서

• OMX GitHub
• MCP Specification