# Hybrid-Gemini MCP

Gemini AI 기반 통합 MCP 서버 - 46개 도구로 AI 전문가 상담, mcp-memory-service 연동 (시맨틱 검색, 지식 그래프), 워크플로우 자동화, 코드 샌드박스 지원

## 주요 기능

| 카테고리 | 도구 수 | 기능 |
|----------|--------|------|
| **Persona** | 6 | AI 전문가 상담 (architect, debugger, reviewer 등) |
| **Memory** | 11 | mcp-memory-service 연동 - 시맨틱 검색, 지식 그래프, 품질 스코어링, 문서 인제스트 |
| **Conversation** | 6 | 대화 세션 관리 (start, ask, dual, smart, history, list) |
| **Workflow** | 4 | 도구 체이닝, 순차/병렬 실행 |
| **Sandbox** | 6 | Python/JavaScript 안전 실행 |
| **File** | 5 | 파일 읽기/쓰기/편집 |
| **SSH** | 3 | 원격 명령 실행, 서버 목록, 연결 테스트 |
| **MCP** | 3 | 다른 MCP 서버 호출 |
| **Cache** | 4 | 응답 캐싱 (stats, list, clear, delete) |
| **Streaming** | 2 | 스트리밍 응답 |

> ⚠️ **RAG 도구 Deprecated**: 이전 RAG 시스템 (Knowledge-Base-Hybrid-RAG)은 mcp-memory-service로 대체되었습니다.
> `memory_search`, `memory_graph`, `memory_ingest`가 RAG 기능을 제공합니다.

## 설치

### 1. 빌드
```bash
npm install
npm run build
```

### 2. 환경 변수
```bash
cp .env.example .env
# GEMINI_API_KEY 설정
```

### 3. Claude Code 설정

`~/.claude.json`에 추가:
```json
{
  "mcpServers": {
    "hybrid-gemini-mcp": {
      "command": "node",
      "args": ["/path/to/Hybrid-Gemini-mcp/dist/server-cli.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Claude Code Skills

### Skills 설치

```bash
# 전역 설치
cp -r .claude/skills/hybrid-gemini ~/.claude/skills/

# 또는 프로젝트별 설치
cp -r .claude/skills/hybrid-gemini /your/project/.claude/skills/
```

### Skills 사용

Claude Code에서 다음 키워드로 자동 활성화:
- "페르소나", "architect", "debugger", "reviewer"
- "메모리 저장", "시맨틱 검색", "지식 그래프"
- "워크플로우", "체이닝"
- "코드 실행", "샌드박스"

자세한 내용: [Skills 문서](docs/skills/README.md)

## 빠른 시작

### 페르소나 시스템

```python
# 아키텍트 상담
mcp__hybrid-gemini-mcp__ask_architect(question="마이크로서비스 설계 방법")

# 디버거 상담
mcp__hybrid-gemini-mcp__ask_debugger(issue="WebSocket 연결 끊김", context="에러 로그")

# 코드 리뷰
mcp__hybrid-gemini-mcp__ask_reviewer(code="def handler(): ...", focus="security")

# 페르소나 직접 실행
mcp__hybrid-gemini-mcp__persona_execute(persona="backend", prompt="FastAPI 최적화")
```

### 메모리 시스템 (mcp-memory-service 연동)

> **NEW!** 시맨틱 검색, 지식 그래프, 품질 스코어링 지원

```python
# 저장 (시맨틱 검색 가능)
mcp__hybrid-gemini-mcp__memory_store(
    content="프로젝트 아키텍처: FastAPI + React + PostgreSQL",
    tags=["project", "architecture"]
)

# 시맨틱 검색 (자연어 질문 가능)
mcp__hybrid-gemini-mcp__memory_search(
    query="FastAPI 관련 설정은?",
    mode="semantic",  # semantic, exact, hybrid
    limit=10
)

# 시간 기반 검색
mcp__hybrid-gemini-mcp__memory_search(
    time_expr="last week",  # yesterday, 3 days ago, last month
    tags=["decision"]
)

# 지식 그래프 탐색
mcp__hybrid-gemini-mcp__memory_graph(
    action="connected",  # connected, path, subgraph
    hash="abc123",
    max_hops=2
)

# 품질 평가
mcp__hybrid-gemini-mcp__memory_quality(
    action="rate",
    content_hash="abc123",
    rating=1,  # -1 (나쁨), 0 (중립), 1 (좋음)
    feedback="유용한 정보"
)

# 문서 인제스트 (PDF, TXT, MD, JSON)
mcp__hybrid-gemini-mcp__memory_ingest(
    directory_path="/docs",
    tags=["documentation"],
    recursive=True
)
```

### 워크플로우 시스템

```python
# 코드 리뷰 파이프라인
mcp__hybrid-gemini-mcp__workflow_execute(
    name="Code Review Pipeline",
    steps=[
        {"tool": "file_read", "args": {"path": "src/main.py"}, "saveAs": "code"},
        {"tool": "ask_reviewer", "args": {"code": "$code.text"}, "saveAs": "review"},
        {"tool": "memory_store", "args": {"content": "$review.text", "metadata": {"tags": ["review"]}}}
    ]
)
```

### 코드 샌드박스

```python
# Python 실행
mcp__hybrid-gemini-mcp__sandbox_python(code="print(sum(range(100)))")

# JavaScript 실행
mcp__hybrid-gemini-mcp__sandbox_javascript(code="console.log([1,2,3].map(x => x*2))")

# 테스트 케이스 실행
mcp__hybrid-gemini-mcp__sandbox_test(
    code="function add(a, b) { return a + b; }",
    testCases=[
        {"input": [1, 2], "expected": 3},
        {"input": [-1, 1], "expected": 0}
    ]
)
```

## 페르소나 목록

| 페르소나 | 모델 | 용도 |
|---------|------|------|
| `architect` | Pro | 시스템 설계, 아키텍처 |
| `backend` | Flash | 서버 개발, API |
| `frontend` | Pro | UI/UX, React/Vue |
| `debugger` | Pro | 버그 수정, 분석 |
| `reviewer` | Pro | 코드 리뷰, 품질 |
| `quick` | Flash | 빠른 작업, 프로토타입 |
| `thinker` | Pro | 심층 분석, 알고리즘 |
| `security` | Pro | 보안 분석, 취약점 |

## 아키텍처

```
Hybrid-Gemini MCP (46개 도구)
│
├── Persona Layer (6)
│   ├── ask_architect, ask_debugger, ask_reviewer
│   └── persona_execute, persona_list, persona_suggest
│
├── Memory Layer (11) - mcp-memory-service 연동
│   ├── memory_store, memory_search, memory_list
│   ├── memory_delete, memory_update, memory_cleanup
│   ├── memory_health, memory_stats, memory_quality
│   └── memory_graph, memory_ingest
│
├── Conversation Layer (6)
│   ├── conversation_start, conversation_continue, conversation_ask
│   └── conversation_list, conversation_get, conversation_delete
│
├── Workflow Layer (4)
│   ├── workflow_execute, workflow_template
│   └── workflow_validate, workflow_register_tool
│
├── Sandbox Layer (6)
│   ├── sandbox_execute, sandbox_javascript, sandbox_python
│   └── sandbox_eval, sandbox_test, sandbox_info
│
├── File Layer (5)
│   ├── file_read, file_write, file_edit
│   └── file_list, file_delete
│
├── Infrastructure (6)
│   ├── ssh_execute (1)
│   ├── mcp_list_servers, mcp_list_tools, mcp_call (3)
│   └── cache_get, cache_set (2)
│
└── Streaming Layer (2)
    └── stream_generate, stream_persona
```

## 문서

- [Skills 개요](docs/skills/README.md) - Skills 사용법
- [설치 가이드](docs/skills/SETUP.md) - 설치 및 설정
- [도구 레퍼런스](docs/skills/TOOLS.md) - 46개 도구 상세
- [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) - 메모리 시스템

## 기술 스택

- **언어**: TypeScript
- **런타임**: Node.js
- **MCP SDK**: @modelcontextprotocol/sdk
- **Gemini**: CLI (Flash + Pro)
- **데이터베이스**: better-sqlite3
- **파일 저장**: ~/.config/hybrid-gemini-mcp/

## 테스트 커버리지

| 파일 | Stmts | Branch | Funcs | Lines |
|------|-------|--------|-------|-------|
| All files | 100% | 100% | 100% | 100% |
| cache-service.ts | 100% | 100% | 100% | 100% |
| file-service.ts | 100% | 100% | 100% | 100% |
| mcp-client.ts | 100% | 100% | 100% | 100% |
| memory-service.ts | 100% | 100% | 100% | 100% |
| rag-service.ts | 100% | 100% | 100% | 100% |
| sandbox-service.ts | 100% | 100% | 100% | 100% |
| ssh-service.ts | 100% | 100% | 100% | 100% |
| streaming-service.ts | 100% | 100% | 100% | 100% |
| workflow-service.ts | 100% | 100% | 100% | 100% |

```bash
npm run test           # 테스트 실행
npm run test:coverage  # 커버리지 리포트
```

- **463개 테스트**, 10개 테스트 파일
- 모든 서비스 파일 100% 커버리지 달성

## 로드맵

- [x] 대화 관리 (SQLite)
- [x] Gemini CLI 통합 (Flash + Pro)
- [x] Dual Model / Smart Selection
- [x] 페르소나 시스템 (8개)
- [x] 파일/SSH/MCP 조작
- [x] ~~RAG 통합~~ → mcp-memory-service로 대체
- [x] 응답 캐싱
- [x] 스트리밍 응답
- [x] 메모리 지속성
- [x] 워크플로우 체이닝
- [x] 코드 샌드박스
- [x] Claude Code Skills
- [x] mcp-memory-service 연동 (시맨틱 검색, 지식 그래프, 품질 스코어링)
- [ ] Context Caching (80% 비용 절감)
- [ ] Grounding (Google Search)
- [ ] 멀티모달 (이미지/비디오/오디오)

## 라이선스

MIT

## 작성자

hwandam

## 생성 날짜

2025-12-30