minmo-engine 1.0.8

MCP 통합 자동화 프레임워크 - Claude Code와 Gemini를 연동한 멀티 에이전트 오케스트레이션

Minmo Engine

MCP 통합 자동화 프레임워크
Claude Code와 Gemini를 연동한 멀티 에이전트 오케스트레이션 시스템

설치 • 빠른 시작 • 기능 • 아키텍처 • 설정

---

Overview

Minmo Engine은 AI 에이전트들이 협력하여 소프트웨어 개발 작업을 자동화하는 프레임워크입니다.

┌─────────────────────────────────────────────────────────────┐
│                      Minmo Engine                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   👑 Commander (Gemini)     ⚡ Worker (Claude Code)         │
│   ├─ 요구사항 분석           ├─ 코드 작성                    │
│   ├─ 작업 계획 수립          ├─ 파일 수정                    │
│   └─ 에러 분석/수정          └─ 테스트 실행                  │
│                                                             │
│   📚 Indexer (RAG)          📝 Scribe (MCP)                 │
│   ├─ 코드 인덱싱             ├─ 상태 관리 (Redis)            │
│   ├─ FTS5 검색               └─ 이력 저장 (SQLite)           │
│   └─ 의존성 분석                                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Features

🎯 멀티 에이전트 오케스트레이션

• Gemini (지휘관): 요구사항 분석, 작업 분해, 계획 수립
• Claude Code (작업자): 실제 코드 작성 및 실행
• 자동 에러 복구: 실패 시 지휘관에게 피드백 → 계획 수정 → 재시도

🔍 로컬 코드 인덱서 (RAG)

• AST 기반 파싱: 함수, 클래스, 메서드, 독스트링 추출
• FTS5 검색: 빠른 전문 검색 (BM25 랭킹)
• 증분 업데이트: 변경된 파일만 자동 재인덱싱
• 의존성 추적: 모듈 간 관계 분석

📡 MCP (Model Context Protocol) 통합

• Scribe MCP Server: Redis + SQLite 이중 저장소
• 9가지 도구: 검색, 상태 관리, 로깅, 코드 컨텍스트 등
• 보안 필터: SQL 인젝션 방지, SELECT 전용 정책

💻 세련된 CLI

• Rich UI: 컬러풀한 터미널 인터페이스
• 대화형 모드: REPL 스타일 상호작용
• 서브커맨드: index, search, overview, run

---

Installation

요구 사항

• Python 3.9+
• Redis Server (상태 관리용)
• Claude Code CLI (작업 실행용)
• Gemini API Key (계획 수립용)

1. 패키지 설치

# PyPI에서 설치 (권장)
pip install minmo-engine

# 또는 소스에서 설치
git clone https://github.com/minmo/minmo-engine.git
cd minmo-engine
pip install -e .

2. 의존성 설치

# Redis 설치 (Windows)
# https://github.com/microsoftarchive/redis/releases 에서 다운로드
# 또는 WSL2에서: sudo apt install redis-server

# Redis 설치 (macOS)
brew install redis
brew services start redis

# Redis 설치 (Linux)
sudo apt install redis-server
sudo systemctl start redis

3. Claude Code CLI 설치

# npm을 통한 설치
npm install -g @anthropic-ai/claude-code

# 또는 직접 다운로드
# https://claude.ai/code 참조

---

Configuration

환경 변수 설정

# Linux/macOS
export GEMINI_API_KEY="your-gemini-api-key"
export CLAUDE_CLI_PATH="/path/to/claude"  # 선택사항

# Windows (PowerShell)
$env:GEMINI_API_KEY="your-gemini-api-key"

# Windows (CMD)
set GEMINI_API_KEY=your-gemini-api-key

API 키 발급

서비스	발급 URL	용도
Gemini API	Google AI Studio	지휘관 (계획 수립)
Claude Code	Anthropic Console	작업자 (코드 실행)

Redis 설정 (선택사항)

# 기본값: localhost:6379
# 커스텀 설정은 환경변수로:
export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_DB="0"

---

Quick Start

1. 프로젝트 인덱싱

# 현재 디렉토리 인덱싱
minmo index

# 특정 경로 인덱싱
minmo index -p /path/to/project

# 전체 재인덱싱 (강제)
minmo index -f

# 파일 변경 감시 모드
minmo index -w

2. 코드 검색

# 심볼 검색
minmo search "login"
minmo search "database" -l 20

# 프로젝트 개요
minmo overview

3. 작업 실행

# 직접 실행
minmo run "로그인 기능에 2FA 추가해줘"

# 대화형 모드
minmo
> 사용자 프로필 페이지 만들어줘
> 테스트 코드도 작성해줘
> exit

---

Architecture

컴포넌트 구조

minmo/
├── __init__.py          # 패키지 초기화, 버전 정보
├── cli.py               # CLI 인터페이스 (Rich UI)
├── orchestrator.py      # 오케스트레이션 엔진
├── gemini_wrapper.py    # Gemini API 래퍼 (지휘관)
├── claude_wrapper.py    # Claude Code 래퍼 (작업자)
├── indexer.py           # 코드 인덱서 (RAG)
└── scribe_mcp.py        # MCP 서버 (Scribe)

데이터 흐름

사용자 입력
     │
     ▼
┌─────────────────┐
│ MinmoOrchestrator│
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────────┐
│Gemini │ │Claude Code│
│(계획) │ │(실행)     │
└───┬───┘ └─────┬─────┘
    │           │
    └─────┬─────┘
          ▼
    ┌──────────┐
    │ Scribe   │
    │ MCP      │
    └────┬─────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│ Redis │ │SQLite │
│(상태) │ │(로그) │
└───────┘ └───────┘

MCP 도구 목록

도구	설명
search_history	작업 이력 검색 (SQL)
get_state	Redis 상태 조회
update_todo	태스크 상태 업데이트
log_event	이벤트 로깅
get_code_context	코드 컨텍스트 검색
search_symbols	심볼 검색
get_file_structure	파일 구조 분석
get_project_overview	프로젝트 개요
index_project	프로젝트 인덱싱

---

Usage Examples

Python API 사용

from minmo import MinmoOrchestrator, CodeIndexer

# 오케스트레이터 사용
orchestrator = MinmoOrchestrator()
result = orchestrator.start_loop("사용자 인증 시스템 구현")
print(result["status"])

# 인덱서 사용
indexer = CodeIndexer("./my-project")
indexer.index_all()

# 검색
results = indexer.search("authenticate")
for r in results:
    print(f"{r.symbol.name} in {r.symbol.file_path}")

# 코드 컨텍스트
context = indexer.get_code_context("database connection")
print(context["symbols"])

Gemini 직접 사용

from minmo import GeminiWrapper

gemini = GeminiWrapper()

# 프로젝트 분석
analysis = gemini.init_project("./my-project", file_list)

# 요구사항 명확화
clarified = gemini.clarify_goal("로그인 기능 추가")

# 작업 계획
plan = gemini.plan("JWT 기반 인증 구현")

Claude Code 직접 사용

from minmo import ClaudeCodeWrapper

worker = ClaudeCodeWrapper(
    working_directory="./my-project",
    verbose=True
)

result = worker.execute({
    "id": "task_001",
    "title": "로그인 폼 구현",
    "description": "이메일/비밀번호 입력 폼 생성",
    "type": "implementation"
})

---

Configuration Files

.claude_config.json

프로젝트 루트에 MCP 설정 파일:

{
  "mcpServers": {
    "minmo-scribe": {
      "command": "python",
      "args": ["-m", "minmo.scribe_mcp"],
      "env": {}
    }
  }
}

.claude/settings.local.json

Claude Code 권한 설정:

{
  "permissions": {
    "allow": [
      "mcp__minmo-scribe__*"
    ]
  }
}

---

Troubleshooting

Redis 연결 실패

# Redis 서버 상태 확인
redis-cli ping

# 서비스 시작
# Windows: Redis 설치 폴더에서 redis-server.exe 실행
# macOS: brew services start redis
# Linux: sudo systemctl start redis

Gemini API 오류

# API 키 확인
echo $GEMINI_API_KEY

# 키가 설정되지 않은 경우
export GEMINI_API_KEY="your-api-key"

Claude Code를 찾을 수 없음

# Claude CLI 경로 확인
which claude  # Linux/macOS
where claude  # Windows

# 직접 경로 설정
export CLAUDE_CLI_PATH="/path/to/claude"

인덱싱 실패

# 권한 확인
ls -la minmo_index.db

# 강제 재인덱싱
minmo index -f

---

Development

개발 환경 설정

# 저장소 클론
git clone https://github.com/minmo/minmo-engine.git
cd minmo-engine

# 개발 의존성 설치
pip install -e ".[dev]"

# 테스트 실행
pytest

# 린트 검사
ruff check minmo/
mypy minmo/

벡터 검색 확장 (선택사항)

# ChromaDB 지원 설치
pip install -e ".[vector]"

---

Roadmap

• v1.0 - 기본 오케스트레이션
• v1.1 - 벡터 검색 (ChromaDB)
• v1.2 - 웹 대시보드
• v1.3 - 멀티 프로젝트 지원
• v2.0 - 플러그인 시스템

---

Contributing

기여를 환영합니다! CONTRIBUTING.md를 참조해주세요.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

---

Made with ❤️ by Minmo Team