local-code-agent

FastMCP 기반으로 개발된 로컬 MCP 서버: 외부 AI(ChatGPT, Claude 등)가 Cloudflare Tunnel을 통해 안전하게 터널링하여 로컬 작업 공간(파일 읽기/쓰기/편집, 검색, shell 명령어, Git 작업)을 원격으로 제어할 수 있으며, Bearer Token 인증, 샌드박스 격리 및 감사 로그를 제공합니다.

이 프로젝트는 AI/LLM 로직을 포함하지 않으며, 도구 계층 서비스와 터널 구성만 포함합니다.

환경 요구 사항

• Python 3.10+(FastMCP 필수 요구 사항)

• pip install -r requirements.txt(fastmcp, pyyaml)

빠른 시작

# 1. 安装依赖
pip install -r requirements.txt
set MCP_AUTH_TOKEN=your_long_random_token
set MCP_WORKSPACE=D:\projects\my-project

# 2. 启动服务（默认监听 127.0.0.1:8000，路径 /mcp）
python server.py

# 3. 公网穿透（临时域名）
cloudflared tunnel --url http://127.0.0.1:8000

# 固定域名（绑定自有域名）
cloudflared tunnel --url http://127.0.0.1:8000 --hostname mcp.yourdomain.com

상태 확인: GET http://127.0.0.1:8000/health(기본적으로 인증 없음; 나머지 엔드포인트는 Bearer Token을 반드시 포함해야 함).

그래픽 인터페이스(선택 사항)

명령줄을 사용하지 않아도 됩니다. tkinter는 Python 표준 라이브러리이므로 별도 설치가 필요하지 않습니다.

python -m gui.app

콘솔 기능:

• 작업 공간 폴더: 「선택…」을 클릭하여 폴더 선택기를 엽니다. 한 번에 하나의 폴더만 선택할 수 있으며, AI의 모든 작업은 해당 폴더(샌드박스) 내로 제한됩니다. 폴더를 변경하면 현재 선택이 대체됩니다.

• 인증 Token: 시작 시 자동으로 무작위 Token이 생성되며, 「재생성」을 클릭하여 변경할 수 있습니다. 이 Token은 AI 클라이언트의 Authorization: Bearer ...에 입력해야 합니다.

• 포트 / 읽기 전용 모드: 수신 포트를 설정합니다. 읽기 전용을 체크하면 쓰기/편집/명령어 도구가 비활성화됩니다.

• 서비스 시작 / 중지: 하위 프로세스로 server.py를 실행하며, 중지하면 프로세스가 종료됩니다.

• 상태 표시줄: /health를 폴링하여 서비스 버전, 현재 작업 공간, 실행 시간을 표시합니다. 또한 cloudflared 터널 명령어를 한 번에 복사할 수 있습니다.

• 로그 영역: server 하위 프로세스의 출력을 실시간으로 표시하며, 600줄을 초과하면 자동으로 잘립니다.

GUI는 server.py의 실행기일 뿐이며, 동일한 인증, 샌드박스, 감사 보안 메커니즘을 사용합니다. 공용 네트워크 연결 방식은 명령줄과 동일합니다.

클라이언트 연결

ChatGPT Custom Connector: URL에 https://<tunnel-host>/mcp를 입력하고, 요청 헤더에 Authorization: Bearer your_long_random_token을 추가합니다.

Claude Desktop의 claude_desktop_config.json:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "https://mcp.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer your_long_random_token" }
    }
  }
}

도구 목록

보안 모델

• 샌드박스: 모든 경로는 realpath로 확인되며, 작업 공간 루트 디렉토리 내에 있어야 합니다(심볼릭 링크 탈출 차단 가능). ../ 및 절대 경로는 경계를 넘을 수 없습니다.

• 인증: FastMCP DebugTokenVerifier가 Bearer Token을 검증합니다. Token은 MCP_AUTH_TOKEN에서만 읽습니다(개발 시 --token 사용 가능). 없으면 시작이 거부됩니다.

• 민감 파일: .env, .env.*, *.pem, *.key, id_rsa, .ssh/, .aws/, credentials는 모든 경로 수준에서 차단됩니다. 통일된 'access denied'를 반환하며, 파일 존재 여부를 노출하지 않습니다.

• 명령어 화이트리스트: config.yaml의 command_allow, command_deny, danger_commands(x-confirm: true 필요).

• 다운로드: download_allow_domains의 http(s) 호스트만 허용; 리디렉션 금지; 50MB 초과 시 중단 및 미완성 파일 삭제.

• 감사 로그: JSON 행 형식, 10MB × 5 로테이션, 시간, 도구 이름, 비식별화된 매개변수, 결과, 소요 시간 기록.

• 읽기 전용 모드: python server.py --readonly는 읽기/검색/Git 보기 도구만 등록합니다.

구성 우선순위

작업 공간: --workspace > 환경 변수 MCP_WORKSPACE > config.yaml(기본값 .). 나머지 구성은 모두 config.yaml에서 가져옵니다(파일 내 기본값 참조).

프로젝트 구조

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
command_whitelist.py      # 命令白名单校验
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # 域名白名单下载
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
gui/                      # tkinter 启动器
start.py / start.spec     # GUI 入口 + PyInstaller onedir
tests/                    # test_core.py + test_extra.py

알려진 제한 사항

• Python 3.8에서는 이 서비스를 실행할 수 없습니다(fastmcp는 3.10+ 필요); 로직 모듈은 3.8과 호환되며, python tests/test_core.py로 자체 점검 가능합니다.

• Cloudflare Tunnel 기본 요청 시간 초과는 약 100초입니다. run_command는 SSE 스트리밍 방식; 총 시간 초과 상한은 3600초입니다.

• 단일 작업 공간만 지원합니다. 다중 작업 공간 전환 및 세션 수준 컨텍스트는 아직 구현되지 않았습니다(YAGNI).

• 패키징: pip install -r requirements-build.txt && pyinstaller start.spec, 결과물 dist/start/start.exe. GUI에서 수동으로 「서비스 시작」을 클릭해야 합니다.