deepseek-mcp

Claude Code가 저장소 작업의 경계가 정해진 한 단위를 로컬 하위 에이전트로서 DeepSeek에 위임할 수 있게 해주는 MCP 서버입니다.

Claude는 오케스트레이터 역할을 유지합니다. 범위, 아키텍처, 정확성을 결정합니다. DeepSeek은 토큰을 많이 소모하는 부분, 즉 저장소 탐색, 일상적이거나 반복적인 변경, 테스트 실행을 단일 승인된 작업 공간 안에서 엄격한 예산 하에 수행하는 실행 워커입니다.

핵심은 동일한 컨텍스트에 대해 두 번 비용을 지불하지 않도록 하는 것입니다. Claude가 하위 시스템을 읽고 DeepSeek이 다시 읽는다면 절약되는 것이 없습니다. 따라서 위임 결정은 광범위한 읽기 이전에 이루어져야 합니다.

User
 ↓
Claude: plan + define goal/scope
 ↓
DeepSeek: inspect repo + read code + implement + test
 ↓
DeepSeek: compact structured summary
 ↓
Claude: review diff/results + final answer

DeepSeek은 기본 저장소 워커이고, Claude는 오케스트레이터입니다. Claude는 계획을 세우고, 아키텍처 및 보안 관련 결정을 내리며, 반환된 diff를 검토하고, 최종 답변을 작성합니다. DeepSeek은 저장소 작업, 즉 탐색, Glob/Grep/Read, 코드 이해, 구현, 테스트, 일상적인 수정을 수행합니다. Claude는 소스 파일을 광범위하게 읽기 전에 위임하며, DeepSeek은 승인된 범위 내에서 관련 파일을 스스로 발견하고 간결한 구조화된 요약을 반환합니다. Claude는 파일 내용을 전송하지 않습니다.

Python 3.11+와 DeepSeek API 키가 필요합니다. 런타임 의존성은 하나뿐입니다: MCP SDK. 나머지는 모두 표준 라이브러리입니다. 검색에는 ripgrep이 있으면 사용되고, 없으면 순수 Python 스캔이 사용됩니다.

1. 설치

이 패키지는 아직 PyPI에 게시되지 않았으므로 체크아웃에서 설치합니다. 한 번, 전역으로 설치하세요. 프로젝트 의존성이 아니며 모든 저장소에서 작동합니다.

git clone https://github.com/giaminhgist/DeepSeek_MCP.git
cd DeepSeek_MCP

uv tool install .          # recommended: isolated, and puts deepseek-mcp on PATH
# or
pipx install .
# or, into the current environment
pip install .

콘솔 스크립트가 제대로 인식되는지 확인합니다:

deepseek-mcp --version     # -> deepseek-mcp 0.1.0

명령어를 찾을 수 없다면 설치 디렉터리가 PATH에 없기 때문입니다. uv를 사용하는 경우 uv tool update-shell을 실행하고 새 셸을 여세요.

인수 없이 deepseek-mcp를 실행하면 stdio에서 MCP 서버가 시작됩니다. Claude Code가 실행하는 것이 바로 이것이며, 일반적으로 직접 호출할 일은 없습니다.

Related MCP server: claude-code

2. API 키 설정

키는 https://platform.deepseek.com/에서 받으세요. 절대 프로젝트 저장소에 넣지 마세요. 셸 프로필에서 내보내세요:

export DEEPSEEK_API_KEY="sk-your-key-here"     # ~/.bashrc, ~/.zshrc, …

# Windows PowerShell
setx DEEPSEEK_API_KEY "sk-your-key-here"

그런 다음 서버가 키를 볼 수 있는지 확인합니다:

deepseek-mcp --check       # prints a health report as JSON; exits 1 if unusable

--check는 키를 읽을 수 있을 때 "mode": "enabled"와 "status": "ok"를 출력합니다. 키 자체는 보고서에 절대 나타나지 않습니다.

지원되는 세 가지 키 소스(우선순위 순):

1. 서버 환경의 DEEPSEEK_MCP_API_KEY 또는 DEEPSEEK_API_KEY.

2. 사용자 구성 파일의 api_key_env로, 읽을 다른 환경 변수를 지정합니다.

3. 사용자 구성 파일의 api_key — 허용되지만 권장되지 않으며, 키를 디스크에 저장하므로 시작 시 경고가 발생합니다.

나머지는 모두 선택 사항입니다. 구성 참조를 참조하세요. 미리 알아두면 좋은 또 다른 변수는 DEEPSEEK_MCP_WORKSPACE로, 승인된 프로젝트 루트를 자동 탐색 대신 고정합니다(작업 공간 참조).

3. Claude Code에 서버 추가

Claude Code가 상속하는 환경에 DEEPSEEK_API_KEY가 이미 내보내져 있다면:

claude mcp add deepseek --scope user -- deepseek-mcp

그렇지 않은 경우(예: 셸 프로필을 읽지 않는 데스크톱 실행) 명시적으로 전달하세요:

claude mcp add deepseek --scope user -e DEEPSEEK_API_KEY=sk-your-key-here -- deepseek-mcp

--scope user는 모든 프로젝트에 등록합니다. 현재 프로젝트에만 등록하려면 --scope local을 사용하세요.

수동으로 작성한 동등한 구성:

{
  "mcpServers": {
    "deepseek": {
      "command": "deepseek-mcp",
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key-here"
      }
    }
  }
}

키가 이미 상속된 환경에 있다면 env 블록을 완전히 생략하세요. 어떤 저장소 파일에도 키를 커밋하지 마세요.

4. 연결 확인

claude mcp list            # deepseek should be listed and connected

그런 다음 Claude Code 내부에서:

• /mcp를 실행하세요 — deepseek가 두 개의 도구와 함께 나타나야 합니다;

• Claude에게 deepseek_health를 호출하도록 요청하세요. 정상 작동하는 서버는 status: "ok", mode: "enabled", 기본 model과 allowed_models 허용 목록, 확인된 작업 공간 루트, 활성화된 기능, 예산 한도, 그리고 이 서버 프로세스에 대한 워커의 누적 합계가 담긴 usage 객체로 응답합니다.

키가 구성되지 않아도 서버는 여전히 시작되고 deepseek_health에 응답합니다 — status: "error", mode: "disabled"로 보고합니다 — 따라서 문제를 Claude Code 내부에서 진단할 수 있습니다. 이 상태에서는 어떤 작업도 수행하지 않습니다.

5. 문제 해결

로그는 event key=value 레코드로 stderr에 기록되며 stdout에는 절대 기록되지 않습니다. DEEPSEEK_MCP_LOG_LEVEL=DEBUG로 상세 수준을 높이거나 DEEPSEEK_MCP_LOG_FILE=/absolute/path.log로 파일에 기록할 수 있습니다.

도구 표면

의도적으로 두 개의 도구만 있습니다.

deepseek_health

구성 및 상태: 상태, 기본 model과 allowed_models 허용 목록, 승인된 작업 공간 루트와 해석 방식, 활성화된 기능, 예산 한도, 그리고 이 서버 프로세스에 대한 워커의 누적 합계가 담긴 usage 객체. 비밀 정보는 없습니다. 워커가 사용 가능한지 확인하고 위임을 보내기 전에 규모를 가늠하는 데 사용하세요.

delegate_to_deepseek

산문 덩어리가 아닌 구조화된 계약으로서의 경계가 정해진 작업 한 단위:

{
  "objective": "Treat a None row as invalid and cover it with a test.",
  "scope": ["src/importer/**", "tests/importer/**"],
  "constraints": ["Do not change the public response schema."],
  "acceptance_criteria": ["validate_row(None) returns False."],
  "verification": [["pytest", "tests/importer", "-q"]],
  "mode": "write"
}

그런 다음 워커는 스스로 반복합니다 — glob, grep, read, edit, run, repair — 그리고 대화 기록이 아닌 간결한 결과를 반환합니다:

{
  "status": "completed",
  "summary": "Treated a None row as invalid and added a regression test.",
  "changed_files": ["src/importer/validate.py"],
  "created_files": ["tests/importer/test_none.py"],
  "deleted_files": [],
  "inspected_files": ["src/importer/__init__.py"],
  "verification": [
    {"argv": ["pytest", "tests/importer", "-q"], "exit_code": 0, "summary": "24 passed"}
  ],
  "warnings": [],
  "unresolved": [],
  "assumptions": [],
  "diff_stat": " src/importer/validate.py | 3 ++-",
  "metrics": {
    "turns": 7, "tool_calls": 12, "prompt_tokens": 18400,
    "completion_tokens": 2100, "duration_seconds": 41.2,
    "files_read": 4, "files_changed": 2, "compactions": 0
  },
  "session_usage": {
    "delegations": 3, "turns": 19, "tool_calls": 31,
    "prompt_tokens": 51200, "completion_tokens": 6400,
    "total_tokens": 57600, "since": "server start"
  },
  "model": "deepseek-chat",
  "analysis": {
    "important_files": ["src/importer/validate.py"],
    "architecture_notes": ["validate_row is the single entry point for row checks."],
    "dependencies": ["src/importer/schema.py"],
    "suggested_scope": ["src/importer/**", "tests/importer/**"],
    "risks": ["Changing the None handling may affect callers that rely on the old behaviour."]
  },
  "debug_ledger": ["R src/importer/validate.py", "E src/importer/validate.py", "X pytest tests/importer -q"]
}

model은 작업별 재정의 해석 후 실제로 위임을 실행한 모델입니다. analysis는 위임이 요청한 경우에만 존재하며 다섯 개의 저장소 맵 필드를 담습니다. debug_ledger는 도구 호출당 한 줄씩 기록되는 간결한 실행 원장으로, 서버가 debug 활성화 상태로 실행될 때만 채워집니다. metrics는 이 위임 자체의 토큰 사용량과 형태를 보고합니다. session_usage는 이 위임을 포함한 이 서버 프로세스의 워커 누적 합계를 담습니다 — delegations, turns, tool_calls, prompt_tokens, completion_tokens, total_tokens, 그리고 since(항상 리터럴 "server start").

usage와 session_usage 뒤의 카운터는 인메모리이며 서버 프로세스에 한정됩니다. MCP 서버가 재시작되면 초기화되는데, 이것이 바로 since 필드가 기록하는 내용입니다. 디스크에 영속화되지 않습니다. 워커에 도달한 위임만 카운트됩니다. 더 일찍 거부된 요청(서버 비활성화, 잘못된 요청 필드, 또는 allowed_models 허용 목록에 없는 모델)은 모델을 호출한 적이 없으므로 delegations나 토큰 수를 증가시키지 않습니다. total_tokens는 저장되는 것이 아니라 구성 요소에서 계산되므로 어긋날 수 없습니다.

상태: completed, partial, blocked, failed, budget_exceeded, disabled. 예상되는 실패(잘못된 구성, 거부된 경로, 거부된 명령, 소진된 예산, 공급자 오류)는 모두 이유와 함께 이 중 하나로 반환됩니다. Python traceback이 반환되는 경우는 없습니다.

결과에는 결론이 담기며, 원시 Read/Grep/도구 기록은 담기지 않습니다. 디버그 원장은 컴팩트 원장입니다. 즉, 도구 호출당 한 줄이며, 디버그가 활성화된 경우에도 도구 출력이 아닙니다.

모드는 좁혀질 뿐 넓혀지지 않습니다

모드는 서버의 구성된 기능과 교차(intersect)됩니다. 서버가 허용하는 것보다 더 많은 것을 요청하는 요청은 API 호출 전에 거부됩니다. 정책을 넓힐 수 없습니다.

워커가 신뢰받지 못하는 두 가지

결과에서 모델로부터 오지 않는 두 가지가 있습니다:

• 변경된 파일 목록은 도구 감시와 실행 전에 찍은 스냅샷에 대한 git status 비교에서 비롯되므로, 사용자의 기존 미커밋 편집이 워커의 작업으로 보고되지 않습니다.

• 상태. 요청된 검증이 실행되지 않았거나 0이 아닌 코드로 종료된 경우, 주장된 completed는 partial로 강등됩니다. failed와 budget_exceeded는 서버의 판정이며 워커가 전혀 주장할 수 없습니다.

그래도 검증하세요. git status --short, git diff --stat를 실행한 다음, 위험 비율에 따라 변경된 헹크를 읽으십시오. completed는 주장이지 증명이 아닙니다.

예산

모든 위임에는 한도가 있으며, 실행은 초과하는 대신 구조화된 이유와 함께 중단됩니다: 턴(24), 도구 호출(80), 벽시계(15분), 도구 호출당 출력(20,000자), Read 창(250줄), Grep 일치(100), Glob 경로(300), 추정 활성 컨텍스트(96,000토큰).

컨텍스트는 커져가는 기록이 아니라 예산이 책정된 리소스로 취급됩니다. 임계값 이상에서는 오래된 도구 페이로드가 결정적 실행 원장의 한 줄 항목으로 대체됩니다. 그것으로 충분하지 않으면, 원장이 수행한 작업을 여전히 기록하므로 전체 오래된 턴이 삭제됩니다. 시스템 프롬프트, 원래 작업 계약, 최근 턴, 원장은 항상 보존됩니다. 요약에 추가 모델 호출이 소비되는 일은 없으며, 워커가 삭제된 세부 정보가 필요하면 파일을 다시 읽습니다.

모든 제한은 구성 가능하며 deepseek_health에 의해 보고됩니다.

구성 참조

reserved로 표시된 설정은 시작 시 검증되지만 아직 사용되지는 않습니다.

우선순위

환경 변수 > 사용자 구성 파일 > 내장 기본값

모델 선택에는 그 위에 한 단계가 더 있습니다: 단일 위임이 자체 모델을 지정할 수 있으므로 전체 순서는

작업별 모델 > 환경 변수 > 사용자 구성 파일 > 내장 기본값

작업별 모델은 delegate_to_deepseek의 model 매개변수입니다. 서버의 allowed_models가 비어 있지 않으면 허용 목록이며, 다른 것을 지정하는 요청은 API 호출 전에 blocked로 거부됩니다. 모델 선택은 운영자가 허용한 범위로 좁혀지며, 위임 모드가 서버의 기능으로 좁혀지는 것과 정확히 같습니다.

누락, 잘못된 형식, 또는 모순된 설정은 오류입니다. 서버는 더 넓은 작업 공간이나 더 관대한 정책으로 대체되지 않습니다.

구성 로드에 실패하면 프로세스는 여전히 시작되고 deepseek_health에 여전히 응답하지만, status: "error", mode: "disabled"를 보고하고 작업을 수행하지 않습니다. 명령줄에서 동일한 보고서를 보려면 deepseek-mcp --check를 실행하십시오.

구성 파일 위치

사용자 구성 파일은 모든 프로젝트 외부에 있습니다:

DEEPSEEK_MCP_CONFIG는 경로를 재정의합니다. 설정되어 있고 파일이 존재하지 않으면 기본값을 조용히 사용하는 대신 시작이 실패합니다. 기본 위치에 구성 파일이 없는 것은 괜찮습니다. 빈 파일도 괜찮습니다. 알 수 없는 키는 오류입니다.

구성 파일 스키마

모든 키는 선택 사항입니다.

{
  "model": "deepseek-chat",
  "allowed_models": ["deepseek-chat", "deepseek-reasoner"],
  "base_url": "https://api.deepseek.com/v1",
  "api_key_env": "DEEPSEEK_API_KEY",
  "workspace": "/absolute/path/to/project",
  "tools": {
    "enabled": ["Read", "Glob", "Grep", "Edit", "Write", "Run"],
    "max_write_bytes": 2000000,
    "allow_secret_paths": false,
    "secret_path_exceptions": []
  },
  "provider": {
    "timeout_seconds": 120,
    "max_retries": 3,
    "retry_base_delay": 0.5,
    "retry_max_delay": 8.0,
    "temperature": 0.0,
    "max_output_tokens": 4096
  },
  "budgets": {
    "max_turns": 24,
    "max_tool_calls": 80,
    "max_wall_seconds": 900,
    "max_tool_output_chars": 20000,
    "read_window_lines": 250,
    "max_grep_matches": 100,
    "max_glob_paths": 300,
    "max_context_tokens": 96000,
    "compaction_threshold_ratio": 0.7
  },
  "commands": {
    "default_timeout_seconds": 120,
    "max_timeout_seconds": 600,
    "extra_denied_executables": [],
    "extra_allowed_executables": [],
    "allow_unsafe_shell": false
  },
  "logging": { "level": "INFO", "file": null, "log_task_text": false },
  "debug": false
}

api_key 키는 여기서 허용되지만 권장되지 않습니다. 키를 디스크에 두고 시작 경고를 생성하기 때문입니다. 대신 읽을 환경 변수의 이름을 지정하는 api_key_env를 선호하십시오.

allowed_models는 위임이 요청할 수 있는 모델 이름의 선택적 허용 목록입니다. 비어 있지 않으면 구성된 model이 그 안에 있어야 하며(그렇지 않으면 설정이 서로 모순됨), 그 밖의 것을 지정하는 작업별 model은 API 호출 전에 blocked로 거부됩니다. 비어 있으면 모든 잘 구성된 모델 이름이 허용됩니다.

자격 증명 및 엔드포인트

API 키가 없으면 작업이 없습니다: 시작 시 서버가 비활성화된 것으로 보고합니다.

작업 공간

명시적 작업 공간이 없으면 프로세스 작업 디렉터리에서 위로 올라가며 .git, .hg, .svn, pyproject.toml, package.json, go.mod 또는 Cargo.toml을 찾아 루트를 발견합니다. 찾지 못하면 작업 디렉터리 자체가 사용되고 경고가 기록됩니다.

존재하지 않거나, 읽을 수 없거나, 디렉터리가 아니거나, 상대 경로이거나, 파일 시스템 루트인 명시적 작업 공간은 시작 오류입니다. 작업 디렉터리로 절대 대체되지 않습니다. 서버는 프로젝트 안에 있을 필요가 없으며, 활성화를 위해 프로젝트를 수정하지 않습니다.

도구

기본 활성화 도구는 NotebookEdit을 제외한 전부입니다. NotebookEdit은 아직 구현이 없는 인식된 이름이므로, 활성화하면 워커에게 제공되지만 사용할 수 없는 도구가 아니라 시작 오류입니다. Read는 필수입니다.

.git, .hg, .svn 내부는 파일 시스템 도구를 통해 읽거나 쓸 수 없습니다. 대신 Run을 통해 읽기 전용 git 명령을 사용하십시오.

예산 제한

모든 제한은 위임별로 적용되며 deepseek_health에 의해 보고되므로 Claude는 위임을 보내기 전에 크기를 조정할 수 있습니다.

예산 초과는 이미 반영된 작업을 보고한 후 status: "budget_exceeded"와 이유로 위임을 종료합니다.

공급자

타임아웃, 연결 실패, 429 및 5xx는 재시도됩니다. 4xx는 즉시 표시되는데, 잘못된 키나 잘못된 요청을 재시도하는 것은 시간 낭비일 뿐이기 때문입니다. 리다이렉트는 완전히 거부되어 Authorization 헤더가 다른 호스트로 재전송될 수 없습니다.

명령 정책

Run은 shell=False로 argv 배열을 실행합니다. 실행 파일은 허용 목록에 있어야 하며, 위험한 하위 명령은 구조적으로 거부됩니다. 구성 파일의 commands.extra_allowed_executables를 사용하여 프로젝트별 도구를 추가하고, extra_denied_executables를 사용하여 하나를 제거할 수 있습니다. 추가 허용 항목은 하드 거부된 프로그램을 다시 활성화할 수 없습니다.

기본적으로 거부되는 항목: 권한 상승, 패키지 설치, 게시, 네트워크 유틸리티, 셸 및 인라인 코드 인터프리터, 파괴적인 파일 시스템 작업, 인플레이스 편집기, 그리고 변경 또는 원격 git 하위 명령. 읽기 전용 git(status, diff, log, show, ls-files, rev-parse, blame, …)은 허용됩니다.

cat, head, grep과 같은 범용 파일 읽기 도구는 의도적으로 허용 목록에 포함되지 않습니다. 이들은 Read, Glob, Grep이 적용하는 비밀 경로 거부 목록을 한 번의 명령으로 우회할 수 있기 때문입니다. 이를 수용할 경우에만 extra_allowed_executables를 통해 다시 추가하십시오.

로깅

위임 로깅은 메타데이터 전용입니다: 이벤트 이름, 상태, 모드, 턴 및 도구 호출 횟수, 토큰 수, 지속 시간, 파일 수. 작업 텍스트, 파일 내용, 명령 출력 또는 프롬프트 본문은 포함되지 않습니다. 로그는 stderr로만 전송되며 stdout으로는 절대 전송되지 않습니다 — stdout은 MCP 프로토콜 트래픽만 전달합니다. API 키는 백스톱으로 모든 레코드에서 삭제됩니다.

보안 태세

워커를 무엇에 연결할지 결정하기 전에 이 섹션을 읽으십시오.

여기에 설명된 보호 기능은 모델 선택 및 분석 기능에 의해 변경되지 않습니다: 압축을 통한 제한된 컨텍스트, 작업 공간 샌드박스, 명령 허용 목록, 커밋 또는 푸시 없음, 기본적으로 패키지 설치 또는 네트워크 액세스 없음, 그리고 토큰 및 도구 메트릭을 전달하는 구조화된 결과.

코드로 강제되는 사항:

• 모든 경로는 하나의 작업 공간 루트에 대해 확인됩니다. 심볼릭 링크는 먼저 추적된 후 그 결과가 검증되므로, 트리 밖으로 연결되는 링크는 거부됩니다. 쓰기 대상은 쓰기 직전에 상위 디렉터리가 다시 검증됩니다.

• 명시적으로 구성된 작업 공간이 없거나 사용할 수 없으면 시작 오류입니다. 더 넓은 디렉터리로 조용히 폴백되지 않습니다.

• 비밀을 포함하는 경로(.env, .env.*, *.pem, *.key, id_rsa, .netrc, .ssh/, .aws/ 등)와 .git/.hg/.svn 내부는 모든 도구에 대해 거부되며, 단순히 읽을 수 없는 것이 아니라 검색 결과에서도 제외됩니다.

• 위임의 scope는 쓰기를 제한합니다. 읽기는 작업 공간 전체에 걸쳐 열려 있는데, 워커가 작업을 수행하려면 탐색해야 하기 때문입니다.

• Run은 shell=False를 사용합니다. 셸이 없으므로 &&, |, $(...), >는 리터럴 인수 텍스트로 도착하며 두 번째 명령을 연결할 수 없습니다. 실행 파일은 허용 목록에 있어야 하고, 위험한 하위 명령은 argv에 대해 구조적으로 거부되며, 절대 경로 인수는 작업 공간 내부에 있어야 하고, 기존 거부 경로를 지정하는 인수는 거부됩니다.

• 패키지 설치, 게시, 네트워크 유틸리티, 권한 상승, 변경 또는 원격 git 하위 명령은 기본적으로 거부됩니다. cat 및 grep과 같은 범용 파일 읽기 도구도 마찬가지인데, 이들은 비밀 경로 거부 목록을 한 번의 명령으로 우회할 수 있기 때문입니다.

• 하위 프로세스는 자격 증명이 제거된 환경을 받으므로 워커 자체의 API 키가 명령 출력이나 로그에 표시될 수 없습니다.

• 쓰기는 원자적입니다(임시 파일, fsync, rename). 따라서 중단된 쓰기는 원본 파일을 그대로 둡니다. Edit는 Read가 반환한 SHA-256을 요구할 수 있으므로 오래된 편집은 적용되지 않고 거부됩니다.

• 시스템 프롬프트는 저장소 콘텐츠가 데이터이지 명령이 아니라고 명시하며 — 위의 제한은 서버 측에서 강제되므로 — 워커에게 지침을 무시하라고 지시하는 파일이 아무것도 부여할 수 없습니다.

• 로그는 기본적으로 메타데이터 전용입니다: 이벤트, 상태, 횟수, 지속 시간. 작업 텍스트, 파일 내용, 명령 출력 또는 프롬프트 본문은 없습니다. API 키는 백스톱으로 모든 레코드에서 삭제됩니다.

이것이 아닌 것: OS 수준의 적대적 샌드박싱.

이것은 애플리케이션 수준 정책입니다. 혼란스럽거나, 실수하거나, 프롬프트 주입된 워커가 취할 수 있는 행동의 범주를 제한합니다. 결심한 적대자에 대한 격리 경계가 아니며, 둘은 동일하지 않습니다.

구체적으로:

• 허용된 테스트 실행기는 프로젝트의 코드를 실행합니다. pytest는 저장소를 가져오고, make test는 Makefile이 지정하는 것을 실행합니다. 그렇게 도달할 수 있는 모든 것은 도달 가능하며, 경로 정책이 거부했을 파일도 포함합니다.

• 프로세스, 파일 시스템 또는 네트워크 격리가 없습니다 — 컨테이너, bubblewrap 또는 seccomp, macOS 샌드박스 프로필, Windows 작업 개체, 네트워크 네임스페이스가 없습니다. 허용된 명령은 서버 프로세스와 동일한 권한으로 실행됩니다.

• 거부 목록은 완전한 것이 아니라 구조적입니다. 이것이 실행 파일 정책이 허용 목록인 이유입니다: 알 수 없는 프로그램은 안전하다고 가정하는 대신 거부됩니다.

테스트를 실행하지 않을 저장소에 이것을 연결하지 말고, diff 검토를 대체하는 것으로 취급하지 마십시오.

알려진 제한 사항

• NotebookEdit은 구현이 없는 인식된 도구 이름입니다. 이를 활성화하면 워커에게 제공되지만 사용할 수 없는 도구가 되는 대신 시작 오류가 됩니다.

• commands.allow_unsafe_shell은 검증되지만 아무것도 하지 않습니다. 원시 셸 실행이 없습니다.

• 워커는 파일을 삭제할 수 없습니다. 삭제 도구가 없으며 rm은 거부됩니다.

• 위와 같이 OS 수준 샌드박스가 없습니다.

• 컨텍스트 추정은 문자 휴리스틱이며, 공급자가 보고한 사용량에 따라 상향 보정됩니다. 의도적으로 보수적이며 정확하지 않습니다.

• 정규식 방언이 다르기 때문에 검색 동작은 ripgrep 엔진과 순수 Python 엔진 간에 약간 다릅니다. 사용된 엔진은 모든 결과에 명시됩니다.

• Windows는 지원되고 CI에서 테스트되지만, 타임아웃 시 프로세스 그룹 종료는 POSIX에 비해 최선의 노력입니다.

• 호출당 위임은 한 번에 하나입니다. 백그라운드 작업, 영구 워커 메모리, 자동 git 커밋 또는 푸시가 없습니다.

개발

uv venv && uv pip install -e ".[dev]"
python -m pytest          # the full suite; no API key and no network needed
python -m ruff check .
python -m ruff format --check .
python -m mypy

테스트 스위트는 유료 API를 호출하지 않습니다. 스크립트된 가짜 공급자가 대신하며, MCP 통합 테스트는 stdio를 통해 임시 git 저장소에 대해 실제 서버 하위 프로세스를 구동합니다.

phases/는 이 서버가 구축된 구현 순서를 담고 있으며 참고용으로 유지됩니다.

GLOBAL_CLAUDE.md는 이 코드베이스의 일부가 아닙니다. 언제 위임할지를 설명하는 사용자 수준 Claude Code 지침 파일입니다 — ~/.claude/CLAUDE.md에 복사하거나 이미 있는 파일에 병합하십시오.

라이선스

MIT.