OMC - MCP Tools Bridge

시리즈: oh-my-claudecode 내부 구조부터 플러그인 개발까지

이 시리즈는 Claude Code 플러그인 시스템의 내부 동작을 단계별로 해부하고, 최종적으로 나만의 플러그인을 직접 개발하는 것까지 도달하는 과정이다.

편	내용	핵심
1편	Plugin Anatomy	plugin.json 하나로 시작하는 플러그인 뼈대
2편	Hook System	이벤트 → stdin JSON → 스크립트 → stdout JSON
3편	Skill System	SKILL.md로 워크플로우를 정의하는 방법
4편	Agent System	Task tool로 위임되는 실제 작업 수행자
5편 (본문)	MCP Tools Bridge	LSP, AST 등 커스텀 도구 서버
6편	State & Lifecycle	.omc/ 상태 관리와 모드 지속
7편	Parallel Orchestration	Ultrawork, Team, Autopilot, Ralph 패턴

---

• MCP Tools Bridge는 Claude Code의 기본 도구로 불가능한 작업을 해결하는 커스텀 도구 서버 시스템
• TypeScript 소스를 esbuild로 번들링해 bridge/mcp-server.cjs로 만들고, .mcp.json에 서버 이름 "t"로 등록하여 모든 도구를 mcp__t__도구이름으로 노출하는 2중 서버 아키텍처
• LSP(IDE 기능 12개), AST(구조 검색 2개), State(상태 5개), Notepad(메모 6개), Memory(지식 4개), Shared Memory(공유 5개), Skills(3개), Trace(3개), Python REPL(1개) 등 총 41개 이상의 전문 도구를 카테고리별로 관리하는 확장 허브

해당 개념이 필요한 이유

• 4편(Agent System)에서 에이전트가 작업 중 타입 체크, 코드 구조 검색, 상태 저장, 메모리 관리가 필요하다는 것까지 학습
• Claude Code의 기본 도구(Read, Write, Bash)만으로는 “이 파일의 타입 에러가 뭐지?”, “이 심볼의 정의는 어디지?” 같은 질문에 효율적으로 답할 수 없음
• MCP Server가 IDE급 기능을 도구로 노출하여 에이전트가 정밀한 작업을 수행할 수 있게 만드는 핵심 인프라

AS-IS

sequenceDiagram
    autonumber
    participant AG as Agent
    participant CC as Claude Code
    participant FS as File System

    AG->>CC: Bash("tsc --noEmit 2>&1")
    CC->>FS: tsc 프로세스 실행
    FS-->>CC: 원시 텍스트 출력 (수백 줄)
    CC-->>AG: 파싱 불가능한 텍스트 덩어리
    Note over AG: 에러 위치·심각도 파싱을<br/>LLM이 직접 해야 함

TO-BE

sequenceDiagram
    autonumber
    participant AG as Agent
    participant CC as Claude Code
    participant MCP as MCP Server "t"
    participant LSP as lsp-tools.ts

    AG->>CC: mcp__t__lsp_diagnostics({ file: "src/main.ts" })
    CC->>MCP: JSON-RPC 요청
    MCP->>LSP: lsp_diagnostics 핸들러
    LSP->>LSP: Language Server 프로토콜 호출
    LSP-->>MCP: 구조화된 에러 목록 (파일, 줄, 심각도)
    MCP-->>CC: JSON-RPC 응답
    CC-->>AG: 즉시 사용 가능한 타입 에러 정보
    Note over AG: 파싱 불필요,<br/>바로 수정 작업 시작

2중 서버 아키텍처

OMC는 동일 계열의 도구를 두 가지 경로로 제공하되, 포함 범위가 다르다.

graph TD
    subgraph "Pattern A: Standalone (플러그인 로드 시)"
        MJ[".mcp.json<br/>서버 이름: t"] -->|"node bridge/mcp-server.cjs"| SS["standalone-server.ts<br/>(raw MCP SDK)"]
        SS -->|"StdioServerTransport"| CC1["Claude Code"]
    end

    subgraph "Pattern B: In-process (서브에이전트용)"
        OTS["omc-tools-server.ts<br/>(Claude Agent SDK)"] -->|"createSdkMcpServer()"| SA["서브에이전트"]
    end

    SS -->|"zodToJsonSchema() 수동 변환"| TOOLS_A["7카테고리 33개 도구"]
    OTS -->|"tool() 헬퍼 자동 변환"| TOOLS_B["10카테고리 41+ 도구"]

구분	Pattern A (Standalone)	Pattern B (In-process)
진입점	bridge/mcp-server.cjs	src/mcp/omc-tools-server.ts
SDK	@modelcontextprotocol/sdk (Server 클래스)	Claude Agent SDK
스키마 변환	zodToJsonSchema() 수동 구현	tool() 헬퍼가 자동 처리
통신	StdioServerTransport (프로세스 간)	인메모리 (같은 프로세스)
도구 범위	LSP, AST, Python, State, Notepad, Memory, Trace (33개)	좌측 전부 + Skills, Shared Memory, Interop (41+개)
비활성화	지원 안 함	parseDisabledGroups()로 카테고리별 비활성화
용도	Claude Code가 플러그인으로 직접 사용	서브에이전트의 allowedTools에 포함

Pattern A에서 Claude Code는 .mcp.json을 읽고 node bridge/mcp-server.cjs를 실행한다. 이 프로세스는 StdioServerTransport를 통해 JSON-RPC 메시지를 주고받으며, Claude Code 입장에서 모든 도구가 mcp__t__도구이름으로 노출된다.

도구 등록 패턴: tagCategory + parseDisabledGroups

등록 흐름

graph LR
    subgraph "1. 도구 정의"
        L["lsp-tools.ts"] --> TC["tagCategory(lspTools, 'lsp')"]
        A["ast-tools.ts"] --> TC2["tagCategory(astTools, 'ast')"]
        S["state-tools.ts"] --> TC3["tagCategory(stateTools, 'state')"]
        N["notepad-tools.ts"] --> TC4["...나머지 카테고리"]
    end

    subgraph "2. 비활성화 필터"
        ENV["OMC_DISABLE_TOOLS=lsp,python-repl"] --> PD["parseDisabledGroups()"]
        PD --> FILTER["allTools.filter(t => !disabled.has(t.category))"]
    end

    TC --> AT["allTools 배열"]
    TC2 --> AT
    TC3 --> AT
    TC4 --> AT
    AT --> FILTER
    FILTER --> SDK["enabledTools → createSdkMcpServer()"]

비활성화 매핑

OMC_DISABLE_TOOLS=lsp,python-repl,project-memory

환경변수 값	비활성화 카테고리
lsp	LSP 12개 도구 전체
ast	AST 2개 도구
python 또는 python-repl	Python REPL 1개
state	State 5개 도구
notepad	Notepad 6개 도구
memory 또는 project-memory	Memory 4개 도구
skills	Skills 3개 도구
trace	Trace 3개 도구
shared-memory	Shared Memory 5개 도구
interop	Interop 도구 (조건부)

파싱은 서버 시작 시 1회만 수행. 런타임 중 동적 활성화/비활성화는 불가하며 서버 재시작 필요.

카테고리별 도구 상세

LSP Tools (12개) — IDE급 코드 분석

LSP (Language Server Protocol)을 통해 실제 언어 서버(TypeScript, Python 등)에 질의하여 정확한 타입 정보와 코드 분석 결과를 반환한다.

모든 LSP 도구는 withLspClient(filePath, operationName, fn) 헬퍼를 사용한다:

1. 파일 확장자로 적합한 Language Server 탐색
2. lspClientManager.runWithClientLease()로 LSP 클라이언트 획득/생성
3. 서버 미설치 시 설치 안내와 함께 에러 반환

도구	파라미터	역할
lsp_hover	file, line, character	심볼의 타입 정보/문서 반환
lsp_goto_definition	file, line, character	심볼 정의 위치 (파일 경로 + 줄)
lsp_find_references	file, line, character, includeDeclaration?	심볼이 사용된 모든 위치
lsp_document_symbols	file	파일 내 심볼 계층 목록
lsp_workspace_symbols	query, file	워크스페이스 전체 심볼 검색
lsp_diagnostics	file, severity?	파일 단위 에러/경고 목록
lsp_diagnostics_directory	directory, strategy?	프로젝트 단위 진단 (tsc/lsp/auto)
lsp_servers	(없음)	설치된 Language Server 상태
lsp_prepare_rename	file, line, character	리네임 가능 여부 확인
lsp_rename	file, line, character, newName	리네임 미리보기 (적용하지 않음)
lsp_code_actions	file, startLine, startChar, endLine, endChar	리팩토링 제안 목록
lsp_code_action_resolve	위 + actionIndex	특정 액션의 편집 상세

AST Tools (2개) — 구조적 코드 검색/변환

@ast-grep/napi 네이티브 모듈을 사용한다. 정규식 기반 검색과 달리 AST 패턴 매칭으로 구문 구조를 정확히 파악한다.

도구	파라미터	역할
ast_grep_search	pattern, language, path?, context?(0-10줄), maxResults?(1-100)	AST 패턴 코드 검색
ast_grep_replace	pattern, replacement, language, path?, dryRun?(기본 true)	AST 패턴 코드 변환

패턴 문법: $NAME(단일 노드), $$$ARGS(다중 노드) 예시: console.log($MSG) → 모든 console.log 호출 매칭

지원 언어: javascript, typescript, tsx, python, ruby, go, rust, java, kotlin, swift, c, cpp, csharp, html, css, json, yaml

State Tools (5개) — 모드 상태 관리

.omc/state/ 디렉토리에 JSON 파일로 모드 상태를 관리한다. session_id 파라미터로 세션별 격리를 지원하며, 미지정 시 레거시 공유 경로를 사용한다(교차 오염 경고 발생).

지원 모드: autopilot, team, ralph, ultrawork, ultraqa, ralplan, omc-teams, deep-interview

도구	핵심 동작
state_read	모드 상태 JSON 읽기
state_write	상태 기록 (atomicWriteJsonSync 사용, _meta 자동 추가)
state_clear	상태 삭제 (team 모드는 런타임 상태 + HUD도 정리)
state_list_active	현재 활성 모드 목록
state_get_status	특정 모드의 상세 상태

state_write는 atomicWriteJsonSync()로 원자적 쓰기를 보장하여 동시 접근 시 부분 쓰기를 방지한다.

Notepad Tools (6개) — 세션 간 구조화 메모리

.omc/notepad.md에 3개 섹션으로 구분된 메모리를 관리한다.

도구	섹션	특성
notepad_write_priority	Priority Context	교체(REPLACE) 방식, 항상 세션 시작 시 로드, 500자 이내 권장
notepad_write_working	Working Memory	추가(APPEND) 방식, 타임스탬프 포함, 7일 후 자동 정리
notepad_write_manual	Manual	추가 방식, 자동 정리 없음
notepad_read	선택 가능	all/priority/working/manual 중 택
notepad_prune	Working Memory	오래된 항목 정리 (기본 7일)
notepad_stats	전체	크기, 항목 수, 최고령 항목, 경로

Memory Tools (4개) — 프로젝트 지식 저장소

.omc/project-memory.json에 구조화된 프로젝트 정보를 관리한다.

섹션: techStack, build, conventions, structure, customNotes, userDirectives

도구	역할
project_memory_read	프로젝트 환경 정보 읽기 (섹션 선택 가능)
project_memory_write	프로젝트 지식 기록 (merge 모드 지원)
project_memory_add_note	카테고리별 커스텀 노트 추가
project_memory_add_directive	사용자 지시사항 추가 (컨텍스트 압축에서 살아남음)

Shared Memory Tools (5개) — 에이전트 간 공유 저장소

.omc/state/shared-memory/{namespace}/{key}.json에 키-밸류 형태로 에이전트 간 데이터를 공유한다. ~/.claude/.omc-config.json의 agents.sharedMemory.enabled로 게이트됨.

도구	역할
shared_memory_write	키-밸류 저장 (TTL 지원, 최대 7일)
shared_memory_read	키-밸류 읽기 (만료 자동 감지)
shared_memory_list	네임스페이스 내 키 목록 또는 전체 네임스페이스 목록
shared_memory_delete	키 삭제
shared_memory_cleanup	만료된 항목 일괄 정리

나머지 도구

카테고리	도구 수	역할
Skills Tools	3개	.omc/skills/(프로젝트) + ~/.omc/skills/(글로벌) 스킬 탐색·목록
Trace Tools	3개	.omc/state/agent-replay-*.jsonl 세션 리플레이 타임라인·요약·검색
Python REPL	1개	Python 코드 실행

Bridge 빌드 파이프라인

빌드 흐름

graph TD
    subgraph "TypeScript 소스"
        S1["src/mcp/standalone-server.ts"]
        S2["src/mcp/omc-tools-server.ts"]
        S3["src/team/bridge-entry.ts"]
    end

    subgraph "빌드 스크립트"
        B1["scripts/build-mcp-server.mjs"]
        B2["scripts/build-bridge-entry.mjs"]
        B3["scripts/build-skill-bridge.mjs"]
    end

    subgraph "bridge/ 산출물"
        O1["mcp-server.cjs<br/>~25,000줄 CJS 번들"]
        O2["team-bridge.cjs"]
        O3["skill-bridge 관련"]
    end

    S1 -->|"esbuild"| B1 --> O1
    S3 -->|"esbuild"| B2 --> O2
    B3 --> O3

    style S2 fill:#ffd,stroke:#aa0
    S2 -.->|"번들링 안 됨<br/>(In-process 전용)"| SA["서브에이전트에서<br/>직접 import"]

esbuild 설정 핵심

esbuild.build({
  entryPoints: ['src/mcp/standalone-server.ts'],
  bundle: true,
  platform: 'node',
  target: 'node18',
  format: 'cjs',
  outfile: 'bridge/mcp-server.cjs',
  external: [
    'fs', 'path', 'os', /* ...Node.js 빌트인 */
    '@ast-grep/napi',    // 네이티브 애드온 → 번들 불가
    'better-sqlite3'     // 네이티브 애드온 → 번들 불가
  ],
  banner: { js: '<NODE_PATH 해석기 프리앰블>' }
});

NODE_PATH 프리앰블

bridge/mcp-server.cjs 최상단에 삽입되는 코드:

try {
  var _globalRoot = require('child_process')
    .execSync('npm root -g', { encoding: 'utf8' }).trim();
  process.env.NODE_PATH = _globalRoot + ':' + process.env.NODE_PATH;
  require('module')._initPaths();
} catch (_e) { /* graceful degrade */ }

외부화된 @ast-grep/napi, better-sqlite3 같은 네이티브 모듈을 런타임에 글로벌 npm 경로에서 찾을 수 있게 하는 트릭이다.

Graceful Shutdown

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));

종료 시 disconnectAll()을 호출한다. 이 함수는 내부적으로 lspClientManager.disconnectAll()을 실행하여 LSP 자식 프로세스를 정리하고 고아 프로세스를 방지한다.

나만의 MCP 도구를 추가한다면

// src/tools/my-tools.ts
import { z } from 'zod';
 
export const myTools = [
  {
    name: 'my_custom_tool',
    description: 'My custom tool description',
    schema: z.object({ input: z.string() }),
    handler: async (args: { input: string }) => ({
      content: [{ type: 'text' as const, text: `Result: ${args.input}` }]
    })
  }
];

// omc-tools-server.ts에 등록
const allTools = [
  ...tagCategory(myTools, 'my-category'),
  // ...기존 도구들
];

npm run build 후 mcp__t__my_custom_tool로 호출 가능.

참고 문서

• MCP (Model Context Protocol) 공식 문서
• Claude Agent SDK - createSdkMcpServer
• 소스: ~/Documents/study/oh-my-claudecode/src/mcp/omc-tools-server.ts
• 소스: ~/Documents/study/oh-my-claudecode/src/mcp/standalone-server.ts