Tool Dependencies — 도구 실행에 필요한 프로그램 설치하기

도구와 부가 기능 · 글 7편

도구와 부가 기능

이 글에서 다루는 것Toolbox의 도구가 실행되려면 필요한 node, npx, python, uv를 운영체제별로 설치하고 Sidecar에 경로를 지정하는 방법입니다.

왜 따로 설치가 필요한가

Toolbox에 등록한 도구는 Msty 앱 안에서 저절로 돌아가는 것이 아닙니다. 각 도구는 별도의 프로그램으로 실행되며, 실행에 필요한 기반 프로그램이 따로 있습니다. 이를 의존성(dependency)이라고 부릅니다. 대표적인 것은 다음 네 가지입니다.

도구 설정의 command 항목에 적힌 이름이 바로 이 프로그램입니다. command가 uvx인 도구는 uv가 설치되어 있어야 실행됩니다.

공식 문서가 강조하는 점은 도구는 Sidecar가 실행되는 곳에서 실행된다는 것입니다. 따라서 의존성도 Sidecar가 돌아가는 그 컴퓨터에 설치해야 합니다.

같은 프로그램도 설치 방법이 여러 가지입니다. 공식 문서는 모든 방법을 다루는 대신 하나의 권장 방법을 제시합니다. nvm 같은 도구로 설치한 의존성은 쓰려는 도구와 맞지 않아 동작하지 않을 수 있다고 덧붙입니다.

프로그램	운영체제	권장 방법
npx, node	Windows, Mac, Linux	Volta. 세 운영체제에서 모두 쓸 수 있습니다
npx, node	macOS	Homebrew도 쓸 수 있습니다
python, uv	Windows	WinGet. Sidecar 연결 창에서 의존성의 전체 경로를 지정해야 할 수 있습니다
uv	Mac	`brew install uv`. `uvx`도 함께 설치됩니다

Windows는 경로 지정 단계가 하나 더 있습니다. 순서대로 진행합니다.

winget install -e --id Python.Python.3.12 --scope machine
winget install --id=astral-sh.uv -e

Sidecar 연결 창에서 Python이 설치된 전체 경로를 지정합니다. uv는 자동으로 감지되므로 경로를 따로 지정하지 않아도 됩니다.
연결한 뒤 새 도구를 하나 만들고, 도구 콘솔(tool console)에서 그 도구의 기능 목록을 불러옵니다. 기능이 나열되면 도구가 정상 동작하는 것입니다.

4번 확인에 공식 문서가 쓰는 예시 도구 설정은 다음과 같습니다.

{
  "command": "uvx",
  "args": ["mcp-request"]
}

첫 번째 명령의 --scope machine은 Python을 특정 사용자가 아니라 컴퓨터 전체에 설치한다는 뜻입니다. 관리자 권한이 필요할 수 있으며, 회사 PC에서 설치가 막혀 있다면 전산 담당자에게 요청해야 합니다.

Mac은 비교적 간단합니다.

Mac에서 Python 경로를 따로 지정해야 하는지는 공식 문서에 설명이 없습니다.

도구를 처음 쓸 때는 도구가 자신에게 필요한 것을 내려받고 설치하느라 몇 분이 걸릴 수 있습니다. 걸리는 시간은 도구마다 다르고 Msty가 통제할 수 없는 부분이라고 공식 문서는 밝힙니다. 처음 실행에서 반응이 없다고 바로 실패로 판단하지 말고 기다려 봅니다.

오류나 문제가 있는지 Sidecar의 로그를 지켜봅니다. 도구가 동작하지 않을 때 원인이 가장 먼저 나타나는 곳입니다.

공식 문서에 별도의 문제 해결 절은 없지만, 본문의 안내를 순서로 정리하면 다음과 같습니다.

도구는 처음 실행할 때 필요한 것을 내려받습니다. 인터넷이 막힌 환경에서 이를 어떻게 처리하는지는 공식 문서에 설명이 없습니다. 폐쇄망 PC에 도구를 올리려는 경우에는 외부망에서 먼저 시험한 뒤 반입 방법을 따로 검토해야 합니다.