TDK CLI Core 및 AI 에이전트: MCP를 통해 Claude와 Codex 연결하기

AI 코딩 에이전트는 추측하는 것보다 실행 중인 시스템을 확인할 수 있을 때 더 신뢰할 수 있습니다. TDK CLI Core는 tdk mcp로 시작되는 로컬 Model Context Protocol (MCP) 서버를 포함하며, 이를 통해 로컬 스택을 에이전트가 호출할 수 있는 도구(tools)로 노출합니다.

사용 가능한 도구들

서버는 여섯 가지 도구를 노출합니다: doctor, up, down, status, logs, 그리고 resource_list입니다. 각 도구는 일치하는 명령을 JSON 모드로 실행하므로, 에이전트는 자유 텍스트가 아닌 구조화된 결과를 받게 됩니다. 인수는 실행되기 전에 검증되며, 서비스 이름은 문자, 숫자, 마침표(.), 밑줄(_), 하이픈(-)만 포함할 수 있습니다.

Codex 연결하기

프로젝트 범위의 항목을 .codex/config.toml에 추가합니다:

[mcp_servers.tdk]
command = "tdk"
args = ["mcp"]
...

cwd는 반드시 .tdk/project.json이 포함된 폴더여야 합니다. 서버는 그곳에서 프로젝트를 찾습니다.

Claude Code 연결하기

Claude Code도 동일한 방식으로 연결됩니다: 명령어는 tdk, 인수는 mcp이며, 작업 디렉터리(working directory)는 프로젝트입니다. agent tooling guide에 두 클라이언트에 대한 설정 단계가 나와 있습니다.

에이전트가 사용해야 하는 방법

작동하는 루프는 간단합니다:

1. doctor를 호출합니다. 만약 canUp이 false라면, 멈추고 이유를 보고합니다.
2. 선택적으로 이름 지정된 서비스로 제한하여 up을 호출합니다.
3. readiness.ready가 true가 될 때까지, 또는 실패가 나타날 때까지 반복적으로 status를 호출합니다.
4. 특정 서비스에 장애가 발생하면, 해당 서비스를 대상으로 작은 tail과 함께 logs를 호출합니다.
5. 작업이 완료되면 down을 호출합니다.

up은 스택이 준비되기 전에 반환됩니다. 왜냐하면 빌드가 단일 도구 호출보다 더 오래 걸릴 수 있기 때문입니다. 3단계의 폴링(polling)이 에이전트에게 실제 종료 지점을 제공하는 것입니다.

피해야 할 것들

• 서버를 네트워크에 노출하지 마십시오. 이 서버는 사용자의 기기에서 표준 입력 및 출력(standard input and output)을 통해 실행됩니다.
• 사람이 승인하기 전에 에이전트가 공유 인프라를 중지하거나 재설정하도록 두지 마십시오.
• 성공적인 up을 시스템이 작동한다는 증거로 간주하지 마십시오. status를 확인하십시오.

요약

MCP 서버는 에이전트가 구조화된 도구를 통해 로컬 스택을 시작하고, 상태를 확인하며, 중지할 수 있게 합니다. 프로젝트 폴더에서 연결하여 에이전트에게 start-poll-report 루프를 제공하고, 파괴적인(destructive) 작업은 사람과 함께 수행하도록 유지하십시오.