격차 해소하기: 로컬 AI 에이전트를 A-Modular-Kingdom MCP 서버에 자동으로 연결하기

Model Context Protocol (MCP)는 우리가 AI 지원 개발 도구를 구축하는 방식을 변화시켰습니다. 이는 로컬 코딩 에이전트(Codex, Claude Code 또는 Cursor와 같은)가 지식 베이스를 원활하게 쿼리하고, 코드를 실행하며, 지속적인 메모리(persistent memory)를 검색할 수 있도록 해줍니다.

하지만, 이를 설정하는 과정은 개발자 경험 측면에서 마찰이 많을 수 있습니다:

1. 설정 체조 (Config gymnastics): 에이전트 설정 파일(예: ~/.codex/config.toml 또는 CLI 명령 구성)을 수동으로 편집하는 것은 지루하고 오류가 발생하기 쉽습니다.
2. 경로 문제 (Path issues): 서로 다른 시스템에서의 절대 경로(Absolute paths)는 설정 파일을 쉽게 깨뜨립니다.
3. 자원 고갈 (Resource exhaustion): 무거운 RAG 파이프라인을 실행하면 과도한 CPU를 소모하여 시스템 저하나 높은 배터리 소모를 유발할 수 있습니다.

이를 해결하기 위해, 저는 저의 플래그십 프로젝트인 **A-Modular-Kingdom (AMK)**에 **로컬 설정 하네스 (local setup harness)**를 추가했습니다. 이 하네스는 열 모니터링(thermal monitoring) 기능이 내장된 상태로, 로컬 에이전트가 AMK 서버와 통신할 수 있도록 자동으로 구성하는 브리지 역할을 합니다.

해결책: 자동화된 MCP 하네스 설정

개발자가 설정 블록을 복사하여 붙여넣도록 요구하는 대신, 이제 리포지토리에 단일 부트스트랩 스크립트가 포함되어 있습니다:

./scripts/setup_mcp.sh

이 스크립트는 내부적으로 두 가지 통합을 자동화합니다:

1. Codex 통합

이 스크립트는 ~/.codex/config.toml에 Codex 설정이 있는지 확인하는 Python 등록 스크립트(scripts/register_mcp.py)를 실행합니다. 이는 modular_kingdom_host를 자동으로 등록하고 구성하며, 경로를 로컬 클론에 동적으로 매핑하여 다음과 같은 설정을 추가합니다:

[mcp_servers.modular_kingdom_host]
command = "/path/to/A-Modular-Kingdom/scripts/thermal_runner.py"
args = ["--threshold", "85", "--", "/path/to/A-Modular-Kingdom/.venv/bin/python", "-u", "/path/to/A-Modular-Kingdom/src/agent/host.py"]
...

2. Claude Code 통합

claude CLI 도구가 설치되어 있는지 자동으로 감지하고, Claude Code의 네이티브 명령어를 사용하여 서버를 등록합니다:

claude mcp add a-modular-kingdom \
    /path/to/python \
    /path/to/thermal_runner.py --threshold 85 -- \
...

안전 우선: Thermal Runner 래퍼 (Wrapper)

새로운 브리지 (bridge)의 핵심 부분은 thermal_runner.py 래퍼 (wrapper)입니다.

대규모 코드베이스나 밀집된 RAG (Retrieval-Augmented Generation) 모델을 실행하는 로컬 에이전트는 상당한 CPU 스파이크 (spike)를 유발할 수 있습니다. 노트북의 발열 제한 (thermal limits)이 작동하면 개발 워크스페이스 전체가 느려지게 됩니다.

thermal runner는 에이전트와 MCP 서버 사이에 위치합니다. 이는 CPU 코어 온도를 지속적으로 모니터링합니다. 시스템 온도가 안전 임계값 (예: 85°C)을 초과하면, MCP 서버 실행을 부드럽게 일시 중지하고 코어가 식은 후에만 다시 재개합니다. 이를 통해 로컬 개발 흐름을 원활하게 유지하고 기기가 과열되지 않도록 보장합니다.

왜 A-Modular-Kingdom인가?

브리지가 구축되면, 로컬 에이전트는 다음과 같은 기능에 즉각적이고 마찰 없는 접근 권한을 얻게 됩니다:

• 하이브리드 RAG (Hybrid RAG): Qdrant 및 Cross-Encoder 재순위화 (reranking)를 통한 빠른 어휘 검색 (lexical search) + 의미론적 벡터 검색 (semantic vector retrieval).
• 계층적 범위 메모리 (Hierarchical Scoped Memory): 메모리를 전역 규칙, 선호도, 페르소나 또는 프로젝트별 컨텍스트로 자동 분류.

더 이상의 수동 설정은 필요 없습니다. 저장소를 클론 (clone)하고 설정 스크립트를 실행하여, 로컬 에이전트가 표준화된 메모리 및 지식 베이스라인의 혜택을 누리게 하세요.

지금 바로 저장소를 확인하고 설정해 보세요:
👉 MasihMoafi/A-Modular-Kingdom

저의 더 많은 작업물을 보려면 웹사이트를 방문하세요:
👉 masihmoafi.tech