질문1.
uv 가상환경이 기존 방식과 달라 이해가 어렵다. 다음 명령어를 상세하게 설명해줘.
cd \path\to\MCP # 1. 원하는 위치로 이동 (예: D:\MCP-server)
uv init docReader # 2. 'docReader'라는 이름의 uv 프로젝트 초기화
cd docReader # 3. 생성된 프로젝트 폴더로 이동
New-Item -ItemType Directory -Name docs # 4. docs 폴더 생성
uv venv --python=python3.10 # 5. Python 3.10 기반 가상환경 생성 (.venv 폴더)
.venv\Scripts\activate # 6. 가상환경 활성화
uv add mcp[cli] PyMuPDF faiss-cpu sentence_transformers # 7. 필요한 패키지 설치
질문2.
uv는 가상환경을 어떻게 실행하는가? uv run *.py 와 같은 명령어를 mcp 서버로 실행하는 경우?
uv 패키지 및 환경 관리 도구
uv는 최근 등장한 빠르고 간결한 Python 패키지 및 환경 관리 도구입니다. 기존의 pip, venv, virtualenv, poetry, pipenv 등과 유사한 역할을 하지만, 더 경량화되고 빠르며, 특히 모노레포 환경이나 WASM 기반 개발에 적합하게 설계되었습니다.
1. cd \path\to\MCP
의미: 해당 디렉토리(예: D:\MCP-server)로 이동
용도: 새로운 uv 프로젝트를 생성할 디렉토리를 지정함
cd는 Change Directory의 약자입니다.
2. uv init docReader
의미: docReader라는 이름의 새로운 uv 프로젝트 초기화
결과: docReader라는 폴더가 생성되고, 내부에 다음과 같은 파일이 생김:
uv.toml : pyproject.toml처럼, 프로젝트 설정 및 의존성 정보를 담는 파일
.venv/ (가상환경은 아직 생성되지 않음)
설명: uv는 해당 폴더를 독립적인 Python 프로젝트로 인식하게 됩니다.
3. cd docReader
의미: 방금 생성된 docReader 폴더로 이동
4. New-Item -ItemType Directory -Name docs
의미: docs라는 이름의 새 폴더 생성
용도: 문서, PDF 등 프로젝트에 필요한 자료를 저장할 공간 마련
Windows PowerShell 명령어입니다.
5. uv venv --python=python3.10
의미: Python 3.10을 기반으로 .venv라는 이름의 가상환경을 생성
결과: .venv 폴더가 생성되고, 그 안에 Python 실행환경이 구성됨
* python3.10이 설치되어 있어야 하고, 시스템 PATH에 등록되어 있어야 함
6. .venv\Scripts\activate
의미: 위에서 만든 .venv 가상환경을 활성화
Windows용 명령어 (Unix/Mac에서는 source .venv/bin/activate)
가상환경 활성화 시, PowerShell 프롬프트 앞에 (.venv) 같은 표시가 생기며, 이후 pip이나 python 명령이 모두 .venv 내부의 것을 참조하게 됩니다.
7. uv add mcp[cli] PyMuPDF faiss-cpu sentence_transformers
의미: 필요한 의존성 패키지를 설치함과 동시에 uv.toml에 기록
설치되는 패키지:
mcp[cli]: MCP 모듈과 CLI 기능 포함
PyMuPDF: PDF 파일을 읽고 처리하기 위한 라이브러리 (fitz로 import)
faiss-cpu: Facebook의 벡터 검색 라이브러리 (CPU 버전)
sentence_transformers: 문장 임베딩 생성을 위한 라이브러리 (BERT 등 사용)
비교 (pip vs uv):
pip install package # 단순 설치
uv add package # 설치 + 프로젝트 의존성 파일에 기록
기존 방식과 다른 점 요약
항목 기존 방식 (venv, pip) uv 방식
가상환경 생성 python -m venv .venv uv venv
패키지 설치 pip install uv add
설정 파일 requirements.txt uv.toml
속도 상대적으로 느림 매우 빠름 (Rust 기반)
의존성 해석 제한적 의존성 충돌 자동 관리
권장 대상 전통적 Python 프로젝트 빠른 빌드, 모듈 프로젝트, WASM
전체 흐름 정리
uv는 빠른 패키지 및 가상환경 설정을 지원하며, 기존 Python 프로젝트의 venv + pip + requirements.txt를 하나로 통합한 새로운 워크플로우입니다.
uv는 가상환경을 어떻게 실행 의미
uv run *.py 와 같은 명령어를 mcp 서버로 실행하는 경우,
uv는 자체적으로 가상환경을 자동으로 인식하고 실행하는 특징이 있습니다. uv run .py와 같은 명령은 기존의 python .py와 비슷하게 보이지만, uv의 가상환경 관리와 실행이 통합된 방식입니다.
uv run *.py는 어떻게 작동하는가?
.venv 또는 uv.toml이 있는 디렉토리 기준으로 실행
uv는 현재 디렉토리 또는 상위 디렉토리에 .venv 폴더나 uv.toml 파일이 있는 경우, 그 가상환경을 자동으로 인식합니다.
그리고 .venv/bin/python 또는 .venv/Scripts/python.exe를 내부적으로 사용합니다.
즉, 다음과 같이 작동합니다:
uv run server.py
→ 아래 명령어와 사실상 동등하게 실행됩니다:
bash
.venv/Scripts/python.exe server.py # (Windows)
MCP 서버와 함께 사용할 경우
예시: MCP 서버 구동
uv run -m mcp.server.fastmcp
-m 옵션은 파이썬의 -m과 동일하게 모듈 방식 실행을 의미합니다.
MCP는 일반적으로 FastAPI 기반의 서버이므로, 이 명령은 python -m mcp.server.fastmcp와 동일한 결과를 냅니다.
.venv 내부에 mcp와 관련된 모든 의존성(mcp[cli], fastapi, uvicorn, 등등)이 설치되어 있어야 정상 작동합니다.
장점 요약
기능 python 사용 시 uv run 사용 시 가상환경 자동 적용
스크립트 실행 python myfile.py uv run myfile.py
모듈 실행 python -m module uv run -m module
빠르고 명확한 옵션 제공, 매우 빠름 (Rust 기반 실행기)
가상환경 수동으로 쓰고 싶다면?
.venv\Scripts\activate # Windows
source .venv/bin/activate # Mac/Linux
python myfile.py
하지만, uv를 쓴다면 이 과정은 생략 가능하고 그냥 아래처럼 하면 됩니다:
uv run myfile.py
