agent-tool

한국어

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은 54개의 도구를 하나의 바이너리로 묶고 컴팩트한 프로필을 통해 필요 시 노출합니다.

• 리버스 엔지니어링 지원 없음: 내장 도구는 바이너리를 디스어셈블하거나 PE/ELF 헤더를 검사하거나 함수 경계를 찾거나 상호 참조를 검색할 수 없습니다. agent-tool은 정적 바이너리 분석(디스어셈블, xref, 함수 탐지), DAP 디버거, CheatEngine 스타일 메모리 도구를 포함하여 에이전트에 완전한 리버스 엔지니어링 기능을 제공합니다.

• 네트워크 검열: 일부 국가에서는 정부 차원의 웹 필터링이 일반 curl/wget 요청을 차단합니다. agent-tool은 이러한 제한을 우회하기 위해 기본적으로 ECH(Encrypted Client Hello)와 DoH(DNS over HTTPS)를 사용합니다.

agent-tool은 모델 컨텍스트를 제한된 범위로 유지하면서 프로젝트 규칙을 보존하는 에이전트 중심 도구로 이러한 문제를 해결합니다.

Related MCP server: DevToolkit MCP Server

지원되는 에이전트

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

기본적으로 LLM 효율적

기본 core 프로필은 전체 54개 대신 toolbox를 포함한 11개의 스키마만 노출합니다. 프로토콜 수준 측정에서 직렬화된 도구 목록이 약 84KB(full)에서 18KB로 줄었습니다. toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute")를 사용하여 한 작업의 필드와 필수 목록만 로드한 다음, toolbox(operation="call", tool="ssh", arguments={...})를 통해 호출합니다. 게이트웨이는 동적 도구 목록 새로고침에 의존하지 않으므로 Codex와 같은 고정 바인딩 클라이언트에서도 작동합니다. Describe는 도구/버전에 바인딩된 schema_handle을 반환합니다. 이후 describe에서 이를 보내면 스키마가 여전히 최신일 때 변경 사항이 없다는 짧은 확인 응답을 반환합니다. --profile coding|remote|analysis|full로 시작할 수도 있습니다.

잠재적으로 큰 텍스트 응답은 기본적으로 32K 문자로 제한되며 최대 상한은 128K입니다. 잘림은 항상 표시되며, 페이지 가능한 도구는 next_offset 또는 next_cursor를 반환합니다. 로컬 상대 경로는 명시적 워크스페이스를 기준으로 해석된 다음 MCP 클라이언트 루트를 기준으로 해석됩니다.

기능

주요 개선 사항

스마트 들여쓰기

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

• .editorconfig에서 indent_style 및 indent_size를 읽습니다.

• 콘텐츠 기반 감지(처음 100줄)로 폴백합니다.

• 레거시 파일 보호: 실제 콘텐츠가 .editorconfig와 모순되면 변환하지 않습니다.

인코딩 보존

편집은 UTF-8을 강제하지 않고 원본 파일 인코딩을 보존합니다.

• 탐지 우선순위: BOM → .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 포함 또는 미포함) 등

• ASCII에 대한 오탐 경고 없음: 유효한 UTF-8은 직접 검증되므로 순수 ASCII 파일은 낮은 신뢰도 경고를 발생시키지 않습니다.

• 줄 끝(Line endings): LF, CRLF, CR 및 혼합 파일을 감지합니다. edit은 파일이 CRLF 또는 LF를 사용하든, 둘을 혼합한 파일을 포함해 여러 줄 old_string과 일치하며, edit/regexreplace로 삽입된 텍스트는 삽입되는 영역의 줄바꿈 스타일을 따르므로 파일의 나머지 부분은 바이트 단위로 동일하게 유지됩니다.

토큰 안전 디렉터리 목록

listdir은 기본적으로 페이지당 500개 항목을 반환하고, 더 많은 항목이 있으면 next_cursor를 반환합니다. directories_only, files_only, name_pattern(예: A*) 또는 include의 여러 OR 패턴으로 결과를 좁힐 수 있습니다. 일치하는 파일/디렉터리 개수만 필요한 경우 counts_only=true를 사용하세요.

유휴 메모리 해제

도구 호출 없이 30분이 지나면 서버는 힙을 OS에 반환합니다. stdio MCP 서버는 버려진 클라이언트와 조용한 클라이언트를 구분할 수 없습니다 -- 해당 서버를 생성한 프로세스는 살아 있을 수도, 이미 사용을 마쳤을 수도, 파이프를 계속 열어 두고 있을 수도 있어서 EOF가 결코 도착하지 않습니다 -- 그리고 그런 추측으로 종료하면 단지 일시 중지된 세션이 끊어질 수 있습니다. 메모리를 해제하는 것은 그 절충에서 안전한 선택입니다. 한 번 50MB 파일을 읽은 인스턴스는 머신이 가동되는 동안 200MB를 계속 보유하는 대신 ~20MB 기준선으로 돌아갑니다. 열려 있는 shell 및 ssh 세션은 유지되며, 클라이언트가 관찰할 수 있는 것은 아무것도 변하지 않습니다.

빠른 시작

1. 릴리스에서 OS에 맞는 바이너리를 다운로드합니다.

2. agent-tool install을 실행합니다(특정 에이전트의 경우 agent-tool install claude).

3. IDE / 에이전트를 다시 시작합니다.

4. 완료 — 간결한 핵심 도구를 즉시 사용할 수 있으며, toolbox는 다른 모든 도구를 요청 시 설명하고 호출합니다.

또는 AI 에이전트에게 대신 처리하도록 요청하세요:

"https://github.com/knewstimek/agent-tool/releases/latest에서 agent-tool을 다운로드하고 agent-tool install을 실행하세요."

유능한 AI 코딩 에이전트(Claude Code, Codex 등)라면 다운로드 → 설치 → 재시작의 전체 흐름을 자동으로 처리할 수 있습니다.

권장: 에이전트가 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.
For several repositories sharing one graph, use codegraph(op="index", path="<db_root>", roots=["<source_root_1>", "<source_root_2>"]). Source-root provenance prevents unrelated projects with the same symbol names from contaminating candidates while explicit/transitive includes can still cross roots.
Then use codegraph for structural queries (find, callers, callees, methods, inherits) instead of grep.

Strict 또는 Soft를 선택하세요:

적용 위치:

프로젝트별 — 프로젝트의 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을 사용할 수밖에 없습니다. 프롬프트 지침에 의존하지 않고 엄격하게 적용하려는 경우 권장됩니다.

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에 추가합니다.

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

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

설치

자동 설치(권장)

# Register with all detected agents (full auto-approve — all tools)
agent-tool install

# Safe mode — only auto-approve local file tools (no SSH, HTTP, DB, shell)
agent-tool install --safe-approve

# No auto-approve — manual approval required for every tool call
agent-tool install --no-auto-approve

# Register with a specific agent
agent-tool install claude
agent-tool install claude --safe-approve

# Uninstall (removes agent-tool entry only, preserves other settings)
agent-tool uninstall          # from all agents
agent-tool uninstall claude   # from specific agent

설치 권한 수준:

승인 수준은 스키마 프로필과 독립적입니다. 설치가 전체 네임스페이스를 승인하더라도 서버는 여전히 토큰 효율적인 core 프로필로 시작할 수 있습니다. toolbox는 --safe-approve로 자동 승인되지 않도록 의도적으로 설계되었습니다. operation=call 게이트웨이가 네트워크, 셸, 데이터베이스 및 프로세스 제어 도구를 호출할 수 있기 때문입니다. 안전 모드 사용자는 각 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"

옵션

# Select the initial schema profile (default: core)
agent-tool --profile coding

# Set fallback encoding for projects with non-UTF-8 files
agent-tool --fallback-encoding EUC-KR

프로필은 추가형 프리셋입니다: core(스키마 11개), coding(core에 파일/빌드/셸 관련 더 넓은 도구가 추가된 프로필), remote, analysis, full. 런타임에서는 클라이언트에 독립적인 toolbox 게이트웨이를 우선 사용하세요: operation=describe는 도구 하나의 스키마를 반환하며(compact=true와 tool_operation을 함께 사용하면 단일 작업으로 제한됩니다), operation=call은 안정적인 toolbox 바인딩을 통해 해당 도구를 호출합니다. 반환된 schema_handle을 다시 보내면 변경되지 않은 스키마를 다시 수신하지 않습니다. 명령 진단이 압축된 경우 operation=output은 보고된 ID로 제한된 원시 출력을 30분 동안 검색하며, 페이지네이션이 필요하면 next_offset을 보고합니다. enable, disable, profile은 tools/list_changed를 지원하는 클라이언트에서 계속 사용할 수 있습니다. 고정 바인딩 클라이언트는 항상 게이트웨이를 계속 사용할 수 있습니다.

환경 변수

CLI 플래그를 반복하지 않으려면 AGENT_TOOL_FALLBACK_ENCODING 및/또는 AGENT_TOOL_PROFILE을 설정하세요:

# Windows (no admin required)
setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR
setx AGENT_TOOL_PROFILE coding

# Linux / macOS (add to ~/.bashrc or ~/.zshrc)
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR
export AGENT_TOOL_PROFILE=coding

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

로컬 SSH/SFTP 연결 프로필

SSH와 SFTP는 connection_profile 또는 세션 로컬 connection_id를 허용하므로 host, user, key, jump-host 필드를 반복할 필요가 없습니다. 프로필은 OS 사용자 구성 디렉터리의 agent-tool/connections.json에서 읽습니다. 위치는 AGENT_TOOL_CONNECTION_PROFILE_FILE로 재정의할 수 있습니다. 이 파일을 로컬에 유지하고, 워크스페이스 안에 배치하는 경우 명시적으로 무시되도록 하세요.

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

최초 호출은 불투명한 connection_id를 반환하며, 이 ID는 두 도구 모두 30분 동안 재사용할 수 있습니다. trusted:true는 표시에만 영향을 줍니다. 허용된 사설 주소 경고는 호출마다가 아니라 풀링된 연결당 한 번만 표시됩니다. SSRF 차단과 클라우드 메타데이터 보호는 변경되지 않습니다. SSH는 또한 quiet, echo_command, result_only를 지원하며, 마지막 옵션은 stdout, stderr, exit_code를 중심으로 한 간결한 JSON을 반환합니다. SFTP는 quiet, result_only, upload_many(최대 100개 파일)를 지원합니다.

런타임 구성

에이전트는 재시작 없이 set_config를 통해 런타임에 설정을 변경할 수 있습니다:

빌드

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 .

문제 해결

깨진 텍스트(인코딩 문제)

한국어, 일본어 또는 기타 비ASCII 텍스트가 깨진 문자로 표시되는 경우:

옵션 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 도구가 포함되어 있습니다. 에이전트가 인코딩 경고나 깨진 텍스트를 발견하면 다음을 호출할 수 있습니다:

{ "tool": "agent_tool_help", "arguments": { "topic": "encoding" } }

사용 가능한 주제: 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 연결은 사용자와 AI 에이전트 모두에게 보이는 보안 경고를 표시하여, 가져온 웹 콘텐츠로부터의 프롬프트 인젝션 공격을 감지하는 데 도움을 줍니다.

• Zip Slip 보호: ../ 경로 탐색이 포함된 아카이브 항목은 차단됩니다(zip 및 tar 모두).

• Zip Bomb 보호: 단일 파일 제한(1GB), 전체 추출 제한(5GB).

• 심볼릭 링크: 기본적으로 건너뜁니다. set_config allow_symlinks=true로 활성화할 수 있습니다(tar 전용, zip 심볼릭 링크는 항상 건너뜀). 활성화된 경우에도 출력 디렉터리 외부를 대상으로 하는 심볼릭 링크는 차단됩니다.

• 파일 크기 제한: 최대 파일 크기를 구성할 수 있으며(기본 100MB) 대용량 파일로 인한 OOM을 방지합니다. set_config max_file_size_mb=N으로 조정할 수 있습니다.

• 인코딩 안전성: chardet는 메모리 효율을 위해 전체 파일이 아닌 64KB 샘플을 사용합니다.

최대 보안을 위해, 특히 SSH 명령, 외부 URL에 대한 HTTP 요청, 데이터베이스 쿼리의 경우 AI 에이전트의 도구 호출을 승인하기 전에 검토하십시오.

기술 스택

• 언어: Go

• MCP SDK: github.com/modelcontextprotocol/go-sdk

• 인코딩: saintfish/chardet + golang.org/x/text

• 배포: 단일 바이너리(크로스 컴파일)

라이선스

MIT