README.ko.md

agent-tool

English

AI 코딩 에이전트를 위한 MCP(Model Context Protocol) 도구 서버.

왜 만들었나?

AI 코딩 에이전트(Claude Code, Cursor, Codex 등)의 내장 도구에는 알려진 한계가 있습니다:

• 탭 들여쓰기 깨짐: LLM은 공백을 출력하지만, 프로젝트는 탭을 사용. 내장 Edit는 공백을 그대로 써서 들여쓰기 스타일이 망가짐.
• 인코딩 손상: EUC-KR, Shift-JIS, GB18030 파일을 편집하면 조용히 UTF-8로 변환되어 레거시 프로젝트가 깨짐.
• 도구가 너무 분산됨: Redis CLI, MySQL/SSH 클라이언트를 따로 찾고 설정하는 과정은 번거롭고 오류가 잦음. agent-tool은 40개 도구를 한 바이너리로 통합하고 compact 프로필과 고정 toolbox gateway로 필요할 때 호출함.
• 리버스 엔지니어링 지원 부재: 내장 도구로는 바이너리 디스어셈블, PE/ELF 헤더 분석, 함수 경계 탐지, 크로스 레퍼런스 검색이 불가능. agent-tool은 정적 바이너리 분석(디스어셈블리, PDB/DWARF 타입을 적용한 C 디컴파일, xref, 함수 탐지), DAP 디버거, CheatEngine 스타일 메모리 도구를 포함 -- 에이전트에게 완전한 리버스 엔지니어링 능력을 부여.
• 네트워크 검열: 일부 국가에서 정부 수준의 웹 필터링으로 curl/wget 요청이 차단됨. agent-tool은 ECH (Encrypted Client Hello)와 DoH (DNS over HTTPS)를 기본 활성화하여 이런 제한을 우회.

agent-tool은 프로젝트 규칙을 보존하면서 모델 컨텍스트를 제한하는 에이전트 지향 도구를 제공합니다.

지원 에이전트

Claude Code, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI 및 모든 MCP 호환 에이전트.

LLM 친화적 기본 동작

기본 core 프로필은 40개 전체 스키마 대신 toolbox를 포함한 11개만 노출합니다. 실제 MCP 프로토콜 측정에서 직렬화된 도구 목록은 full 약 74KB에서 약 15KB로 줄었습니다. 상시 컨텍스트를 최소화하려면 --profile core-lite로 약 6.4KB인 read, write, edit, grep, toolbox만 노출할 수 있습니다. toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute")로 한 operation에 필요한 필드와 required 목록만 확인한 뒤 toolbox(operation="call", tool="ssh", arguments={...})로 호출할 수 있습니다. 이 gateway는 동적 도구 목록 갱신에 의존하지 않아 Codex 같은 고정 binding 클라이언트에서도 동작합니다. describe가 반환한 tool/version 기반 schema_handle을 다음 describe에 전달하면 스키마가 그대로일 때 짧은 확인만 반환합니다. SSH 실행, MySQL 쿼리, 파일 복사, Windows 스크린샷/클립보드 이미지, 정적 분석의 주요 operation은 compact 스키마를 지원합니다. 또는 --profile core-lite|coding|remote|analysis|full로 시작할 수 있습니다.

대용량 텍스트 결과는 기본 32K자, 절대 상한 128K이며 잘림을 숨기지 않습니다. 페이지 가능 도구는 next_offset 또는 next_cursor를 반환합니다. 로컬 상대경로는 명시적 workspace, MCP 클라이언트 root, 서버 cwd 순서로 해석됩니다.

기능

도구	설명	상태
Edit	스마트 들여쓰기 + 인코딩 보존 문자열 치환 (dry_run 지원)	✅
Read	인코딩 인식 줄번호 읽기. 기본 400줄/32K자, 명시적 truncation과 정확한 next_offset, 초장문 행 안전 처리, 선택적 SHA-256, 이미지 ImageContent	✅
Write	인코딩 인식 파일 생성/덮어쓰기	✅
Grep	기본 32K 예산, 파일별 compact 묶음 출력, 상대경로, .gitignore/.ignore/생성 디렉터리 제외, 바이너리 감지, 중복 없는 결정적 next_cursor 페이징	✅
Glob	정렬·제한된 ** 검색. 상대경로, .gitignore/.ignore/생성 디렉터리 제외, 명시적 has_more, 결정적 cursor 페이징	✅
ListDir	출력 제한·페이징 디렉토리 목록. max_entries + continuation cursor, 디렉토리/파일 필터, 이름 glob 필터, counts-only, flat/tree 지원	✅
Diff	두 파일 비교 (unified diff 출력, 인코딩 인식). 줄바꿈이나 끝 개행만 다른 경우 빈 diff 대신 그 사실을 명시	✅
Patch	unified diff 패치 적용 (dry_run 지원). 줄마다 자기 줄바꿈을 유지하므로 CRLF/LF 혼합 파일이 재작성되지 않음	✅
Checksum	파일 해시 계산 (md5, sha1, sha256)	✅
FileInfo	파일 메타데이터 (크기, 인코딩, 혼합 줄바꿈별 개수, 들여쓰기, 줄 수)	✅
ConvertEncoding	파일 인코딩 변환 (EUC-KR ↔ UTF-8, BOM 추가/제거 등)	✅
Delete	안전한 파일/디렉토리 삭제와 최대 100개 file_paths 일괄 처리. 디렉토리는 recursive=true 필요, 보호 경로·심볼릭링크 차단, 오류 제한, dry_run 미리보기	✅
Rename	원자적 파일/디렉토리 이름 변경 및 이동 (dry_run)	✅
ProcList	프로세스 목록 — PID, 이름, 커맨드라인, 메모리. 민감 인자 자동 마스킹. 이름/포트 필터	✅
ProcKill	PID/포트로 프로세스 종료/일시정지/재개. 트리 킬, 시그널 선택(kill/term/hup/int/stop/cont), 좀비 처리(Linux), dry_run	✅
ProcExec	에이전트를 붙잡지 않는 프로세스 실행. yield_after_sec 안에 안 끝나면 job_id 반환(wait/status/tail/cancel/list, 프로세스 트리 종료), 출력을 계속 수집하는 백그라운드 job, 일시정지 상태 시작, 수명 타임아웃·환경변수, 안전한 반복 진단 압축과 만료형 raw 출력 조회	✅
SSH	기본 32K head+tail 캡처, 원본 바이트 수, 비정상 종료 오류 의미론, 백그라운드 작업(start/wait/status/tail/cancel, toolbox operation=job에서도 조회), 비영어 Windows에서도 UTF-8 powershell_script 출력. 인증 인식 풀링, 호스트 키 검증, ProxyJump, IPv6	✅
SSHKey	로컬 개인키를 PuTTY PPK v3, 전통 PEM, 최신 OpenSSH, PKCS#8 사이에서 변환. 입력 자동 감지, 암호화 PPK/OpenSSH 출력, 0600 저장을 지원하며 키 본문은 반환하지 않음	✅
SFTP	SSH 경유 파일 전송 및 원격 파일시스템 관리. 업로드, 다운로드, ls, stat, mkdir, rm, chmod, rename. 비동기 전송(upload_async/download_async + status/cancel). SSH 세션 풀 재사용. 최대 2GB	✅
Bash	영속 셸 세션 — 작업 디렉토리·환경변수 상태 유지, 안전한 반복 진단 압축과 만료형 raw 출력 조회. 세션 풀링 (최대 5개, 유휴 타임아웃 30분). Unix: bash/sh, Windows: PowerShell/git-bash/cmd	✅
Download	URL에서 파일 다운로드. ECH + DoH 기본 활성. SSRF 차단. HTTP/SOCKS5 프록시. 원자적 파일 저장. 최대 2GB	✅
HTTPReq	HTTP 요청 실행 (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS). 커스텀 헤더, 본문, 프록시 지원. API 테스트용. SSRF 차단	✅
Query	JSON/YAML/TOML 파일에서 점 표기법 경로로 값 하나만 조회 (예: dependencies.react, services.web.ports[0], users[*].email). 형식은 확장자 또는 format으로 지정. 큰 설정 파일의 토큰 절약	✅
Copy	파일/디렉토리 복사. 원자적 쓰기 + 권한 보존. 재귀 디렉토리 복사. Windows 잠긴 파일 폴백 (실행 중인 exe/DLL 이름 변경 후 교체). dry_run 미리보기	✅
Mkdir	디렉토리 생성. 8진수 권한 모드 지정 가능 (예: 0755). 기본 재귀 생성 (mkdir -p). dry_run 미리보기	✅
MultiRead	최대 50개 파일, 호출 전체 32K 예산, 파일별 기본 200줄, 초장문 행 안전 처리, 파일별/전체 continuation 메타데이터. 해시는 opt-in	✅
RegexReplace	파일/디렉토리 전체 정규식 찾기-바꾸기. 인코딩과 줄바꿈 보존, 캡처 그룹 ($1, $2) 지원. 바이너리 파일 자동 제외. dry_run 미리보기	✅
NetCheck	네트워크 진단: external_ip(공인 IPv4/IPv6, 제공자 자동 fallback), dns(A/AAAA/MX/CNAME/TXT/NS/SOA, DoH 또는 시스템 리졸버), tls(인증서 주체·발급자·만료일·SAN·TLS 버전·암호 스위트), port(TCP 포트 OPEN/CLOSED와 응답 시간)	✅
MySQL	MySQL/MariaDB SQL 쿼리 실행. SELECT 결과의 행·열·셀·전체 출력 제한을 각각 설정 가능하고 DML은 영향 행 수 반환. 페이징은 SQL LIMIT/OFFSET 사용	✅
Redis	Redis 명령 실행. 타입별 포맷 출력. TLS 지원. 위험 명령(FLUSHALL, SHUTDOWN 등) 차단	✅
SLOC	언어별 소스 코드 라인 수 집계. 70+ 언어 감지, 파일/언어별 분류, 빈 줄 통계, max_depth 제어	✅
Debug	DAP(Debug Adapter Protocol) 기반 인터랙티브 디버거. 변수값·전체 출력 제한과 variables/completions/modules/loaded_sources 페이징 지원. dlv(Go), debugpy(Python), codelldb(C/C++/Rust) 테스트 완료. 모든 DAP 호환 어댑터 사용 가능. Stdio/TCP 모드. 참고: vsdbg(Microsoft)는 VS Code 라이센스 필수로 단독 사용 불가 — codelldb 또는 netcoredbg를 대안으로 사용	✅
Analyze	정적 바이너리 분석 및 리버스 엔지니어링. x86/x64 PE/ELF 함수의 C 디컴파일(Ghidra 디컴파일러 코어의 Go 포팅인 Gosleigh, 시간/메모리 상한을 건 별도 워커 프로세스에서 실행), GUID가 맞는 PE PDB(내장 리더, DIA SDK 불필요; pdb_force로 GUID가 다른 PDB도 로드) 또는 내장 DWARF 자동 적용(디컴파일에는 함수 이름·프로토타입·구조체/열거형 타입·전역 데이터·비트필드·지역변수 이름과 타입 -- 함수가 쓰는 구조체/열거형은 멤버 오프셋·열거값과 함께 함수 뒤에 출력되고, 그 밖의 타입은 type_info로 이름 조회, disassemble·call_graph·function_at에는 이름과 정확한 함수 경계), MSVC 데코레이션 이름 디맹글, Go 바이너리는 Go ABI 적용, Ghidra 방식의 noreturn 함수 감지(호출 지점 투표만으로 noreturn이 된 함수라도 본문에서 ret에 도달하면 noreturn_verify로 리턴 함수로 유지), 해독 불가 바이트는 그 경로만 halt_baddata()로 끊고, 흐름 폭주(정크 바이트 난독화, Ghidra는 타임아웃)는 함수의 x64 .pdata 범위 안에서 디컴파일하며 범위를 벗어나는 지점마다 표시(halt_missing()), 런타임 추적으로 확인한 조건 분기는 assume_branches로 고정, agent-tool decompile-all로 바이너리 전체를 JSONL 코퍼스로 추출, x86/x64/ARM/ARM64 디스어셈블리(기본은 주소+명령어, show_bytes로 hex 인코딩 열 추가, 코드 안의 switch 테이블은 case 대상과 함께 데이터 줄로 출력), 실행 섹션 전체 오프셋 복구·CFG 신뢰도·호출 대상/결과 필터·ABI 인식 CALL/tail-call 인자까지의 제한된 레지스터/스택/읽기 전용 상수 추적(병렬 고정점 분석, stdcall 인자 정리 반영 -- x86 import는 실제 DLL에서 읽음)을 갖춘 x86/x64 의미 기반 명령어 검색(명령어·레지스터·즉치값·메모리 오프셋, 결과마다 함수 이름), PE/ELF/Mach-O 파싱과 PE import 출력 페이징·상한, 주소·문자열 텍스트·구조체 필드(Class::member, 디컴파일로 확인) xref(코드·즉치값·데이터 포인터·vtable 칸, 참조마다 소속 함수 표시), 함수/콜그래프(PDB 없이 찾은 함수 경계가 대형 x64 이미지에서 PDB 경계와 주소 기준 100%, x86에서 99.5% 일치; 썽크·꼬리 호출을 거친 호출자, vtable 참조), 포인터/RTTI/vtable/구조체 분석, imphash, Rich 헤더, DWARF, 문자열, hexdump, 패턴 검색, 엔트로피, 오버레이, 바이너리 비교. 글로벌 파일 크기 제한 없음	✅
Memtool	CheatEngine 스타일 프로세스 메모리 도구 — 메모리 값 검색/필터/읽기/쓰기, read_chain(base+offset 포인터 체인을 한 콜에 배치로 해소), 라이브 디스어셈블리(x86/x64/ARM/ARM64), 실행 취소, 구조체 패턴 검색, 포인터 스캔, 메모리 diff. 대용량 스캔을 위한 디스크 기반 스냅샷. 세션 관리 (유휴 타임아웃). Windows (ReadProcessMemory), Linux (/proc/pid/mem). Windows는 elevated 시 SeDebugPrivilege 자동 활성화, opt-in force_dacl로 같은 유저의 self-harden DACL 프로세스 우회(원본 DACL 원복). 긴 스캔은 job_id로 yield되고 cancel 시 즉시 멈춤(취소된 filter는 롤백)	✅
Wintool	Windows GUI 자동화 -- 창/자식 컨트롤 검색/열거, 스크린샷 캡처(ImageContent PNG, PrintWindow), 클립보드 이미지 읽기, 텍스트 읽기/쓰기, 클릭, 타이핑, 원시 메시지 전송, 표시/숨기기/최소화/최대화, 이동/크기 변경, 닫기, 포커스. screenshot/clipboard 기본 ImageContent 반환 (save_path 옵션으로 파일 저장). AI 에이전트가 GUI 앱을 "보고" 조작할 수 있게 함. Windows 전용	✅
CodeGraph	완전 내장 시맨틱 코드 그래프. Go 표준 라이브러리 AST와 C/C++·Python·C#·Rust·Java용 지연 압축 tree-sitter WASM에 선언/정의 통합, 반환 체인·generic·alias 전파, 전이 include, 보정 가능한 overload 증거 점수, virtual/interface dispatch, macro/callback 간선, 빌드 조건 provenance, multi-root workspace를 더함. 컴파일러·언어 서버·외부 바이너리·LLM 호출·토큰 비용 없음	✅
SetConfig	런타임 설정 변경 (인코딩, 파일 크기 제한, symlink, workspace 등)	✅
Help	에이전트용 사용법 안내 (인코딩, 들여쓰기, 트러블슈팅)	✅

분석 주석 저장

기존 analyze 도구에서 annotation_set으로 사용자 주석·라벨을 저장하고, annotation_list로 검색·조회하며, annotation_delete로 삭제할 수 있습니다. 디스어셈블리·디컴파일 결과에 저장된 주석이 자동으로 표시됩니다. 사용자 판단은 자동 심볼·디버그 타입과 구분되며, 라벨·subject는 분석 엔진의 심볼 이름이나 추론 타입을 변경하지 않는 메타데이터입니다.

{"operation":"annotation_set","file_path":"sample.exe","rva":"0x1234","subject":"rax","comment":"현재 사용자 포인터로 추정","annotation_status":"hypothesis","annotations_path":"project.annotations.sqlite"}
{"operation":"disassemble","file_path":"sample.exe","va":"0x140001234","annotations_path":"project.annotations.sqlite"}
{"operation":"annotation_list","file_path":"sample.exe","query":"사용자","annotations_path":"project.annotations.sqlite"}

toolbox의 operation="call", tool="analyze", arguments={...}로 호출합니다. 전체 인자·예시는 toolbox describe 또는 help의 analyze 항목에서 확인할 수 있습니다.

• annotations_path로 저장·로드할 SQLite 파일을 직접 지정합니다. 상대 경로는 workspace/MCP root 기준입니다. 생략하면 <사용자 설정 폴더>/agent-tool/analysis-annotations.sqlite를 사용합니다 (Windows는 %APPDATA% 아래). 조회는 DB를 생성하지 않고, 첫 annotation_set이 생성합니다. 코드그래프 DB·분석 캐시와 별도로 보존합니다.
• 바이너리 전체 SHA-256과 정적 주소로 주석을 구분합니다. 동일한 파일을 옮기거나 복사해도 주석을 찾고, 내용이 달라진 바이너리에는 자동 적용하지 않습니다. 빌드 간 자동 이관은 지원하지 않습니다. 주소는 정적 va(hex 또는 파일·디버그 심볼)나 PE의 rva(모듈 기준 오프셋)를 사용합니다. 실행 중 ASLR 주소나 파일 오프셋과는 다릅니다.
• annotation_kind는 instruction(기본), function(함수 시작 주소), decompile입니다. subject로 해당 위치의 레지스터·피연산자·변수를 지정할 수 있습니다. annotation_status는 hypothesis(추정, 기본), confirmed(확인), rejected(기각)이며 사용자의 판단을 기록합니다.
• C 라인 주석은 먼저 decompile에 line_numbers=true를 지정합니다. 출력의 code_hash, C 본문의 line(L 번호), 함수 시작 va와 annotation_kind="decompile"을 annotation_set에 전달합니다. 주석은 해당 줄 앞에 표시됩니다. C 결과가 달라지면 다른 줄에 붙이지 않고, 함수 머리에 needs_review로 남깁니다. 헤더·주석·뒤에 출력되는 타입 정의는 L 번호에 포함되지 않습니다.
• 함수 주석은 C 본문 앞에 표시됩니다. 명령어 주석은 디스어셈블리에 표시되며, 디컴파일에서는 정확한 PDB/.pdata 또는 크기가 알려진 ELF 심볼 경계 안의 명령어 주석도 원래 VA와 함께 모아 표시합니다. 확인할 수 없는 경계는 안내와 함께 시작 주소의 주석만 표시합니다. 함수당 최대 16개 범위를 사용하며, 개별 C 라인에 명령어 주석을 임의로 배치하지 않습니다.
• ID 없이 저장하면 새 주석을 생성합니다. 같은 위치에 주석이 있으면 다른 편집자의 내용을 덮어쓰지 않고 거부합니다. annotation_id로 수정할 때는 저장·조회 결과의 정확한 expected_revision 문자열이 필요합니다. 생략한 필드는 유지하고, 최상위의 비어 있지 않은 필드만 변경합니다. 빈 문자열로 지우거나 line=0을 지정하려면 annotation_patch를 사용합니다. patch에 지정한 값이 최상위 값보다 우선합니다. 수정 후에도 라벨이나 코멘트, 올바른 위치 정보는 남아 있어야 합니다. 삭제도 ID와 revision이 모두 필요합니다. 오래된 revision의 수정·삭제는 거부하므로 다시 조회한 뒤 재시도합니다. revision은 화면 주석과 축약 응답에서도 정확한 문자열로 반환합니다.
• 조회는 주소·종류·subject·상태·ID·query(문자열 포함, ASCII 대소문자 무시)를 지원합니다. max_results 기본 50·최대 200, result_offset은 행 번호이며 JSON의 next_result_offset으로 이어 읽습니다. 출력 상한으로 페이지가 짧아질 수 있습니다. 한 주석도 조회하지 못하면 max_output_chars를 늘립니다. 쓰기의 출력 상한은 최소 256자이며 변경 전에 검사합니다. 상세 결과가 상한을 넘으면 실패로 바꾸지 않고 saved, annotation_id, revision (또는 deleted)과 details_omitted=true를 담은 짧은 JSON 성공 응답을 반환합니다. 디스어셈블리·디컴파일의 페이지 오프셋은 문자 기준입니다. 결과 화면에는 최대 500개를 표시하며 나머지는 조회로 확인합니다.
• 주석 DB를 읽지 못해도 디스어셈블리·디컴파일 결과는 경고와 함께 반환합니다. 주석 저장·조회·삭제 작업 자체의 DB 오류는 계속 오류로 처리합니다. 기존 v1·v2 DB는 변경 없이 조회하고, 첫 쓰기 때 트랜잭션 안에서 필요한 revision·근거·출처·원문 필드를 추가해 v3로 전환합니다. 기존 revision은 유지하며 v1 주석은 "1"에서 시작합니다. v1·v2만 지원하는 과거 실행 파일은 v3 DB를 읽을 수 없습니다.

부분 수정 예시입니다. 직전 조회 결과의 ID와 revision을 사용합니다.

{"operation":"annotation_set","file_path":"sample.exe","annotation_id":"<id>","expected_revision":"1","annotation_patch":{"comment":"사용자 포인터로 확인","annotation_status":"confirmed","label":""},"annotations_path":"project.annotations.sqlite"}

배치와 근거 기록 예시입니다.

{"operation":"annotation_batch","file_path":"sample.exe","annotations_path":"project.annotations.sqlite","batch":[{"operation":"set","rva":"0x1234","subject":"rax","comment":"사용자 포인터","provenance":"수동 분석","evidence":[{"kind":"static","va":"0x140001230","source":"lookup_user 호출","detail":"반환값을 컨텍스트 포인터로 사용함"}]},{"operation":"set","annotation_id":"<id>","expected_revision":"1","annotation_patch":{"annotation_status":"confirmed"}}]}

• 배치는 한 바이너리·DB에 대해 1~32개의 set·delete 항목을 처리합니다. DB 열기와 파일 해시는 한 번만 수행하고, 항목별로 독립 반영해 순서 번호와 성공·충돌 결과를 반환합니다. 다른 항목이 실패해도 성공한 항목은 유지됩니다. max_output_chars는 최소 768 * 항목 수 + 256이며 변경 전에 검사합니다. 기본 출력 예산으로 32개까지 처리합니다. DB를 열지 못하면 배치 전체가 시작되지 않고, 취소 시 완료한 항목은 유지하며 나머지는 실패로 표시합니다.
• evidence에는 최대 16개의 사용자 관찰을 기록합니다. kind는 static·runtime·user, va는 선택적인 정확한 주소 문자열, source는 출처, detail은 필수 관찰 내용입니다. provenance에는 판단의 유래를 기록합니다. 출처를 자동 조회하거나 관찰을 검증하지 않습니다. 저장·표시·검색할 수 있고 부분 수정에서도 유지됩니다. 명시적으로 지우려면 annotation_patch에 evidence:[] 또는 provenance:""를 전달합니다.
• C 라인 주석을 저장할 때 정확한 원문 한 줄을 anchor_text에도 담습니다. annotation_suggest에 주석 ID를 주면 해당 함수를 다시 디컴파일하고, 현재 code_hash·revision과 최대 3개의 위치 후보를 반환합니다. 스냅샷이 같으면 기존 줄, 달라졌으면 원문 또는 토큰 유사도로 찾습니다. 최고 점수가 같은 후보는 ambiguous로 표시합니다. 원문이 없거나 너무 일반적인 경우 후보가 없을 수 있으며, 원문이 없는 과거 주석은 결과가 바뀌면 수동으로 위치를 골라야 합니다. 후보 조회는 DB를 변경하지 않습니다. 검토 후 annotation_set에 ID·expected_revision과 annotation_patch:{"line":N,"code_hash":"<현재 해시>","anchor_text":"<원문>"}를 전달해야 이동하며 revision 검사도 그대로 적용됩니다. source·detail·provenance 상한은 각각 UTF-8 512·1024·512바이트, anchor_text는 C 원문 한 줄·최대 2048바이트입니다.

{"operation":"annotation_suggest","file_path":"sample.exe","annotation_id":"<id>","annotations_path":"project.annotations.sqlite"}

주석 DB에는 비공개 분석 내용이 들어갈 수 있으므로 공개 Git에 포함하지 마세요. 이 저장소는 *.annotations.sqlite*와 기본 DB 파일명을 무시합니다. 다른 파일명을 지정하면 별도 ignore 규칙이 필요합니다. 사용자 주석은 복구 가능한 사본을 보관하며, 분석 캐시 정리로 삭제되지 않습니다.

핵심 개선사항

스마트 들여쓰기

LLM은 보통 공백으로 출력하지만, 많은 프로젝트가 탭을 사용합니다. AgentTool은 파일의 기존 스타일에 맞게 들여쓰기를 자동 변환합니다.

• 부모 .editorconfig의 indent_style, indent_size, tab_width를 속성별로 상속. root = true, unset, indent_size=tab과 흔한 ** 경로 패턴 반영
• 설정이 없으면 줄 수 제한 없이 최대 8 MiB 범위에서 내용 기반 감지. 긴 줄과 LF·CRLF·CR 줄바꿈 지원. 단순 들여쓰기·내어쓰기 빈도보다 블록 시작의 공백 변화 근거를 우선하여 연속 줄 정렬과의 혼동을 줄이고, 근거가 불분명하면 기존의 결정적 빈도 추정 유지
• 유일한 앵커를 복구할 때 새 공백 중첩 단계는 주변 32줄·16 KiB 이내의 가장 가까운 블록 너비 근거 활용. 문자열·주석 상태는 파일 처음부터 최대 8 MiB 표본 내에서 추적하며, 그 이후 앵커는 기존 추정 유지. 일반 주석, 따옴표·raw·삼중 따옴표 문자열과 괄호·대괄호 연속 줄은 구조 추정에서 제외. 언어 파서나 의미를 보장하는 포매터가 아닌 휴리스틱
• 기존 공백 들여쓰기가 탭 설정과 충돌하면 파일에서 감지한 공백 너비 유지
• 탭↔공백과 2칸↔4칸 등의 공백 너비 변환 지원. 변환한 검색 문자열도 줄 경계를 지키며, 탭 깊이 보정 시 상대 중첩 유지
• 유일한 한 줄·여러 줄 블록의 실제 들여쓰기와 접두 공백 대응을 활용하여 혼합 파일의 소수 스타일, 정렬, 빈 줄의 들여쓰기 보존. 블록의 상대 중첩 구조는 일치해야 함
• C++·헤더와 Python 파일 편집은 기존 내장 Tree-sitter WASM을 필요할 때만 재사용. 이웃 블록이나 인자 정렬 대신 실제로 감싸는 블록의 직접 자식 문장에서 새 공백 중첩 단계 추정. 외부 컴파일러·Python 설치·CGO·인덱스 불필요
• 치환 조각을 정상 분석한 경우, 시작 줄의 실제 토큰 열에 맞춘 연속 줄 정렬은 시작 줄의 들여쓰기 이동량을 따르고, 단순히 한 단계 들여쓴 연속 줄은 첫 인자가 시작 줄에 있어도 중첩 단계에 맞춰 너비 변환. 여러 줄 문자열·주석 내부는 입력한 내용 보존. 정확히 일치하는 치환과 명시적 스타일 지정은 기존 동작 유지
• 미지원 파일, 근거가 불분명하거나 오류가 포함된 해당 블록, 분석 실패·시간 초과, 8 MiB 초과 소스는 기존 휴리스틱 사용. 파싱마다 2초 제한이며 치환 조각의 구문 보조는 64 KiB·512줄 이내. 구문 분석은 의미 동등성을 보장하지 않음
• 동일하게 타당한 탭 깊이 후보가 여러 개면 임의로 선택하지 않고 오류 반환
• 감지는 언어 포매터가 아닌 추정 방식이므로, 자동 편집 결과는 dry_run=true로 검토 가능

인코딩 보존

UTF-8로 강제 변환하지 않고, 원본 파일 인코딩을 유지합니다.

• 감지 우선순위: BOM → 호출별 encoding 지정 → 상속된 .editorconfig charset → BOM 없는 UTF-16 → 유효한 UTF-8 → chardet 자동 감지 → 폴백 인코딩
• 지원 인코딩: UTF-8, UTF-8 BOM, EUC-KR, Shift-JIS, ISO-8859-1, UTF-16 (LE/BE, BOM 유무 무관) 등
• 설정 상속: charset은 들여쓰기 설정과 독립적으로 상속. 새 파일의 charset = utf-8-bom 설정은 실제 UTF-8 BOM 기록에 반영
• 디코딩 실패: 잘못된 UTF-8·UTF-16, 감지된 손실성 디코딩, 지원하지 않는 인코딩은 오류 반환. write는 기존 파일의 인코딩을 읽을 수 없으면 덮어쓰기 거부
• 설정 변경 없이 재시도: read, multiread, edit, multiedit, write, patch, file_info에 encoding="EUC-KR", encoding="CP949" 등 지원하는 인코딩 지정 가능. .editorconfig보다 우선하며 기존 BOM은 유지. 의도적인 인코딩 변환은 convert_encoding 사용
• 감지 한계: 자동 감지는 추정 방식이며, 긴 헤더 뒤의 레거시 텍스트를 놓치지 않도록 ASCII 머리말 이후부터 64 KiB 표본을 사용. 결과가 모호하면 encoding 또는 charset 명시
• ASCII 오탐 경고 없음: 유효한 UTF-8 은 직접 검증하므로 순수 ASCII 파일에 신뢰도 경고가 뜨지 않음
• 줄바꿈: LF, CRLF, CR, 혼합 파일을 구분. edit은 CRLF/LF 어느 쪽이든 여러 줄 old_string을 매칭하며(둘이 섞인 파일 포함), edit/regexreplace로 삽입되는 문자열은 해당 위치 구역의 줄바꿈을 따라가므로 나머지 바이트는 그대로 유지됨

일관된 읽기와 묶음 편집

• read, multiread, file_info, grep, patch가 LF·CRLF·CR 줄 경계를 동일하게 처리. 끝 개행은 가짜 줄을 만들지 않으며, EOF 뒤를 읽으면 0줄 반환.
• 읽기 해시는 표시한 텍스트와 같은 원본 바이트에서 계산. edit, multiedit, write, patch, regexreplace, convert_encoding은 저장 전에 읽었던 원본의 해시를 다시 확인. expected_hash는 edit, multiedit, patch에서 지정 가능.
• multiedit도 edit과 같은 encoding·indent_style 옵션 지원. 각 치환은 앞선 결과를 대상으로 하며, 중간 치환 실패 시 파일 전체를 그대로 유지.
• multiread는 전역·파일별 encoding 지원. 원래 입력 목록에 start_file_index=next_file_index, resume_offset=next_offset을 지정해 이어 읽기(오프셋이 0이면 생략). 현재 파일의 최초 요청 끝과 뒤쪽 파일의 원래 요청 범위 유지.
• 읽기 출력 예산은 256~131072자. 첫 줄이 예산보다 길면 잘렸음을 표시하고 다음 줄로 진행하며, 전체 줄을 보려면 max_output_chars 또는 max_line_chars 확대.

변환과 대량 처리 결과

• 디렉토리 regexreplace는 files_scanned, error_count, limit_reached, truncated로 결과와 일치 파일 한도를 명시. 다른 파일이 실패해도 성공한 변경은 유지되므로 부분 결과를 확인하고 실패한 파일만 재시도.
• diff는 encoding_a·encoding_b와 context_lines=0 지원. 해석된 텍스트가 같은 경우와 원본 바이트가 같은 경우를 구분하며, CR·LF 배치 차이와 마지막 개행 누락도 따로 표시.
• convert_encoding의 from_encoding으로 원본 인코딩 지정 가능. GBK와 GB18030은 서로 다른 대상이며 GB2312는 GBK 호환 별칭. 대상 인코딩이 표현하지 못하는 문자가 있으면 원본 유지.
• 파일 쓰기는 대상 옆에 교체 파일을 준비. 준비·교체 실패 시 원본을 직접 잘라 쓰는 방식으로 우회하지 않고 오류 반환. 대상을 잠근 프로그램을 닫거나 디렉토리 권한을 확인한 후 재시도.

토큰을 보호하는 디렉토리 목록

listdir는 기본적으로 페이지당 500개까지만 반환하고, 항목이 더 있으면 next_cursor를 제공합니다. directories_only, files_only, name_pattern (예: A*) 또는 여러 OR 패턴을 받는 include로 결과를 좁힐 수 있습니다. 이름이 필요 없으면 counts_only=true로 파일/디렉토리 개수만 반환합니다.

유휴 메모리 반환

툴 호출 없이 30분이 지나면 서버가 힙을 OS 에 반환한다. stdio MCP 서버는 "버려진 클라이언트" 와 "조용한 클라이언트" 를 구분할 수 없다 -- 서버를 띄운 프로세스가 살아있는 채로 파이프만 쥐고 있으면 EOF 가 영영 오지 않는다 -- 그래서 추측으로 종료하면 잠시 쉬던 세션을 죽이게 된다. 메모리 반환은 그 거래의 안전한 절반이다: 50MB 파일을 한 번 읽은 인스턴스가 200MB 를 계속 쥐고 있는 대신 기준선인 ~20MB 로 돌아간다. 열려있는 shell/ssh 세션은 그대로 유지되고, 클라이언트가 관찰할 수 있는 동작은 아무것도 바뀌지 않는다.

빠른 시작

1. Releases에서 OS에 맞는 바이너리 다운로드
2. agent-tool install 실행 (또는 agent-tool install claude 등 특정 에이전트)
3. IDE / 에이전트 재시작
4. 끝 — core 도구는 즉시 사용하고 나머지는 toolbox gateway로 필요할 때 호출 가능

또는 AI 에이전트에게 시키세요:

"https://github.com/knewstimek/agent-tool/releases/latest 에서 agent-tool을 다운받고 agent-tool install 실행해줘"

Claude Code, Codex 등 AI 코딩 에이전트가 다운로드 → 설치 → 재시작까지 알아서 처리합니다.

권장: 에이전트에게 agent-tool 우선 사용 지시

설치 후 에이전트가 agent-tool을 사용할 수 있게 되지만, 기본 내장 도구(Read, Edit 등)를 계속 쓸 수 있습니다. 에이전트가 agent-tool을 우선 사용하게 하려면 아래 지시를 추가하세요.

코드 탐색 팁: 대규모 프로젝트에서 AST 기반 코드 탐색을 사용하려면 CLAUDE.md / AGENTS.md에 추가하세요:

At the start of a session, run codegraph(op="index", path="<project_root>") to build a code index.
여러 저장소를 하나의 그래프로 만들 때는 codegraph(op="index", path="<db_root>", roots=["<source_root_1>", "<source_root_2>"])를 사용하세요. source-root provenance가 다른 프로젝트의 동명 심볼 오염을 막고, 명시적·전이 include는 root 사이에서도 연결합니다.
Then use codegraph for structural queries (find, callers, callees, methods, inherits) instead of grep.

Strict 또는 Soft 선택:

모드	사용 시점	지시문
Strict	비 UTF-8 파일이나 혼합 들여쓰기 프로젝트	ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools. agent-tool preserves file encoding and respects .editorconfig indentation settings.
Soft	일반 프로젝트	Prefer agent-tool MCP tools (mcp__agent-tool__*) over built-in file tools when available.

어디에 넣을까:

Claude Code — CLAUDE.md (프로젝트별) 또는 전역 설정

프로젝트별 — 프로젝트의 CLAUDE.md에 추가:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

전역 (모든 프로젝트) — ~/.claude/CLAUDE.md에 추가:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

강제 적용 — ~/.claude/settings.json으로 내장 도구를 권한 레벨에서 차단:

{
  "permissions": {
    "deny": ["Read", "Edit", "MultiEdit", "Write", "Glob", "Grep"]
  }
}

Claude Code의 내장 파일 도구를 아예 사용 불가 상태로 만들어 에이전트가 agent-tool을 쓰도록 강제합니다. 프롬프트 지시에 의존하지 않고 확실히 적용하고 싶을 때 권장.

Codex CLI — model_instructions.md (전역)

1. ~/.codex/config.toml에 추가 (최상위 레벨, [mcp_servers.*] 안이 아님):

model_instructions_file = "~/.codex/model_instructions.md"

2. ~/.codex/model_instructions.md 파일 생성:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

3. Codex 재시작.

프로젝트별 — 프로젝트의 AGENTS.md에 추가해도 됩니다.

Cursor / Windsurf / Cline — .cursorrules 또는 AGENTS.md

프로젝트의 .cursorrules, .windsurfrules, 또는 AGENTS.md에 추가:

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

설치

자동 설치 (권장)

# 감지된 모든 에이전트에 자동 등록 (전체 자동 승인 — 모든 도구)
agent-tool install

# Safe 모드 — 로컬 파일 도구만 자동 승인 (SSH, HTTP, DB, 셸 제외)
agent-tool install --safe-approve

# 자동 승인 없음 — 모든 도구 호출에 수동 승인 필요
agent-tool install --no-auto-approve

# 특정 에이전트에만 등록
agent-tool install claude
agent-tool install claude --safe-approve

# 제거 (agent-tool 항목만 삭제, 다른 설정은 보존)
agent-tool uninstall          # 모든 에이전트에서 제거
agent-tool uninstall claude   # 특정 에이전트에서만 제거

설치 권한 수준:

수준	플래그	자동 승인 도구
Full (기본)	(없음)	모든 도구 (mcp__agent-tool__* 와일드카드)
Safe	--safe-approve	29개 로컬 전용 도구 (read, edit, write, grep, glob 등) — SSH, HTTP, DB, bash, 프로세스 제어 제외
None	--no-auto-approve	없음 — 모든 호출에 수동 승인 필요

승인 수준과 스키마 프로필은 별개입니다. 전체 네임스페이스를 승인해도 서버는 토큰 효율적인 core 프로필로 시작할 수 있습니다. toolbox의 operation=call은 네트워크·셸·DB·프로세스 제어 도구도 호출할 수 있으므로 --safe-approve 자동 승인 대상에서 의도적으로 제외됩니다. Safe 모드에서는 toolbox 승인을 매번 검토하고, 전체 AgentTool 네임스페이스를 신뢰하려는 경우가 아니면 영구 허용하지 마세요.

수동 설정

Claude Code / Cursor / Cline (settings.json 또는 mcp.json):

{
  "mcpServers": {
    "agent-tool": {
      "command": "/path/to/agent-tool"
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.agent-tool]
command = "/path/to/agent-tool"

옵션

# 초기 스키마 프로필 선택 (기본: core)
agent-tool --profile core-lite

# core에 선택한 도구만 추가 노출
agent-tool --profile core+copy+delete+ssh+wintool

# UTF-8이 아닌 프로젝트에서 폴백 인코딩 지정
agent-tool --fallback-encoding EUC-KR

프로필: core-lite(read/write/edit/grep/toolbox), core(11개 스키마), coding, remote, analysis, full. 프리셋에 +도구명을 붙여 초기 목록을 조합할 수 있습니다. core+copy+delete+ssh+wintool은 15개를 노출하며 분석·기타 원격 도구는 게이트웨이로 사용합니다. AGENT_TOOL_PROFILE과 toolbox operation=profile도 같은 구문을 지원합니다. 알 수 없는 도구나 빈 구성 요소가 있으면 등록 전에 거부합니다. 실행 중에는 클라이언트와 무관하게 동작하는 toolbox gateway를 우선 사용합니다. operation=describe는 한 도구의 스키마를 반환하며 compact=true와 tool_operation을 함께 쓰면 한 operation으로 제한합니다. 반환된 schema_handle을 다시 전달하면 변경 없는 스키마의 재출력을 피할 수 있습니다. operation=call은 고정된 toolbox binding을 통해 그 도구를 호출합니다. 명령 진단이 압축된 경우에는 operation=output과 표시된 ID로 보존된 bounded raw 출력을 30분 동안 조회할 수 있으며 큰 출력은 next_offset으로 이어 읽습니다. 오래 걸리는 호출은 에이전트를 붙잡지 않습니다. bash, ssh, sftp, download, analyze, codegraph, memtool은 호출이 약 15초를 넘기면(procexec은 yield_after_sec 후) 작업을 계속 돌린 채 job_id를 반환하므로, 그동안 에이전트가 사용자에게 답하거나 다른 일을 할 수 있습니다. 결과는 operation=job과 job_action=wait|status|tail|cancel|list로 받으며, wait를 취소해도 job은 멈추지 않습니다. enable, disable, profile은 tools/list_changed를 반영하는 클라이언트의 직접 binding 용도로 유지됩니다.

환경변수

세션마다 CLI 플래그를 반복하지 않으려면 환경변수를 설정하세요:

# Windows (관리자 권한 불필요)
setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR
setx AGENT_TOOL_PROFILE coding

# Linux / macOS (~/.bashrc 또는 ~/.zshrc에 추가)
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR
export AGENT_TOOL_PROFILE=coding

우선순위: CLI 플래그 > 환경변수 > 기본값 (UTF-8).

세션 디렉터리 별칭

directory_alias를 toolbox의 describe 후 call로 호출해 여러 디렉터리를 등록합니다.

{"operation":"set","aliases":{"src":"src","logs":"logs"}}
{"operation":"set","connection_profile":"dev","aliases":{"deploy":"/srv/releases/current"}}

로컬 값은 존재하는 디렉터리의 작업공간 상대경로나 절대경로입니다. 원격 값은 절대경로이며 등록할 때 서버에 접속하지 않습니다. read·write·edit·copy·multiread 등 공통 로컬 경로에는 @src/main.go, SSH remote_root와 SFTP 경로에는 @deploy를 쓸 수 있습니다. 경로 표시는 별칭이 더 짧을 때 축약하며 파일 내용과 SSH 명령문은 치환하지 않습니다.

별칭은 클라이언트 세션 메모리에만 저장하고 로컬 작업공간·원격 접속 대상별로 구분하며, 연결 종료 시 정리합니다. JSON 파일을 생성하거나 읽지 않습니다. list로 필요할 때만 조회(names로 필터)하고, delete의 names로 삭제합니다. 기존 값을 바꾸려면 overwrite:true가 필요합니다. 이름은 대소문자를 구분하는 ASCII 영숫자이며 두 번째 문자부터 _·-를 허용합니다. 이름은 64자, 범위별 별칭은 64개까지입니다. 미등록 이름과 절대경로 형태·..·:가 들어간 접미 경로는 거부합니다. 실제 파일명이 @로 시작하면 ./@name을 쓰세요. 별칭은 경로 편의 기능이며 샌드박스가 아니므로 심볼릭 링크의 대상까지 제한하지는 않습니다.

로컬 SSH/SFTP connection profile

SSH와 SFTP는 connection_profile 또는 세션 로컬 connection_id를 받아 host, user, key, jump host 필드 반복을 없앨 수 있습니다. 프로필은 OS 사용자 설정 디렉터리의 agent-tool/connections.json에서 읽으며 AGENT_TOOL_CONNECTION_PROFILE_FILE로 위치를 바꿀 수 있습니다. workspace 안에 둘 경우 반드시 명시적으로 ignore하고 로컬에만 보관하세요.

{
  "connections": {
    "dev": {
      "host": "192.0.2.10",
      "user": "builder",
      "key_file": "/local/path/to/id_ed25519",
      "host_key_check": "strict",
      "trusted": true,
      "remote_root": "/srv/app"
    }
  }
}

첫 호출이 반환한 opaque connection_id는 두 도구에서 30분간 재사용할 수 있습니다. 로컬 프로필은 기본적으로 trusted:true이며, trusted:false를 지정하면 사설 주소 경고를 pooled connection당 한 번이 아닌 매 호출마다 표시합니다. 표시 방식만 바뀌며 SSRF 차단과 cloud metadata 보호는 그대로 유지합니다. SSH는 quiet, echo_command, result_only도 지원하며 마지막 옵션은 stdout, stderr, exit_code 중심의 compact JSON을 반환합니다. SFTP는 quiet, result_only, 최대 100개 파일의 upload_many를 지원합니다.

접속 프로필이나 최초 SSH/SFTP 호출에 절대경로 remote_root를 지정하면, 반환된 connection_id로 원격 작업 디렉터리도 재사용합니다. SSH는 일반·백그라운드 명령과 PowerShell 스크립트 실행마다 해당 디렉터리로 이동하며, 이동에 실패하면 실행하지 않습니다. SFTP의 상대 remote_path, 이름 변경의 new_path, 일괄 업로드 대상도 이 루트를 기준으로 해석합니다. 명시적인 절대경로는 유지하며, 접근 범위를 제한하는 샌드박스는 아닙니다. 기존 ID에 다른 루트를 지정하면 원래 ID를 바꾸지 않고 새 ID를 반환합니다.

remote_shell은 SSH 서버의 기본 셸을 뜻하며 posix, cmd, powershell을 지원합니다. 생략하면 Windows 드라이브 루트(D:/app)에는 cmd, 나머지에는 posix를 적용합니다. 서버의 기본 셸이 다르면 명시적으로 지정하세요. Windows 루트는 드라이브 절대경로여야 하며, cmd에서 확장되거나 셸 구문으로 해석되는 특수문자가 있는 루트는 거부합니다. powershell_script는 SSH 기본 셸과 별도로 PowerShell의 작업 디렉터리 설정을 사용합니다.

remote_root가 있는 Windows CMD 명령은 PowerShell의 프로세스 API로 작업 디렉터리를 지정하여 실행하므로 대상에 PowerShell이 필요합니다. 명령을 데이터로 전달해 괄호나 %CD%가 작업 디렉터리 설정 구문에 간섭하지 않게 합니다. PowerShell은 본문의 선두 using·param 선언을 보존하고 스크립트 바깥에서 위치를 설정합니다. 생성된 Windows 실행 명령의 최종 길이가 제한에 도달하면 임시 스크립트 실행 방식으로 전환합니다.

read 진단, multiread 헤더, edit·copy 결과의 로컬 경로는 작업공간 내부일 때 상대경로로 표시합니다. SFTP는 로컬 경로를 작업공간 기준, 원격 경로를 remote_root 기준으로 표시하며 비동기 전송 상태에도 적용합니다. 루트 밖의 경로는 그대로 표시합니다. 파일 내용과 SSH stdout·stderr는 바꾸지 않습니다. SSH 명령 재출력은 기본으로 끄며, 원래 명령을 표시하려면 echo_command:true를 지정합니다. 호출마다 루트 안내나 별칭 목록을 추가하지 않습니다.

{"connection_profile":"dev","command":"git status"}
{"operation":"upload","connection_profile":"dev","local_path":"build/app","remote_path":"bin/app"}

프로필을 수정하지 않으려면 최초 호출에 루트를 지정하고 반환된 ID를 재사용합니다.

{"connection_profile":"dev","remote_root":"/srv/app","command":"git status"}
{"operation":"ls","connection_id":"<returned-id>","remote_path":"logs"}

로컬 SSH 개인키 변환

ssh_key는 개인키 내용을 네트워크로 보내거나 응답에 노출하지 않고 로컬 파일을 변환합니다. 입력은 PPK, PEM, PKCS#8, OpenSSH 중 하나로 자동 감지하며 출력 형식은 ppk, pem, pkcs8, openssh 중 하나입니다.

{
  "operation": "convert",
  "input_path": "server.pem",
  "output_path": "server.ppk",
  "output_format": "ppk",
  "input_passphrase": "",
  "output_passphrase": "",
  "overwrite": false
}

PPK 출력은 버전 3입니다. 패스프레이즈로 보호하는 PPK 출력은 Argon2id, AES-256-CBC, HMAC-SHA-256을 사용하고, OpenSSH 출력은 최신 암호화 형식을 사용합니다. 전통 PEM과 PKCS#8 출력은 의도적으로 암호화하지 않으므로 출력 암호화가 필요하면 openssh 또는 ppk를 사용하세요. 새 파일은 0600 권한으로 저장하며 overwrite=true가 없으면 기존 파일을 바꾸지 않습니다.

런타임 설정

에이전트가 set_config 도구로 재시작 없이 설정을 변경할 수 있습니다:

파라미터	설명	기본값
fallback_encoding	자동 감지 실패 시 폴백 인코딩	UTF-8
encoding_warnings	인코딩 감지 경고 표시	true
max_file_size_mb	read/edit/grep 최대 파일 크기 (MB)	100
allow_symlinks	tar 압축 해제 시 symlink 생성 허용	false
workspace	명시적 로컬 루트. 미설정 시 첫 MCP 클라이언트 root, 이후 cwd 사용	(MCP root/cwd)
allow_http_private	webfetch/download/httpreq의 사설 IP 접근 허용	false
allow_mysql_private	mysql 도구의 사설 IP 접근 허용	true
allow_redis_private	redis 도구의 사설 IP 접근 허용	true
allow_ssh_private	ssh/sftp 도구의 사설 IP 접근 허용	true
enable_doh	DNS over HTTPS 글로벌 활성화 (webfetch/download/httpreq/dnslookup)	true
enable_ech	Encrypted Client Hello 글로벌 활성화 (webfetch/download/httpreq)	true

빌드

go build -trimpath -ldflags="-s -w" -o agent-tool .

크로스 컴파일:

GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool.exe .

릴리스

보호된 GitHub workflow가 테스트, 선언된 전체 asset 빌드, MCPB/checksum 생성 및 업로드된 바이트 검증을 수행합니다. clean 상태로 push된 master에서 먼저 build-only dry-run을 실행합니다.

.\scripts\release.ps1

dry-run 성공 후 main.go에 선언된 버전을 게시합니다.

.\scripts\release.ps1 -Publish

workflow는 docs/releases/vVERSION.md의 추적된 릴리스 노트를 요구합니다. 게시 시 annotated tag와 GitHub Release를 만들고, 최종 MCPB hash로 server.json을 갱신합니다. RepoPlane이 이 저장소를 workspace로 사용할 때는 저장소 로컬 catalog/ manifest를 통해 같은 dry-run, publish, status 작업을 검색하고 실행할 수 있습니다.

트러블슈팅

한글/일본어가 깨져 보일 때 (인코딩 문제)

방법 1: .editorconfig에 charset 추가:

[*]
charset = euc-kr

방법 2: 환경변수로 영구 설정:

setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR   # Windows
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR  # Linux

방법 3: CLI 플래그 (세션별):

agent-tool --fallback-encoding EUC-KR

에이전트용 내장 도움말

agent-tool은 agent_tool_help 도구를 제공합니다. 에이전트가 인코딩 경고나 깨진 텍스트를 만나면 자동으로 사용법을 확인할 수 있습니다.

사용 가능 토픽: overview, encoding, indentation, tools, troubleshooting

보안

agent-tool은 강력한 시스템 접근 기능(SSH, MySQL, Redis, 파일 작업, HTTP 요청)을 제공합니다. AI 코딩 에이전트와 함께 사용할 때 프롬프트 인젝션 위험에 유의하세요:

• SSRF 보호: 클라우드 메타데이터 IP (169.254.x.x, fe80::/10)는 설정과 무관하게 항상 차단됩니다. 사설 IP 접근은 프로토콜별로 set_config로 설정 가능 (allow_http_private, allow_mysql_private, allow_redis_private, allow_ssh_private)
• DLP (데이터 유출 방지): 모든 HTTP 요청 본문에서 민감 데이터 패턴(PEM 개인키, AWS 액세스 키, GitHub/GitLab 토큰, Slack 토큰, .env 파일 덤프)을 스캔하고 전송 전 차단합니다
• 프롬프트 인젝션 경고: 허용된 사설 IP 접속에는 짧은 경고를 표시하며, 신뢰된 로컬 SSH/SFTP 프로필은 pooled connection당 한 번만 표시합니다
• Zip Slip 보호: ../ 경로 조작을 통한 Path Traversal 차단 (zip, tar 모두)
• Zip Bomb 보호: 단일 파일 1GB, 총 추출 크기 5GB 제한
• Symlink: 기본 스킵 (보안). set_config allow_symlinks=true로 활성화 (tar만 지원). 활성화해도 outputDir 밖을 가리키는 symlink는 차단
• 파일 크기 제한: 설정 가능한 최대 파일 크기 (기본 100MB)로 OOM 방지. set_config max_file_size_mb=N으로 조절 가능
• 인코딩 안전성: chardet는 ASCII 머리말 이후의 64 KiB 표본을 사용하며, 잘못된 입력은 편집 결과가 손실된 텍스트로 저장되기 전에 오류로 알림

보안을 위해 AI 에이전트의 도구 호출을 승인 전에 검토하세요. 특히 SSH 명령, 외부 URL로의 HTTP 요청, 데이터베이스 쿼리에 주의가 필요합니다.

기술 스택

• 언어: Go
• MCP SDK: github.com/modelcontextprotocol/go-sdk
• 인코딩: saintfish/chardet + golang.org/x/text
• 배포: 단일 바이너리 (크로스 컴파일)
• 디컴파일러: Gosleigh + Ghidra x86/x64 언어 스펙 내장
• PDB: gopdb (PDB 7.0 리더 + MSVC 디맹글러)

라이선스

MIT

디컴파일러(Gosleigh)와 내장된 Ghidra 언어 스펙은 Apache License 2.0을 따릅니다. Gosleigh는 미국 국가안보국(NSA)이 개발한 Ghidra 디컴파일러(https://github.com/NationalSecurityAgency/ghidra)의 재구현입니다.