AMEVA MCP Toolkit Utils

61개 MCP 도구를 제공하는 AMEVA 에코시스템의 핵심 범용 유틸리티 서버.
Git, DB, 웹 크롤링, 시스템 모니터링, Docker, 네트워크 스캔, 코드 검색까지 단일 서버로 통합.

---

📦 도구 도메인 구조

도메인	경로	도구 수	설명
Document	src/tools/document/	5	MD↔DOCX 변환, 이미지 경로 수정, 파일 관리
Git	src/tools/git/	13	git 전 작업 + 전체 레포 브로드캐스트, 커밋 메시지 생성
SSH	src/tools/ssh/	1	원격 SSH 커맨드 실행
Web	src/tools/web/	3	웹 크롤링, 가독성 클리너, 데드링크 스캐너
Database	src/tools/database/	19	SQLite CRUD, 스키마, ERD, 마스킹/언마스킹, 동기화
System Utils	src/tools/utils/	16	시스템/GPU/온도, 프로세스, 스케줄러, REST 클라이언트, HTML→PDF
Docker	src/tools/docker/	1	컨테이너 목록/시작/정지/로그/통계/inspect
Dataset	src/tools/dataset/	1	Audit 로그 전사 병합 및 통계 분석
Search	src/tools/search/	1	BM25 기반 소스코드 전역 검색
Network	src/tools/network/	1	병렬 포트 스캔 & AMEVA 서비스 자동 인식
총계		61

---

🔐 보안 정책

경로 보안

• 모든 파일시스템 접근은 C:\ameva 하위만 허용 (Path Traversal 방지)
• Docker 컨테이너 내부 실행 시 /app/workspace 자동 리매핑

CUD 쓰기 토큰 보안

DB, 마스킹, 동기화 등 데이터 변경 작업은 client_token 필수:

# 환경변수 설정
AMEVA_DB_WRITE_TOKEN=your-secret-token-here

토큰이 일치하지 않으면 Security Error: CUD (Write) operation is restricted. 반환.

---

🛠️ 전체 도구 목록

📄 Document & File (5개)

도구명	설명
convert_md_to_docx	마크다운 → DOCX (헤딩, 리스트, 코드블록, 볼드 지원)
docx_to_markdown	DOCX → 마크다운 (헤딩, 테이블, 볼드/이탤릭 파싱)
md_image_path_fixer	MD 내 깨진 이미지 경로 자동 교정
delete_file_in_docker	Docker 내 파일 삭제
move_file_in_docker	Docker 내 파일 이동/리네임

🌿 Git & Source Control (13개)

도구명	설명
git_status	레포 상태 조회
git_pull	원격 풀 (토큰 자동 주입)
git_commit_and_push	add + commit + push 원스텝
git_clone	원격 레포 클론
git_log	커밋 히스토리 조회
git_diff	변경사항 diff
git_branch	브랜치 목록/생성/삭제
git_checkout	브랜치/파일 체크아웃
git_merge	브랜치 머지
git_reset	soft/mixed/hard 리셋
git_stash	stash push/pop/list/apply/clear
workspace_git_broadcaster	전체 AMEVA 레포 일괄 상태 진단
git_commit_helper	staged diff 기반 커밋 메시지 자동 생성

🌐 Web & Crawling (3개)

도구명	설명
crawl_website	웹사이트 크롤 (링크/텍스트/메타)
web_readability_cleaner	광고/네비 제거 후 순수 마크다운 변환
dead_link_scanner	MD 파일 내 데드링크 전수 검사

🗄️ Database (19개)

도구명	쓰기 토큰	설명
db_get_schema	❌	스키마 분석
db_execute_query	조건부	SQL 실행 (output_format: markdown/json/csv/html/xml/plain)
db_view_table_data	❌	테이블 브라우저 (페이징, 정렬, 필터)
db_summarize_table	❌	테이블 프로파일링
db_search_schema	❌	스키마 키워드 검색
db_global_search_value	❌	전체 텍스트 컬럼 값 검색
db_generate_erd	❌	Mermaid ERD 다이어그램 생성
db_generate_mock_data	✅	가짜 테스트 데이터 삽입
db_merge_tables	✅	DB 간 테이블 머지
db_sync_connector	✅	DB 간 테이블 벌크 동기화 (upsert)
db_mask_table_data	✅	컬럼 GDPR 마스킹
db_unmask_table_data	✅	마스킹 복원 (shadow 테이블 또는 규칙 기반)
db_enable_time_travel	✅	shadow ledger + 트리거 활성화
db_restore_time_travel	✅	타임스탬프 기반 데이터 복원
db_compare_schemas	❌	두 DB 스키마 비교 + 동기화 DDL
db_transpile_sqlite_to_other	❌	SQLite → PostgreSQL/MySQL 변환
db_optimize_query_tuning	❌	인덱스 추천 분석
db_format_sql	❌	SQL 포매팅/키워드 대문자화
db_profile_and_scan_health	❌	DB 헬스체크 (FK 무결성, 인덱스 분석)

⚙️ System Utilities (16개)

도구명	설명
get_system_info	CPU/메모리/디스크 현황
check_port	TCP 포트 열림 여부 확인
generate_uuid	UUID v4 생성
format_json	JSON 포맷/검증
base64_encode_decode	Base64 인코딩/디코딩
calculate_file_hash	MD5/SHA256 해시 계산 (Docker)
get_external_ip	내부/외부 IP 조회
send_http_request	임의 HTTP 요청
find_large_files	대용량 파일 탐색 (Docker)
extract_text_from_url	URL에서 순수 텍스트 추출
gpu_monitor	GPU 사용률/VRAM/온도/전력 실시간 조회
system_thermal_scanner	CPU 온도/클럭/코어별 사용률
process_watchdog	프로세스 스캔/탐색/강제종료
task_cron_scheduler	Windows schtasks / Linux crontab 관리
rest_client_simulator	curl 없는 REST API 테스트 + curl 등가 출력
html_to_pdf_renderer	HTML/URL → PDF 변환 (weasyprint/pdfkit/headless)

🐳 Docker Container Control (1개)

도구명	설명
docker_container_manager	컨테이너 list/stats/start/stop/restart/logs/inspect

📦 Dataset & Audit (1개)

도구명	설명
audit_log_aggregator	전체 AMEVA 프로젝트 mcp_audit.jsonl 병합 및 통계

🔍 Code Search (1개)

도구명	설명
vector_code_searcher	BM25 알고리즘 소스코드 전역 검색 (컨텍스트 하이라이팅)

🌐 Network Discovery (1개)

도구명	설명
service_discovery	병렬 포트 스캔 + AMEVA 서비스 자동 인식 (Streamlit/Gradio/Ollama 등)

---

🚀 빠른 시작

필수 환경변수

AMEVA_GITHUB_TOKEN=ghp_xxxx         # GitHub 인증 토큰 (git push/pull)
AMEVA_DB_WRITE_TOKEN=your-secret    # DB 쓰기 권한 토큰
AMEVA_IN_CONTAINER=true             # Docker 내부 실행 시

실행

# 로컬 직접 실행
cd src
python server.py

# Docker 실행
docker compose up -d

MCP 클라이언트 연결 (Claude Desktop)

{
  "mcpServers": {
    "ameva-toolkit-utils": {
      "command": "python",
      "args": ["C:/ameva/AMEVA-MCP-Toolkit-Utils/src/server.py"],
      "env": {
        "AMEVA_GITHUB_TOKEN": "ghp_xxxx",
        "AMEVA_DB_WRITE_TOKEN": "your-secret"
      }
    }
  }
}

---

📂 프로젝트 구조

AMEVA-MCP-Toolkit-Utils/
├── src/
│   ├── server.py              # FastMCP 서버 진입점 (61개 도구 등록)
│   ├── tools/
│   │   ├── document/          # MD↔DOCX, 파일 관리
│   │   ├── git/               # Git 전 작업 + 브로드캐스터
│   │   ├── ssh/               # 원격 SSH
│   │   ├── web/               # 크롤링, 가독성, 데드링크
│   │   ├── database/          # SQLite 전 기능
│   │   ├── utils/             # 시스템, GPU, 프로세스, 스케줄러
│   │   ├── docker/            # 컨테이너 관리
│   │   ├── dataset/           # Audit 로그 병합
│   │   ├── search/            # BM25 코드 검색
│   │   └── network/           # 포트 스캔
│   └── utils/
│       └── audit_logger.py    # MCP 액션 감사 로그
├── requirements.txt
├── Dockerfile
└── README.md

---

📋 requirements.txt 의존성

mcp[cli]
fastmcp
requests
beautifulsoup4
psutil
python-docx
paramiko

선택적: weasyprint 또는 pdfkit (HTML→PDF), nvidia-smi (GPU 모니터)