local-code-agent

FastMCP 기반으로 개발된 로컬 MCP 서버: 외부 AI(ChatGPT, Claude 등)가 HTTP를 통해 로컬 작업 공간을 원격으로 제어할 수 있도록 합니다(파일 읽기/쓰기/편집, 검색, 셸 명령, Git 작업). 또한 샌드박스 격리, 민감 파일 보호 및 감사 로그를 제공합니다.

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

환경 요구 사항

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

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

Related MCP server: OpenAI Secure MCP Tunnel

빠른 시작

방법 1: 그래픽 인터페이스 (권장)

python start.py

콘솔 창 조작 단계:

1. 작업 공간 폴더: 「선택…」을 클릭하여 폴더를 지정합니다. AI의 모든 작업은 해당 폴더 내로 제한됩니다(샌드박스). 폴더를 변경하면 샌드박스 루트가 전환됩니다.

2. 연결 프롬프트: 창 중간에 「연결 프롬프트」 카드가 있습니다. 그 안의 텍스트를 복사하여 웹 페이지 AI에 보내면, AI가 해당 구성에 따라 이 MCP 서버에 바인딩됩니다(토큰 불필요).

3. 포트: 기본값 8000; 충돌 시 변경 가능합니다.

4. 읽기 전용 모드: 체크하면 쓰기/편집/명령 도구가 모두 거부되며, 실행 중 전환 시 즉시 적용됩니다.

5. 「서비스 시작」 클릭 → 상태 표시줄에 버전, 읽기 전용 상태, 작업 공간, 실행 시간이 표시되고, 로그 영역에 서비스 로그가 실시간으로 출력됩니다.

6. 중지: 「서비스 중지」를 클릭하거나 창을 직접 닫습니다(먼저 확인 메시지가 표시됨).

방법 2: 명령줄

# 1. 安装依赖
pip install -r requirements.txt

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

선택적 매개변수: --workspace D:\projects\my-project (샌드박스 루트 디렉터리), --host 0.0.0.0 (로컬 네트워크 액세스 허용), --port 9000. 중지는 Ctrl+C를 사용합니다.

확인 및 상태 점검

서비스 시작 후 접속: GET http://127.0.0.1:8000/health (인증 불필요). 반환:

{ "status": "ok", "service": "local-code-agent", "version": "0.1.0",
  "workspace": "D:\\projects\\my-project", "readonly": false,
  "uptime_seconds": 3 }

나머지 엔드포인트(/mcp 포함)는 인증 없이 직접 접근 가능합니다.

로컬 네트워크 액세스

기본적으로 127.0.0.1만 수신하므로, 본 기기에서만 연결 가능합니다. 동일 로컬 네트워크의 다른 기기에서 접속하려면:

python server.py --host 0.0.0.0

클라이언트 연결 주소: http://<본기기_로컬_네트워크_IP>:8000/mcp (본기기 IP는 ipconfig로 확인). 로컬 네트워크에 노출하면 동일 네트워크 세그먼트의 모든 기기가 인증 없이 접근할 수 있으므로 주의해야 합니다.

공용 네트워크에 직접 노출하는 것은 권장하지 않습니다. 공용 네트워크 접근이 필요한 경우, 자체 리버스 프록시 솔루션(Nginx + TLS, frp 또는 기타 터널 도구)을 준비하고, 리버스 프록시 계층에서 HTTPS와 인증을 강제하십시오.

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

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

python start.py

콘솔 기능:

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

• 연결 프롬프트: 내장된 편집 가능한 프롬프트 텍스트가 있으며, 「프롬프트 복사」를 클릭하여 한 번에 복사한 후 웹 페이지 AI에 보내면 MCP 바인딩이 완료됩니다. 토큰이 필요 없습니다.

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

• 서비스 시작 / 중지: GUI 프로세스 내에서 FastMCP를 시작합니다(백그라운드 스레드 + uvicorn). 독립적인 로그 핸들러를 사용하며, 중지 시 서비스 스레드가 완료될 때까지 기다립니다.

• 실행 중 전환: 작업 공간을 변경하거나 읽기 전용을 체크하면 재시작 없이 즉시 적용됩니다. 포트 변경은 서비스 재시작이 필요합니다.

• 상태 표시줄: /health를 폴링하여 버전, 읽기 전용 상태, 현재 작업 공간, 실행 시간을 표시합니다.

• 로그 영역: 서비스 출력을 실시간으로 표시하며, ANSI 이스케이프 코드를 자동으로 정리합니다. 마우스 오른쪽 버튼으로 복사 가능하며, 600줄 초과 시 자동으로 잘라냅니다.

GUI와 명령줄은 동일한 샌드박스 및 감사 메커니즘을 공유합니다. 연결 방식도 동일합니다.

클라이언트 연결

로컬 기기 클라이언트: URL에 http://127.0.0.1:8000/mcp 입력; 로컬 네트워크 클라이언트는 http://<본기기_로컬_네트워크_IP>:8000/mcp 사용(서버는 --host 0.0.0.0으로 시작해야 함). 인증이 필요 없습니다.

Claude Desktop의 claude_desktop_config.json:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

도구 목록

보안 모델

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

• 인증: 토큰 인증이 없습니다. 서비스는 기본적으로 본 기기 127.0.0.1만 수신합니다. 외부에 노출해야 하는 경우 리버스 프록시 계층에서 직접 인증을 추가하십시오.

• 위험 작업 확인: Git 커밋은 요청 헤더 x-confirm: true가 있어야 실행됩니다.

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

• 다운로드: 모든 HTTP(S) 호스트 지원; 리디렉션 금지; 50MB 초과 시 중단하고 불완전한 파일 삭제.

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

• 읽기 전용 모드: python server.py --readonly 또는 GUI 체크. 쓰기/명령 도구는 여전히 표시되지만 호출 시 read-only mode 반환. 실행 중 전환 가능.

구성 우선 순위

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

프로젝트 구조

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # HTTP(S) 下载（无域名白名单）
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
runtime.py                # 运行时只读标志
gui/                      # tkinter 控制台（进程内服务）
start.py                  # GUI 入口
tests/                    # test_core.py + test_extra.py

알려진 제한 사항

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

• run_command는 SSE 스트리밍 출력이며, 총 타임아웃 상한은 3600초입니다.

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