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. 빌드

npm install
npm run build

2. 환경 변수

cp .env.example .env
# GEMINI_API_KEY 설정

3. Claude Code 설정

~/.claude.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 설치

# 전역 설치
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 문서

빠른 시작

페르소나 시스템

# 아키텍트 상담
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! 시맨틱 검색, 지식 그래프, 품질 스코어링 지원

# 저장 (시맨틱 검색 가능)
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
)

워크플로우 시스템

# 코드 리뷰 파이프라인
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 실행
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 개요 - Skills 사용법
• 설치 가이드 - 설치 및 설정
• 도구 레퍼런스 - 46개 도구 상세
• 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%

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