MCX - Modular Code Execution

███╗   ███╗ ██████╗██╗  ██╗
████╗ ████║██╔════╝╚██╗██╔╝
██╔████╔██║██║      ╚███╔╝
██║╚██╔╝██║██║      ██╔██╗
██║ ╚═╝ ██║╚██████╗██╔╝ ██╗
╚═╝     ╚═╝ ╚═════╝╚═╝  ╚═╝

AI 에이전트가 도구를 직접 호출하는 대신 코드를 실행할 수 있게 해주는 MCP 서버입니다.

Anthropic의 코드 실행 관련 아티클을 기반으로 합니다.

문제점

기존 MCP에는 두 가지 비효율성이 있습니다:

도구 정의 과부하 - 모든 도구 정의를 로드하면 컨텍스트가 넘쳐납니다.
중간 결과 비대화 - 모든 API 응답이 모델을 거쳐 전달됩니다.

해결책

에이전트는 도구를 직접 호출하는 대신 샌드박스에서 실행되는 코드를 작성합니다:

const invoices = await api.getInvoices({ limit: 100 });
return {
  count: invoices.length,
  total: sum(invoices, 'amount'),
  byStatus: count(invoices, 'status')
};
// Returns ~50 tokens instead of 50,000

결과: 실행 환경 내에서 데이터를 필터링하여 토큰 98% 절감

설치

# Install globally with bun
bun add -g @papicandela/mcx-cli

# Initialize global directory (~/.mcx/)
mcx init

Bun 필요: MCX는 런타임으로 Bun을 사용합니다. 아직 설치하지 않았다면 Bun을 설치하세요.

빠른 시작

# 1. Initialize global MCX directory
mcx init

# 2. Generate adapters from API docs
mcx gen ./api-docs.md -n myapi

# 3. Add credentials to ~/.mcx/.env

# 4. Start server
mcx serve

디렉토리 구조

~/.mcx/
├── adapters/           # Your adapters
│   ├── supabase.ts     # Supabase Management API
│   ├── chrome-devtools.ts  # Chrome DevTools Protocol
│   └── myapi.ts        # Generated from OpenAPI
├── skills/             # Reusable skills
├── mcx.config.ts       # Auto-loads all adapters
├── .env                # API credentials
└── package.json        # Dependencies

# Runtime (created automatically)
~/.mcx/
├── logs/               # Server logs (mcx logs to view)
└── .cache/             # FTS5 search index

Claude Code 통합

Claude Code 설정(~/.claude.json 또는 프로젝트의 .mcp.json)에 추가하세요:

{
  "mcpServers": {
    "mcx": {
      "command": "mcx",
      "args": ["serve"]
    }
  }
}

끝입니다! MCX는 설정 및 어댑터를 위해 자동으로 ~/.mcx/를 사용합니다.

Claude Code 훅 (선택 사항)

더 나은 성능을 위해 기본 도구를 MCX 대안으로 리디렉션하세요:

~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Grep", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Glob", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Write", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Read", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-read-check.js" }] },
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-bash-check.js" }] }
    ]
  }
}

기본 도구	MCX 대안	장점
`Glob`	`mcx_find`	최근 사용 빈도 순위, git 상태, 근접성 향상
`Grep`	`mcx_grep`	SIMD 가속, 퍼지 검색
`Edit`	`mcx_edit`	"먼저 읽기" 요구 사항 없음, CRLF 정규화
`Write`	`mcx_write`	"먼저 읽기" 요구 사항 없음
`Read` (>50KB)	`mcx_file({ storeAs })`	파일이 샌드박스에 유지되어 토큰 99% 절감
`Bash cat/grep/find`	`mcx_file/mcx_grep/mcx_find`	셸 명령을 MCX로 리디렉션

훅 스크립트에 대해서는 훅 통합을 참조하세요.

주요 기능

기능	설명
지연 로딩	`~/.mcx/adapters/`의 어댑터는 시작 시 메타데이터만 스캔되며, 첫 사용 시 완전히 로드됨
도메인 힌트	더 나은 검색 가능성을 위해 어댑터를 도메인별(결제, 데이터베이스, 이메일 등)로 그룹화
자동 수정	`executeSql`을 `execute_sql`로 자동 수정 (camelCase를 snake_case로)
컨텍스트 효율성	필터링은 샌드박스에서 수행되며, 모델은 결과만 확인
변수 지속성	나중에 사용할 수 있도록 결과를 `$invoices`, `$customers`로 저장
자동 압축	오래된 변수(5분 이상, 1KB 이상)는 컨텍스트 절약을 위해 자동 압축
FTS5 검색	대용량 출력 자동 인덱싱, `intent` 매개변수로 검색
FFF 통합	Fast File Finder - SIMD 가속 퍼지 검색, 콘텐츠 grep
백그라운드 작업	장기 실행 작업을 위한 `mcx_spawn`, `mcx_tasks`로 확인
일괄 작업	한 번의 호출로 여러 작업을 수행하는 `mcx_batch`
파일 처리	`$file` 주입을 통해 로컬 파일을 처리하는 `mcx_file`
대용량 파일 처리	50KB 이상의 파일은 `storeAs`를 통해 샌드박스에 유지, 헬퍼로 쿼리
파일 편집	`mcx_edit`(문자열/라인 모드), `mcx_write` - "먼저 읽기" 요구 사항 없음
파일 쿼리 헬퍼	저장된 파일에 대한 `around()`, `lines()`, `block()`, `grep()`, `outline()`
URL 가져오기	HTML-to-markdown 변환을 지원하는 `mcx_fetch` (24시간 TTL 캐시)
제어 흐름	루프, 조건문, 재시도는 네이티브 코드로 실행
개인정보 보호	중간 데이터는 샌드박스 내에 유지
보안	네트워크 격리, 경로 탐색 보호, 환경 변수 주입 방지

MCP 도구

도구	설명
`mcx_execute`	어댑터 접근 권한으로 코드를 실행하고 `$result`로 자동 저장
`mcx_search`	3가지 모드: 사양 탐색, FTS5 검색, 어댑터/메서드 검색
`mcx_batch`	한 번의 호출로 여러 실행/검색 수행 (스로틀링 우회)
`mcx_file`	`$file` 주입으로 로컬 파일 처리 또는 `storeAs`를 사용한 저장 전용 모드
`mcx_edit`	파일 편집 (문자열 또는 라인 모드) - 네이티브 Edit의 읽기 요구 사항 우회
`mcx_write`	파일 생성/덮어쓰기 - 네이티브 Write의 읽기 요구 사항 우회
`mcx_fetch`	HTML-to-markdown 및 자동 인덱싱으로 URL 가져오기 (24시간 캐시)
`mcx_find`	최근 사용 빈도 및 근접성 순위가 포함된 빠른 퍼지 파일 검색
`mcx_grep`	파일 전체에 대한 SIMD 가속 콘텐츠 검색
`mcx_related`	가져오기/내보내기 분석을 통해 관련 파일 찾기
`mcx_tree`	전체 내용을 로드하지 않고 대용량 JSON 결과 탐색
`mcx_spawn`	백그라운드에서 코드 실행, 즉시 작업 ID 반환
`mcx_tasks`	백그라운드 작업 및 결과 목록 확인
`mcx_list`	사용 가능한 어댑터 및 기술 목록 표시
`mcx_stats`	세션 통계 (인덱싱된 콘텐츠, 변수, 네트워크)
`mcx_doctor`	진단 실행 (Bun, SQLite, 어댑터, 샌드박스, FFF)
`mcx_upgrade`	최신 버전으로의 자체 업그레이드 명령 가져오기
`mcx_run_skill`	등록된 기술 실행

CLI 명령

명령	설명
`mcx serve`	MCP 서버 시작 (기본값)
`mcx gen`	OpenAPI 사양에서 어댑터 생성 (TUI 포함)
`mcx init`	전역 `~/.mcx/` 디렉토리 초기화
`mcx update`	CLI 및 전역 설치 업데이트
`mcx list`	사용 가능한 어댑터 및 기술 목록 표시
`mcx run`	기술 직접 실행
`mcx logs`	서버 로그 보기

자세한 내용은 CLI 문서를 참조하세요.

포함된 어댑터

어댑터	메서드	설명
`supabase`	24	Supabase 관리 API (프로젝트, 테이블, 함수, 비밀)
`chrome-devtools`	25	Chrome DevTools 프로토콜 (스크린샷, 탐색, DOM)

OpenAPI 문서에서 직접 어댑터를 생성하세요:

mcx gen ./api-docs.md -n myapi

내장 헬퍼

샌드박스에서 사용할 수 있는 함수:

pick(data, ['id', 'name'])     // Extract fields
first(data, 5)                  // First N items
sum(data, 'amount')             // Sum numeric field
count(data, 'status')           // Count by field
table(data, 10)                 // Markdown table

// Async helpers
await poll(fn, { interval: 2000, maxIterations: 5 })  // Poll until done
await waitFor(fn, { timeout: 30000 })                  // Wait for condition

파일 쿼리 헬퍼

mcx_file({ path, storeAs })를 사용하여 파일을 샌드박스로 로드할 때:

// Load file without returning content to context (99% token savings)
mcx_file({ path: "src/large-file.ts", storeAs: "src" })

// Then query with helpers:
around($src, 150, 10)          // 10 lines around line 150
lines($src, 100, 120)          // Get lines 100-120 (1-indexed, inclusive)
block($src, 150)               // Extract code block by indentation
grep($src, "TODO", 3)          // Search with 3 lines context
outline($src)                  // Extract function/class signatures

문서

CLI 명령 - 상세 명령 참조
어댑터 - 어댑터 생성 및 작성
기술 - 재사용 가능한 작업
구성 - 설정 파일 참조
프로그래밍 API - 코드에서 MCX 사용하기
보안 - 샌드박스 보안 계층

개발

git clone https://github.com/schizoidcock/mcx
cd mcx
bun install
bun run build

라이선스

MIT

MCX (Modular Code Execution)