MCP Localization Project

# MCP 로컬화 프로젝트 계획 ## 프로젝트 개요 MCP(Model Context Protocol) 기능을 로컬화하여 CPU와 RAM을 통해 GPU의 인공지능을 진두지휘하는 통합 프로세스 구축 ## 목표 - mcp_research 폴더의 상세한 기능 분석을 바탕으로 한 완전한 MCP 도구 로컬화 구현 - GPU AI 모델(Qwen2.5-Coder-7B 혹은 Gemma3. Ollama를 이용한 변경 가능 구조)과 CPU 기반 MCP 도구들의 효율적인 연동 - 자동화된 작업 흐름 구성 및 컨텍스트 엔지니어링 시스템 구축 - 궁극적인 목표는 로컬 인공지능의 치명적 단점인 문맥 파악 실패와 당장 무슨 작업을 해야 되는지 파악하지 못하는 단점을 보완 ## mcp_research 폴더 기반 고도화된 MCP 도구 목록 ### 1. Terminal MCP (기반: @dillip285/mcp-terminal) - **기능**: 안전한 터미널 명령 실행, 명령 제한, 타임아웃 관리 - **보안**: 허용된 명령어 목록, 경로 제한, 무한 루프 방지 - **로컬화 장점**: 외부 의존성 제거, 커스터마이징, 직접 프로세스 관리 ### 2. Filesystem MCP (기반: @modelcontextprotocol/server-filesystem) - **기능**: 파일 읽기/쓰기, 디렉토리 관리, 파일 검색, 동적 권한 관리 - **고급 기능**: Roots 프로토콜 지원, 원자적 쓰기, 심볼릭 링크 처리 - **로컬화 장점**: 성능 최적화, 동적 권한 관리, 안전한 파일 수정 ### 3. Edit-File-Lines MCP (기반: oakslee/edit-file-lines) - **기능**: 정밀한 라인 편집, 패턴 매칭, 2단계 편집 과정 - **안전성**: 충돌 감지, 원자적 연산, 상태 관리 (TTL) - **로컬화 장점**: 성능 최적화, 커스터마이징, 직접 파일 시스템 접근 ### 4. Google Search MCP (기반: g-search-mcp) - **기능**: 실시간 웹 검색, 병렬 검색, 안티봇 우회 - **고급 기능**: Playwright 기반 검색, 결과 구조화, 웹페이지 내용 추출 - **로컬화 장점**: 실시간성, 안정성, 병렬 처리, 비용 절감 ### 5. Shrimp Task Manager MCP (기반: @cjo4m06/mcp-shrimp-task-manager) - **기능**: 지능형 작업 분해, 의존성 추적, 작업 완료 검증 - **고급 기능**: 연구 모드, 작업 메모리, 반성 메커니즘 - **로컬화 장점**: 성능 최적화, 데이터 프라이버시, 오프라인 작업 ### 6. Playwright Stealth MCP (기반: @pvinis/playwright-stealth-mcp-server) - **기능**: 브라우저 자동화, 스텔스 모드, 웹 스크래핑 - **고급 기능**: 봇 탐지 우회, 자연스러운 행동 패턴, 테스트 코드 생성 - **로컬화 장점**: 성능 최적화, 보안 강화, 실시간 브라우저 상태 확인 ### 7. MCP Debugger (기밀: mcp-debugger) - **기능**: 다중 언어 디버깅, DAP 프로토콜 지원, 세션 관리 - **고급 기능**: 브레이크포인트 시스템, 변수 조사, 스텍 트레이스 - **로컬화 장점**: 성능 최적화, 프라이버시, 오프라인 작업 ### 8. Browser Tools MCP (기반: @agentdeskai/browser-tools-mcp) - **기능**: 브라우저 로그 모니터링, 접근성 감사, 성능 감사 - **고급 기능**: Lighthouse 통합, SEO 감사, NextJS 전용 감사 - **로컬화 장점**: 프라이버시, 실시간 분석, 오프라인 감사 ### 9. Auto Compact System (기반: Claude Code 기능) - **기능**: 자동 컨텍스트 압축, 중요 정보 보존, 무중단 작업 - **고급 기능**: 지능형 요약, 컨텍스트 시각화, 사용자 제어 - **로컬화 장점**: 무제한 압축, 커스터마이징, 성능 최적화 ### 10. Context Engineering System (기반: 2024년 최신 기술) - **기능**: 동적 컨텍스트 생성, RAG 시스템, 멀티모달 컨텍스트 - **고급 기능**: 퍼숏 프롬팅, 사고 과정 연쇄, 시간적 컨텍스트 관리 - **로컬화 장점**: 동적 적응, 품질 최적화, 개인화, 확장성 ## 아키텍처 구상 ### 핵심 컴포넌트 1. **AI 모델 매니저** (GPU) - Qwen2.5-Coder-7B 모델 관리 - Gemma3:12B 모델 관리 - 양자화 및 메모리 최적화 2. **MCP 오케스트레이터** (CPU) - 각 MCP 도구 통합 관리 - 작업 흐름 조정 3. **로컬 데이터베이스** - 작업 히스토리 저장 - 캐시 데이터 관리 ### 데이터 흐름 ``` 사용자 입력 → MCP 오케스트레이터 → AI 모델 → 결과 처리 → 사용자 출력 ↓ ↓ ↓ 작업 분석 도구 선택/실행 결과 저장 ``` ## 개발 단계 ### Phase 1: 기반 구축 (완료) - [x] Qwen2.5-Coder-7B 모델 설치 - [x] 가상환경 설정 - [x] 기본 양자화 구현 ### Phase 2: 통합 프레임워크 개발 (완료) - [x] MCP 오케스트레이터 기본 구조 설계 - [x] 각 도구별 로컬 래퍼 개발 - [x] 통합 API 인터페이스 구현 - [x] 메인 실행 파일 및 문서 작성 ### Phase 3: mcp_research 기반 고도화 (현재 진행) 🎯 **CLAUDE.md 지침 통합**: 무한 로딩 방지, 타임아웃 관리, 안전 조치, 모든 코드블럭 주석 필수 - [ ] **Terminal MCP 완전 구현**: - 핵심 기능: execute_command, get_command_history, kill_process, get_system_info, change_directory, environment_variables - CLAUDE.md 반영: 타임아웃 필수, 프로세스 정리, GPU 환경변수, safe_runner 통합 - [ ] **Filesystem MCP 완전 구현**: - 핵심 기능: read_file, write_file, read_multiple_files, edit_file, create_directory, list_directory, move_file, search_files, get_file_info 등 - CLAUDE.md 반영: 파일 분할 원칙, 효율적 파일 처리, 18KB 제한 고려 - [ ] **Edit-File-Lines MCP 완전 구현**: - 핵심 기능: edit_file_lines, approve_edit, get_file_lines, search_file - CLAUDE.md 반영: dryRun 필수, strMatch/regexMatch, 2단계 검증 - [ ] **Google Search MCP 완전 구현**: - 핵심 기능: search 및 결과 처리 - CLAUDE.md 반영: Playwright 통합, 브라우저 자동화 안전 조치 - [ ] Shrimp Task Manager MCP 완전 구현: 지능형 작업 분해 및 메모리 시스템 - [ ] Playwright Stealth MCP 구현: 스텔스 브라우저 자동화 - [ ] MCP Debugger 구현: 다중 언어 디버깅 시스템 - [ ] Browser Tools MCP 구현: 포괄적 웹 감사 시스템 - [ ] Auto Compact System 구현: 무제한 컨텍스트 압축 - [ ] Context Engineering System 구현: 동적 컨텍스트 생성 ### Phase 4: 통합 및 최적화 (예정) - [ ] 모든 MCP 도구 통합 테스트 - [ ] 성능 최적화 및 메모리 관리 - [ ] 컨텍스트 엔지니어링 시스템 완성 - [ ] 오류 처리 및 복구 시스템 ### Phase 5: 사용자 인터페이스 및 배포 (예정) - [ ] 통합 CLI 인터페이스 - [ ] 웹 기반 관리 패널 - [ ] 설정 관리 시스템 - [ ] 문서화 및 사용자 가이드 ## 기술 스택 - **AI 모델**: Qwen2.5-Coder-7B (양자화), Gemma 3-12B 등 Ollama로 모델은 변경 가능. - **백엔드**: Python 3.12 - **데이터베이스**: SQLite (로컬) - **프레임워크**: FastAPI (API 서버) - **인터페이스**: CLI + Web UI ## 예상 시스템 요구사항 - **GPU**: NVIDIA (CUDA 지원) - **VRAM**: 최소 8GB (양자화 시) - **RAM**: 16GB 이상 권장 - **Storage**: 100GB 이상 (모델 + 캐시) ## mcp_research 기반 고도화 및 확장 기능 ### 고도화된 기존 기능 - **고도화된 보안 시스템**: 명령어 화이트리스트, 경로 제한, 새로운 위협 대응 - **지능형 파일 관리**: 동적 권한 관리, 원자적 연산, 심볼릭 링크 처리 - **고급 텍스트 편집**: 패턴 매칭, 충돌 감지, 2단계 검증 시스템 ### 새로운 고급 기능 - **지능형 작업 분해**: 복잡한 작업을 관리 가능한 하위 작업으로 자동 분해 - **스텔스 브라우저 자동화**: 봇 탐지 우회 및 자연스러운 행동 패턴 - **다중 언어 디버깅**: Python, JavaScript, Go 등 다양한 언어 지원 - **포괄적 웹 감사**: 접근성, 성능, SEO, 모범 사례 자동 검사 - **무제한 컨텍스트 압축**: 관리자 제한 없이 자유로운 컨텍스트 관리 - **동적 컨텍스트 생성**: 실시간 상황에 따른 맞춤형 컨텍스트 제공 ### 커스텀 도구 개발 계획 - **로컬 AI 모델 연동**: Qwen2.5-Coder-7B, Gemma3 등 로컬 모델 직접 연동 - **설정 관리 시스템**: 사용자 선호도 및 프로젝트별 설정 관리 - **성능 모니터링**: 실시간 성능 추적 및 자동 최적화 시스템 - **플러그인 시스템**: 사용자 정의 기능 추가 및 기존 도구 확장 ## 주의사항 - 모든 작업은 로컬 환경에서 수행 - 민감한 데이터 처리 시 보안 고려 - 시스템 리소스 효율적 사용 - 확장 가능한 아키텍처 설계 ## 구현된 주요 컴포넌트 ### 1. MCP 오케스트레이터 (mcp_orchestrator.py) - 작업 생성, 실행, 관리 기능 - SQLite 기반 데이터베이스 관리 - 비동기 작업 처리 및 의존성 관리 - 도구 등록 및 실행 시스템 ### 2. 도구 래퍼 (tool_wrappers.py) - **TerminalWrapper**: 안전한 시스템 명령 실행 - **FilesystemWrapper**: 파일 시스템 접근 (읽기/쓰기/목록) - **EditFileLinesWrapper**: 파일 라인 단위 편집 - **Context7Wrapper**: 라이브러리 문서 검색 (캐시 지원) - **GoogleSearchWrapper**: 웹 검색 (캐시 지원) - **TaskManagerWrapper**: 작업 생성 및 관리 ### 3. API 인터페이스 (api_interface.py) - FastAPI 기반 RESTful API 서버 - 작업 관리 엔드포인트 - 도구 직접 실행 엔드포인트 - 시스템 정보 및 헬스 체크 ### 4. 메인 실행 파일 (main.py) - CLI 모드: 대화형 명령줄 인터페이스 - API 모드: 웹 서버 실행 - 통합 시스템 초기화 및 관리 ## 다음 단계: mcp_research 기반 고도화 및 통합 테스트 ### 단계별 고도화 계획 - [ ] **Phase 3.1**: 핵심 도구 고도화 (Terminal, Filesystem, Edit-File-Lines) - [ ] **Phase 3.2**: 고급 기능 구현 (Google Search, Shrimp Task Manager) - [ ] **Phase 3.3**: 전문 도구 구현 (Playwright Stealth, MCP Debugger) - [ ] **Phase 3.4**: 분석 도구 구현 (Browser Tools, Auto Compact) - [ ] **Phase 3.5**: 컨텍스트 엔지니어링 시스템 구현 ### 통합 테스트 및 검증 - [ ] 각 MCP 도구 개별 기능 테스트 - [ ] 도구 간 상호작용 테스트 - [ ] 대규모 통합 시나리오 테스트 - [ ] 성능 및 메모리 최적화 검증 - [ ] 컨텍스트 엔지니어링 시스템 효과 검증 ### 예상 결과 및 해결될 문제 - **문맥 파악 실패 보완**: 동적 컨텍스트 생성 및 지능형 압축 - **작업 방향성 실패 보완**: 자동 작업 분해 및 의존성 추적 - **성능 및 안정성 향상**: 로컬 실행으로 인한 신뢰성 증대 - **무제한 확장성**: 외부 서비스 제약 없는 자유로운 커스터마이징 ## 사용 가능한 MCP 기능 목록 ### 1. edit-file-lines - `edit_file_lines`: 라인 기반 파일 편집 - `approve_edit`: 편집 승인 및 적용 - `get_file_lines`: 특정 라인 정보 조회 - `search_file`: 파일 내 텍스트 검색 ### 2. browser-tools - `getConsoleLogs`: 콘솔 로그 가져오기 - `getConsoleErrors`: 콘솔 에러 가져오기 - `getNetworkErrors`: 네트워크 에러 로그 가져오기 - `getNetworkLogs`: 모든 네트워크 로그 가져오기 - `takeScreenshot`: 스크린샷 찍기 - `getSelectedElement`: 선택된 요소 가져오기 - `wipeLogs`: 모든 브라우저 로그 지우기 - `runAccessibilityAudit`: 접근성 감사 실행 - `runPerformanceAudit`: 성능 감사 실행 - `runSEOAudit`: SEO 감사 실행 - `runNextJSAudit`: NextJS 감사 실행 - `runDebuggerMode`: 디버거 모드 실행 - `runAuditMode`: 감사 모드 실행 - `runBestPracticesAudit`: 모범 사례 감사 실행 ### 3. shrimp_task_manager - `plan_task`: 작업 계획 - `analyze_task`: 작업 분석 - `reflect_task`: 작업 반성 - `split_tasks`: 작업 분할 - `list_tasks`: 작업 목록 조회 - `execute_task`: 작업 실행 - `verify_task`: 작업 검증 - `delete_task`: 작업 삭제 - `clear_all_tasks`: 모든 작업 삭제 - `update_task`: 작업 업데이트 - `query_task`: 작업 검색 - `get_task_detail`: 작업 상세 정보 조회 - `process_thought`: 사고 과정 처리 - `init_project_rules`: 프로젝트 규칙 초기화 - `research_mode`: 연구 모드 ### 4. mcp_debugger - `create_debug_session`: 디버깅 세션 생성 - `list_supported_languages`: 지원 언어 목록 조회 - `list_debug_sessions`: 활성 디버깅 세션 목록 조회 - `set_breakpoint`: 브레이크포인트 설정 - `start_debugging`: 디버깅 시작 - `close_debug_session`: 디버깅 세션 닫기 - `step_over`: 한 단계씩 실행 (Step Over) - `step_into`: 함수 안으로 실행 (Step Into) - `step_out`: 함수 밖으로 실행 (Step Out) - `continue_execution`: 계속 실행 - `pause_execution`: 실행 중지 - `get_variables`: 변수 가져오기 - `get_stack_trace`: 스택 트레이스 가져오기 - `get_scopes`: 스코프 가져오기 - `evaluate_expression`: 표현식 평가 - `get_source_context`: 소스 컨텍스트 가져오기 ### 5. context7 - `resolve_library_id`: 라이브러리 ID 확인 - `get_library_docs`: 라이브러리 문서 가져오기 ### 6. filesystem - `filesystem__read_file`: 파일 읽기 - `read_multiple_files`: 여러 파일 읽기 - `filesystem__write_file`: 파일 쓰기 - `edit_file`: 파일 편집 - `create_directory`: 디렉토리 생성 - `filesystem__list_directory`: 디렉토리 목록 조회 - `list_directory_with_sizes`: 크기를 포함한 디렉토리 목록 조회 - `directory_tree`: 디렉토리 트리 구조 조회 - `move_file`: 파일 이동/이름 변경 - `search_files`: 파일 검색 - `get_file_info`: 파일 정보 조회 - `list_allowed_directories`: 허용된 디렉토리 목록 조회 ### 7. terminal - `execute_command`: 명령 실행 ### 9. playwright_stealth - `start_codegen_session`: 코드 생성 세션 시작 - `end_codegen_session`: 코드 생성 세션 종료 - `get_codegen_session`: 코드 생성 세션 정보 가져오기 - `clear_codegen_session`: 코드 생성 세션 지우기 - `playwright_navigate`: URL로 이동 - `playwright_screenshot`: 스크린샷 찍기 - `playwright_click`: 클릭 - `playwright_iframe_click`: iframe 클릭 - `playwright_fill`: 입력 필드 채우기 - `playwright_select`: 선택 - `playwright_hover`: 마우스 오버 - `playwright_evaluate`: JavaScript 실행 - `playwright_console_logs`: 콘솔 로그 가져오기 - `playwright_close`: 브라우저 닫기 - `playwright_get`: GET 요청 - `playwright_post`: POST 요청 - `playwright_put`: PUT 요청 - `playwright_patch`: PATCH 요청 - `playwright_delete`: DELETE 요청 - `playwright_expect_response`: 응답 대기 시작 - `playwright_assert_response`: 응답 확인 - `playwright_custom_user_agent`: 사용자 에이전트 설정 - `playwright_get_visible_text`: 보이는 텍스트 가져오기 - `playwright_get_visible_html`: 보이는 HTML 가져오기 - `playwright_go_back`: 뒤로 가기 - `playwright_go_forward`: 앞으로 가기 - `playwright_drag`: 드래그 - `playwright_press_key`: 키 누르기 - `playwright_save_as_pdf`: PDF로 저장 ## 기존 구현 상태 분석 ### 1. Terminal MCP 구현 상태 ⚠️ **불완전** **파일**: `enhanced_terminal_mcp.py` - ✅ **구현됨**: execute_command (기본) - ❌ **누락**: get_command_history, kill_process, get_system_info, change_directory, environment_variables ### 2. Filesystem MCP 고도화 ✅ 완료 (2025-07-19) **파일**: `fixed_filesystem_mcp.py` - **Roots 프로토콜**: 동적 권한 관리 및 경로 제한 - **보안 감사**: 모든 파일 작업 로깅 및 추적 - **메타데이터 관리**: 파일 해시, 권한, 소유권 자동 수집 - **원자적 쓰기**: 파일 손상 방지 및 백업 시스템 - **실시간 감시**: 파일 변경 사항 실시간 모니터링 (선택적) ### 3. Edit-File-Lines MCP 고도화 ✅ 완료 (2025-07-19) **파일**: `enhanced_edit_file_lines_mcp_fixed.py` - **2단계 편집**: Preview → Apply 방식으로 안전성 확보 - **충돌 감지**: 동시 편집 상황 탐지 및 해결 - **세션 관리**: 편집 세션 만료 및 자동 정리 - **원자적 편집**: 트랜잭션 방식 파일 편집 - **편집 히스토리**: 모든 편집 작업 기록 및 추적 ### 4. Google Search MCP 구현 ✅ 완료 (2025-07-19) **파일**: `enhanced_google_search_mcp.py` - **안티봇 우회**: User-Agent 로테이션, 헤더 위장, 지능형 지연 - **다중 검색 엔진**: Google, Bing, DuckDuckGo 지원 - **병렬 검색**: 다중 쿼리 및 엔진 동시 검색 - **캐싱 시스템**: SQLite 기반 1시간 캐시로 성능 최적화 - **결과 구조화**: 순위, 관련성 점수, 내용 추출 기능 ### 5. 테스트 검증 - **Terminal MCP**: 명령 실행, 보안 제한, 히스토리 기록 모두 정상 동작 - **Filesystem MCP**: 파일 읽기/쓰기, 디렉토리 목록, 권한 관리 정상 동작 - **Edit-File-Lines MCP**: 세션 생성, 미리보기, 편집 적용 모두 정상 동작 - **Google Search MCP**: 다중 엔진 검색, 병렬 처리, 캐싱 시스템 정상 동작 ## 업데이트 로그 - 2025-07-18: 프로젝트 계획 수립 및 기본 구조 설계 - 2025-07-18: Qwen2.5-Coder-7B 모델 설치 완료 - 2025-07-18: Phase 2 완료 - 통합 프레임워크 개발 완료 - 2025-07-19: mcp_research 폴더 상세 분석 완료, project_plan.md 업데이트 - 2025-07-19: Phase 3 시작 - mcp_research 기반 고도화 작업 착수 - 2025-07-19: **중요 발견** - 기존 MCP 구현이 불완전함을 확인, 세분화된 기능들 누락 - 2025-07-19: **Phase 3.2 시작** - 완전한 MCP 기능 구현을 위한 재구성