DevTwin MCP

AI 코딩 에이전트에게 로컬 개발 환경에 대한 실시간 구조화된 이해를 제공합니다.

DevTwin은 AI 코딩 에이전트의 핵심 질문 하나에 답하는 Model Context Protocol(MCP) 서버입니다: 이 개발자의 환경이 왜 다르거나, 고장났거나, 비정상인가?

프로젝트 기술 스택을 감지하고, 설치된 런타임 버전을 프로젝트가 실제로 요구하는 버전과 대조하며, 의존성 및 잠금 파일 상태를 검사하고, 필요한 로컬 서비스(Postgres, Redis 등)와 해당 서비스의 실행 여부를 찾아내며, 포트와 Git 상태를 확인하고, 이 모든 것을 구조화된 증거 기반 진단으로 변환합니다 -- 환경을 클라우드 백엔드로 전송하지 않으며, 비밀 값을 모델에 노출하지도 않습니다.

목차

• DevTwin이 존재하는 이유

• FAQ: Claude CLI에는 이미 셸이 있는데 왜 MCP가 필요한가?

• 이점

• 토큰 비용

• 솔직한 트레이드오프

• DevTwin 유무 비교: 실제 사례

• 이를 통해 가능해지는 질문 예시

• 언어별 예시

• 아키텍처

• 지원 생태계

• 설치

• MCP 클라이언트 구성

• 다른 프로젝트에서 사용하기

• 도구 참조

• 보안 모델

• 개인정보 보호 모델

• 로컬 우선 아키텍처

• 개발

• 기여

• 로드맵

• 라이선스

DevTwin이 존재하는 이유

• AI 코딩 에이전트는 코드를 잘 읽지만, 코드가 실제로 실행되는 환경에 대해서는 알지 못합니다.

• "내 컴퓨터에서 npm test가 왜 실패하지?"라는 질문은 대개 코드와는 무관합니다 -- Node 버전 불일치, 실행 중이지 않은 서비스, 또는 설치되지 않은 의존성 때문입니다.

• DevTwin은 에이전트에게 시니어 엔지니어가 직접 수집하는 것과 동일한 신호 -- node --version, git status, lsof -i :5432, docker ps -- 를 추측이 아닌 구조화된 도구 호출로 제공합니다.

FAQ: Claude CLI에는 이미 셸이 있는데 왜 MCP가 필요한가?

이것은 보통 개발자가 가장 먼저 묻는 질문이며, 타당한 질문입니다. 이미 Bash 도구가 있는 Claude Code와 같은 클라이언트에서는 node --version, docker ps, lsof -i :5432 등을 직접 실행하라고 요청하면 됩니다 -- MCP 서버가 필요 없습니다. DevTwin이 해결하는 격차는 "이것이 아예 가능한가"의 문제가 아니라 다음과 같습니다:

Claude CLI에 대한 솔직한 답변: 이미 Bash가 있으므로 DevTwin의 이점은 "없던 기능"보다는 안전성 보장과 일관된 구조화된 출력입니다 -- 완전히 새로운 접근 권한이 아닙니다. 이것이 무료가 아닌 이유이기도 합니다 -- 연결 시 실제 비용과 가치가 있는 시점은 토큰 비용을 참조하세요.

도입 전에 물어볼 만한 몇 가지 추가 질문:

"이것은 단지 doctor 스크립트(make doctor, bin/setup)에 단계가 추가된 것 아닌가?" 개념적으로는 그렇습니다 -- 많은 성숙한 저장소가 이미 직접 작성하고 있습니다. DevTwin의 차별점은 대부분의 저장소에는 그런 것이 없고, 생태계별로 좋은 스크립트를 작성하는 것은 실제 작업이며, 그 출력은 사람이 읽는 일반 텍스트가 아니라 에이전트가 추론할 수 있는 구조화된 JSON이며, 프로젝트마다 각자의 규칙과 사각지대를 가진 맞춤 스크립트 대신 동일한 10개 도구가 모든 저장소에서 동일하게 작동한다는 점입니다.

"Claude / Claude Code에서만 작동하나요?" 아닙니다. DevTwin은 표준 Model Context Protocol을 사용합니다 -- 모든 MCP 호환 클라이언트(Claude Desktop, Cursor, Windsurf 등)가 동일한 방식으로 연결할 수 있습니다. Claude 전용 기능은 없습니다.

"의존해도 안전한가요 -- 활발히 유지관리되나요?" Alpha 상태이며 신생 프로젝트입니다 -- 의존하는 워크플로우에 적용하기 전에 코드를 읽어보세요(짧습니다). 다른 새로운 개발 도구 의존성과 마찬가지로 말입니다.

"잘못된 제안을 하거나 나쁜 권장 사항을 자동으로 실행할 수 있나요?" 여기서 어떤 도구도 recommendations 문자열을 실행하지 않습니다 -- 그것은 에이전트(또는 사용자)가 읽고 결정할 텍스트일 뿐입니다. dev_check만이 무언가를 실행하는 유일한 도구이며, 고정 허용 목록에 대해 스스로 인식한 명령만 실행합니다 -- 보안 모델 참조.

"어디로 전화를 걸거나 텔레메트리를 보내나요?" 아닙니다. 자체 네트워크 호출이 전혀 없습니다 -- 로컬 우선 아키텍처 참조.

"내 컴퓨터에서 어떤 명령도 실행하지 않는 MCP 서버를 원합니다." 10개 도구 중 9개는 순수 읽기 전용입니다(파일 읽기, 버전 확인). dev_check만 무언가를 실행하며, DevTwin이 프로젝트 파일에서 직접 인식한 명령만 허용 목록으로 검사하고 shell=False와 타임아웃으로 실행합니다 -- 정확히 무엇을 허용하고 허용하지 않는지는 보안 모델을 참조하세요.

이점

• 잘못된 진단 감소. DevTwin이 없으면 실패를 디버깅하는 에이전트는 코드를 읽고 추측할 수밖에 없습니다 -- 실제로는 Node 버전 불일치나 중지된 데이터베이스인 문제에 대해 코드 수정을 제안하는 경우가 많습니다. DevTwin은 추측 대신 실제 사실을 제공합니다.

• 여러 번 대신 한 번의 호출. 단일 dev_health 호출이 약 10개의 기본 검사(런타임 버전, 의존성 상태, 서비스, 포트, Git)를 하나의 구조화된 점수 결과로 묶습니다 -- 에이전트가 수십 번의 개별 셸 왕복을 하고 매번 원시 CLI 출력을 파싱하는 대신 말입니다.

• 매번 동일한 검사. 생태계별 정확한 검사(Gradle wrapper vs. 시스템 Gradle, .nvmrc vs. package.json engines 등)가 한 번에 인코딩되므로 에이전트가 우연히 실행할 명령에 의존하는 대신 세션 간에 일관된 진단이 가능합니다.

• 에이전트에 셸을 넘겨주는 것보다 안전. 임의 명령 실행이 없고 파괴적인 작업이 절대 없습니다 -- 보안 모델 참조.

• 비밀 값은 절대 다루지 않음. 비밀로 보이는 환경 변수는 존재 여부만 확인하며 값은 절대 읽거나 반환하지 않습니다 -- 개인정보 보호 모델 참조.

• 에이전트에 셸이 없는 곳에서도 작동. Bash 도구가 없는 MCP 클라이언트(일부 IDE 어시스턴트, 제한된 에이전트)도 이 기능을 전혀 못 쓰는 대신 사용할 수 있습니다.

토큰 비용

추정치가 아닌 실제 수치 -- 이 서버 자체의 MCP 도구 스키마(mcp.list_tools())와 실제 dev_health() 응답에서 직접 측정했으며, 표준 약 4문자-당-토큰 근사치를 사용했습니다.

토큰이 소비되는 두 가지 시점이 있으며 비용이 매우 다릅니다:

도구별 스키마 세부 내역(측정값):

솔직한 결론: 환경 질문을 전혀 다루지 않는 세션에서 단일 일회성 진단의 경우, 원시 Bash가 총 토큰에서 더 저렴할 수 있습니다 -- 약 1,400토큰의 고정 스키마 비용이 여러 셸 명령을 한 번의 호출로 대체하는 절약 효과를 능가하는 경우가 많습니다. 양쪽의 실제 수치에 대한 비교는 아래 작업 비교를 참조하세요.

DevTwin의 가치는 한 세션에서 환경 질문이 더 많이 나올수록 커집니다(고정 비용은 한 번만 지불하고 이후 질문마다 DevTwin은 약 150토큰인 반면 원시 Bash는 매번 수백 토큰 이상) -- 그리고 진정한 장점은 원시 토큰 수가 아니라 일관성, 안전성, 그리고 Bash 도구가 없는 MCP 클라이언트에서 작동한다는 점입니다. 이점 및 솔직한 트레이드오프 참조.

실질적 의미: DevTwin을 사용자 전체가 아닌 프로젝트별로 등록하여 고정 비용이 실제로 유용한 세션에서만 지불되도록 하세요 -- 다른 프로젝트에서 사용하기 참조.

솔직한 트레이드오프

DevTwin은 안정적인 환경을 위한 일상적인 도구가 아닙니다 -- 작성하는 모든 함수마다 "Postgres가 실행 중인지" 다시 확인할 필요는 없습니다. 비상용 도구입니다: 특정 순간(새 클론, 알 수 없는 빌드 실패, 커밋 직전)에 높은 가치를 제공하고 나머지 시간에는 유휴 상태입니다. 이것이 의도된 사용 패턴이지 단점이 아닙니다.

• 토큰 오버헤드는 연결되는 순간부터 매 턴마다 사용 여부와 관계없이 발생합니다. 실제 측정 수치는 토큰 비용을 참고하세요.

• 단발성 질문 하나에 대해서는 토큰 수에서 확실히 이기지 못합니다. 일관성, 안전성, 그리고 셸이 없는 클라이언트까지 도달할 수 있다는 점에서 이깁니다. 혜택 참고.

• 에이전트가 이미 완전히 통제하는 저장소에 전체 셸 접근 권한을 갖고 있고 환경 드리프트가 거의 없다면, DevTwin이 필요 없을 수도 있습니다.

• DevTwin이 가장 가치를 발휘하는 곳은: 공유/온보딩 저장소, 신뢰도가 낮거나 셸이 없는 에이전트 환경, 그리고 "무엇을 확인해야 할지" 자체가 어려운 멀티 에코시스템 모노레포입니다.

DevTwin 사용 시와 미사용 시: 실제 사례

에이전트에게 "npm test가 왜 실패하나요?"라고 묻는다고 가정해 보세요. 실제 원인은 Node 버전 불일치와 Postgres가 실행되고 있지 않기 때문입니다.

DevTwin 없이 (원시 Bash를 사용하는 에이전트) -- 올바른 명령 순서를 한 번에 하나씩 추측해야 합니다:

cat package.json                      # spot "engines": {"node": ">=20"}
node --version                        # v16.20.0 -- mismatch found
grep -i "pg\|postgres" package.json   # spot the Postgres dependency
cat .env                              # risk: may print a real secret into context
lsof -i :5432                         # nothing listening
docker ps                             # check if it's in a container instead

여섯 번의 왕복(round-trip), 에이전트가 스스로 만들어내야 했던 조사 경로, 4단계에서 비밀이 대화에 유출될 실제 가능성, 그리고 명령어 + 출력 텍스트 약 400-800 토큰 (파일 크기와 실행 중인 Docker 컨테이너 수에 따라 달라짐).

DevTwin과 함께라면, 한 번의 호출로:

dev_health()

{
  "status": "error",
  "summary": "2 issues found: runtime drift, service down",
  "issues": [
    "Node 16.20.0 installed, project requires >=20 (from package.json engines)",
    "Postgres required (found in docker-compose.yml) but not running on 5432"
  ],
  "recommendations": [
    "nvm install 20 && nvm use 20",
    "docker compose up -d postgres"
  ]
}

동일한 결론, 응답에 ~150 토큰 -- 게다가 해당 턴에 이미 지불된 ~1,400 토큰의 고정 스키마 비용까지 (토큰 비용 참고). 여섯 번 대신 한 번의 호출, 비밀 유출 가능성 없음, 그리고 세션마다 달라지는 임의 조사 대신 매번 동일하게 선별된 검사.

이 기능으로 가능해지는 질문 예시

• "내 개발 환경을 점검해 줘."

• "내 Kotlin 프로젝트가 빌드에 실패하는 이유는 무엇인가요?"

• "이 저장소에 맞는 Node 버전인가요?"

• "내 앱이 Postgres에 연결되지 않는 이유는 무엇인가요?"

• "내 환경이 이 저장소가 기대하는 것과 다른가요?"

• "커밋하기 전에 무엇을 실행해야 하나요?"

• "방금 이 저장소를 클론했는데, 실행하려면 무엇을 해야 하나요?"

언어별 예시

지원되는 에코시스템마다 한 행씩: 실제로 물어볼 질문, 답을 위해 DevTwin이 확인하는 항목, 그리고 dev_check에 대해 인식하는 테스트/빌드 명령어.

아키텍처

하나의 MCP 서버에 여러 에코시스템 어댑터가 있는 구조입니다. 언어마다 별도의 서버가 아닙니다.

MCP server -> core (workspace/detector/health/drift/diagnostics) ->
adapters (python/node/jvm/go/rust/dotnet/swift/ruby/php/generic) ->
system inspection (os/process/ports/env/fs/docker) ->
service detection (postgres/redis/generic)

자세한 내용은 docs/architecture.md에 있습니다. 새 언어 어댑터를 추가하는 방법: docs/adapters.md.

지원되는 에코시스템

특정 어댑터에 매칭되지 않는 프로젝트도 일반(generic) 어댑터에서 유용한 출력을 얻을 수 있습니다. DevTwin은 인식되지 않는 프로젝트에 대해 아무것도 반환하지 않는 법이 없습니다.

설치

uv pip install devtwin-mcp
# or
pip install devtwin-mcp

이 저장소를 클론한 뒤 로컬 개발을 진행하려면 docs/development.md를 참고하세요.

MCP 클라이언트 설정

정확한 설정 구문은 클라이언트마다 다릅니다. 클라이언트 문서를 확인하세요. 일반적으로 DevTwin은 stdio MCP 서버이며 다음과 같이 호출합니다:

{
  "mcpServers": {
    "devtwin": {
      "command": "devtwin"
    }
  }
}

클론에서 로컬 개발할 때(패키지를 설치하지 않고):

{
  "mcpServers": {
    "devtwin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/devtwin-mcp", "devtwin"]
    }
  }
}

MCP Inspector로 도구가 인식되는지 확인하세요:

npx @modelcontextprotocol/inspector uv run devtwin

다른 프로젝트에서 사용하기 (다른 개발자용)

DevTwin은 단일 바이너리입니다. 같은 설치에 원하는 수의 프로젝트를 연결할 수 있으며 프로젝트별 재설치가 필요 없습니다. 두 가지 범위(scope)가 있습니다:

프로젝트 범위 -- 프로젝트 루트에 .mcp.json을 넣으세요:

{
  "mcpServers": {
    "devtwin": {
      "command": "/absolute/path/to/devtwin-mcp/.venv/bin/devtwin"
    }
  }
}

또는 Claude Code CLI로:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope project

사용자 범위:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope user

추가한 후 클라이언트를 다시 시작하고(또는 MCP 서버를 다시 연결한 다음) 평소처럼 질문하면 됩니다. 이 기능으로 가능해지는 질문 예시 참고.

모노레포 팁: 여러 플랫폼이 섞인 저장소(예: Android + iOS + 백엔드)에서는 저장소 루트 대신 특정 하위 폴더를 대상으로 질문하세요. 예: "android/ 앱의 상태를 확인해 줘". 혼합 저장소 루트에서 dev_detect를 실행하면 발견한 모든 에코시스템을 보고하는데, 한 번은 유용하지만 특정 대상을 확인할 때는 너무 시끄럽습니다.

도구 참조

모든 도구는 {status, summary, data, issues, recommendations}를 반환합니다. status는 ok, warning, error, unknown 중 하나입니다.

보안 모델

• 임의 명령 실행 없음. execute_shell 도구는 존재하지 않습니다. dev_check는 DevTwin이 프로젝트 파일에서 직접 인식한 명령어만 실행하며, 허용 목록(allowlist)에 대해 검사되고 shell=False 및 타임아웃으로 실행됩니다.

• 파괴적 작업 절대 없음. DevTwin은 git reset --hard, rm -rf, kill -9, docker compose down, 잠금 파일 삭제 또는 .env 변경을 절대 실행하지 않습니다.

• dev_prepare는 계획만 수립합니다. 모든 제안 단계를 (read_only/safe/requires_approval/dangerous)로 분류하며 그 자체로는 아무것도 실행하지 않습니다.

전체 세부 사항: docs/security.md.

개인정보 보호 모델

• 환경 변수는 이름이 비밀 키로 보일 때(PASSWORD, TOKEN, SECRET, API_KEY, PRIVATE_KEY, ACCESS_KEY, AUTH, CREDENTIAL, ...) 존재 여부만 확인하며 값은 절대 반환하지 않습니다.

• .env 파일은 변수 이름만 스캔합니다.

• dev_precommit은 비밀 키로 보이는 스테이징 파일 이름을 표시하며 내용을 읽거나 보고하지 않습니다.

로컬 우선 아키텍처

• 서버 구성 요소, 계정, 자체 네트워크 호출이 없으며, 검사하는 로컬 명령어(git, docker, 언어 툴체인) 외에는 아무것도 없습니다.

• 보고하는 모든 것은 실행 중인 머신에 이미 존재하는 파일과 프로세스에서 비롯됩니다.

개발

uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src
uv run devtwin

전체 워크플로는 docs/development.md를 참조하세요.

기여

CONTRIBUTING.md를 참조하세요. 새로운 언어 생태계를 추가하는 것이 가장 일반적인 기여 방식입니다 -- 템플릿은 docs/adapters.md를, 실제 병합된 예시는 src/devtwin/adapters/swift.py, ruby.py, 그리고 php.py를 참조하여 모델링하세요.

로드맵

• 추가 생태계 어댑터: Elixir, Dart, Scala, C/C++ (CMake/Bazel/Buck), Nix (추가 방법은 docs/adapters.md 참조)

• 추가 서비스 탐지기 (MySQL/MariaDB, MongoDB, Kafka, RabbitMQ)

• CI 구성(예: GitHub Actions 런타임 매트릭스)에 대한 더 풍부한 드리프트 비교

• 세션 내 도구 호출 간 비용이 많이 드는 검사의 선택적 로컬 캐싱

라이선스

Apache-2.0 -- LICENSE 참조.