7.3 · Thiết lập dự án với uv + Python SDK

Mở đầu: Tại sao uv chứ không phải pip?

pip install mcp anthropic

Và chờ. 30 giây. 45 giây. 1 phút. pip đang resolve dependencies — đọc metadata, check version constraints, download, compile wheels... Cuối cùng xong.

Ngày thứ 4, bạn thêm pandas. Lại chờ. Lại 45 giây cho một lib đã cài ở project khác.

Ngày thứ 7, bạn clone project đồng nghiệp. pip install -r requirements.txt. 2 phút 15 giây. Bạn đi pha cà phê.

Astral — công ty đứng sau Ruff — nhìn bài toán này và viết lại toàn bộ package manager Python bằng Rust. Kết quả: uv — nhanh hơn pip 10-100 lần, resolve deterministic qua uv.lock, và handle virtualenv + Python version cùng một công cụ.

Anthropic chọn uv làm standard cho MCP SDK. Không phải vì fancy — mà vì mỗi giây tiết kiệm nhân với hàng nghìn dev cài đặt MCP server mỗi ngày là thời gian đáng kể.

Bài này sẽ setup môi trường với uv. Nếu bạn đang dùng pip / poetry / conda quen rồi, vẫn OK nhưng khóa học sẽ follow uv convention vì phần lớn MCP ecosystem dùng nó.

Tài nguyên tải về

Course này có sẵn 2 file ZIP project:

• cli_project.zip — Project rỗng với skeleton sẵn sàng để bạn điền code theo từng bài
• cli_project_COMPLETE.zip — Bản hoàn chỉnh để bạn đối chiếu nếu bí

Link tải trong bài gốc của khóa học (hoặc hỏi instructor). Khuyến nghị:

1. Download cli_project.zip ngay bây giờ
2. Giải nén vào thư mục bạn chọn (ví dụ ~/projects/mcp-course/)
3. Mở terminal tại thư mục đó trước khi tiếp tục bài

Nếu bạn muốn build from scratch, đọc tiếp phần "Khởi tạo dự án từ đầu" dưới đây.

Cài đặt uv

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Script tự cài uv vào ~/.local/bin/. Restart terminal hoặc:

source $HOME/.local/bin/env

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify cài đặt

uv --version

Khởi tạo dự án từ đầu

Nếu bạn muốn build from scratch thay vì dùng ZIP:

Bước 1: Tạo thư mục project

mkdir mcp-course
cd mcp-course

Bước 2: Init uv project

uv init --python 3.10

Lệnh này tạo:

mcp-course/
├── .python-version       # Pin version 3.10
├── pyproject.toml         # Dependencies metadata
├── README.md
└── main.py                # Entry point mẫu

Bước 3: Thêm dependencies

uv add "mcp[cli]" anthropic python-dotenv

• mcp[cli] — MCP Python SDK + CLI tool mcp dev
• anthropic — Official Claude API SDK
• python-dotenv — Load env vars từ file .env

pyproject.toml sau khi add sẽ có:

[project]
name = "mcp-course"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "anthropic>=0.40.0",
    "mcp[cli]>=1.0.0",
    "python-dotenv>=1.0.0",
]

Bước 4: Verify dependencies

uv sync

Lệnh này download + install tất cả deps vào .venv/ (tự động). Nhanh cực.

uv run python -c "import mcp; print(mcp.__version__)"

Cấu trúc thư mục chuẩn cho MCP project

Sau setup, thêm các file sau để match với bài thực hành ở các Module tiếp theo:

mcp-course/
├── .env                       # API key (KHÔNG commit!)
├── .env.example               # Template cho teammate
├── .gitignore                 # Exclude .env, .venv, __pycache__
├── .python-version
├── pyproject.toml
├── uv.lock                    # Lock file cho reproducible install
├── README.md
├── mcp_server.py              # ← MCP server code (Bài 7.4)
├── mcp_client.py              # ← Custom client class (Bài 7.6)
├── main.py                    # ← Entry point CLI chat (Bài 7.6)
└── core/
    ├── __init__.py
    ├── chat.py                # Chat logic với Claude
    ├── cli_chat.py            # CLI interface
    └── tools.py               # Helper để pass tools vào Claude

Nếu bạn dùng cli_project.zip, tất cả đã có sẵn skeleton. Nhiệm vụ của bạn trong các bài tiếp theo là điền vào logic.

.gitignore mẫu

__pycache__/
*.py[cod]
.venv/
.Python

.env
.env.local

.vscode/
.idea/
*.swp

dist/
build/
*.egg-info/

Cấu hình API key an toàn

Bước 1: Tạo file .env

Tại root project:

touch .env

Mở .env và thêm:

ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxx
CLAUDE_MODEL=claude-sonnet-4-5

(Lấy API key từ console.anthropic.com — tab "API Keys").

Bước 2: Tạo .env.example

Để teammate biết cần env var nào mà không lộ key thật:

ANTHROPIC_API_KEY=
CLAUDE_MODEL=claude-sonnet-4-5

File này được commit lên git. File .env thật thì không.

Bước 3: Load trong code

Ở đầu main.py:

from dotenv import load_dotenv
import os

load_dotenv()

api_key = os.environ["ANTHROPIC_API_KEY"]
model = os.environ.get("CLAUDE_MODEL", "claude-sonnet-4-5")

Thế là xong. Code không có hard-coded key.

Bảng so sánh: uv vs pip vs poetry vs conda

Cho MCP work chọn uv. Nó là future-proof và match với tooling Anthropic recommend.

Ví dụ thực chiến: Setup trong 3 phút

Tình huống

Bạn vừa mở laptop sáng thứ 2, muốn bắt đầu học khóa MCP ngay.

Bước 1: Cài uv (30 giây)

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

Bước 2: Tạo project (15 giây)

mkdir mcp-course && cd mcp-course
uv init --python 3.10

Bước 3: Add deps (20 giây)

uv add "mcp[cli]" anthropic python-dotenv

uv resolve và cài đặt — cực nhanh.

Bước 4: Tạo .env (30 giây)

cat > .env <<EOF
ANTHROPIC_API_KEY=sk-ant-api03-...
EOF

cat > .gitignore <<EOF
.env
.venv/
__pycache__/
EOF

Bước 5: Verify (15 giây)

uv run python -c "
from anthropic import Anthropic
from mcp.server.fastmcp import FastMCP
print('Anthropic SDK loaded')
print('MCP SDK loaded')
"

Kết quả

Tổng thời gian: ~2 phút. So với pip + venv truyền thống: ~5-7 phút.

Bạn giờ đã sẵn sàng viết MCP server ở Bài 7.4.

Ví dụ theo ngành — Cách setup trong các team khác nhau

Startup developer solo

Workflow

uv + .env local + VS Code. Không cần Docker, không CI phức tạp. Code xong, commit, push.

Thế mạnh

Iteration cực nhanh. Setup mới 2 phút.

Enterprise dev team

Workflow

uv + .env.vault (hoặc secret manager như Doppler) + CI/CD pipeline. uv.lock được commit và CI verify bằng uv sync --locked.

Thế mạnh

Reproducible builds, audit trail, không leak secret.

Data scientist / ML engineer

Workflow

uv + Jupyter kernel trong .venv/. uv pip install ipykernel && python -m ipykernel install --user --name=mcp

Thế mạnh

Notebook + MCP server cùng một env. Thử nghiệm tool call từ Jupyter.

Student / học viên khóa này

Workflow

Download cli_project.zip → uv sync → cp .env.example .env → fill API key. 3 bước.

Thế mạnh

Zero config. Focus vào học concept, không vướng tool.

Remote/dev team quốc tế

Workflow

Dev container / GitHub Codespaces + uv được cài trong image. uv.lock đảm bảo mọi người cùng version dù OS khác.

Thế mạnh

"It works on my machine" biến mất.

Anti-patterns — Những sai lầm cần tránh

Cài globally thay vì virtualenv

Sai lầm:

pip install mcp anthropic

(Không venv, cài thẳng vào system Python)

Tại sao là sai

Conflict version với project khác. Khó gỡ. Permission issues trên macOS/Linux.

Cách đúng

Dùng uv hoặc python -m venv luôn luôn. uv run tự dùng .venv/ của project.

Commit .env

Sai lầm:

git add .env && git commit -m "add config"
git push

Tại sao là sai

API key công khai. Anthropic sẽ tự revoke key nếu detect leak, nhưng bạn mất tiền credit đã bị abuse. Đây là lý do phải luôn .gitignore .env.

Cách đúng

.gitignore .env ngay từ lần commit đầu. Dùng .env.example cho teammate.

Hard-code API key trong code

Sai lầm:

client = Anthropic(api_key="sk-ant-api03-xxxxx")

Tại sao là sai

Key vào git history. Ngay cả khi xóa file sau, commit cũ vẫn còn key.

Cách đúng

os.environ["ANTHROPIC_API_KEY"] + .env.

Không commit uv.lock

Sai lầm

.gitignore cả uv.lock.

Tại sao là sai

Mỗi dev/CI cài version khác nhau. Bug "chỉ xảy ra trên máy tôi" xuất hiện.

Cách đúng

Commit uv.lock. CI dùng uv sync --locked để verify match.

Mix uv với pip install trong cùng project

Sai lầm

Cài lib qua pip install foo khi project dùng uv.

Tại sao là sai

uv.lock và pyproject.toml không biết về foo. Khi uv sync, foo sẽ bị remove.

Cách đúng

Luôn uv add foo.

Dùng Python 3.8 hoặc cũ hơn

Sai lầm

.python-version chứa 3.8 hoặc 3.9.

Tại sao là sai

MCP SDK dùng nhiều features từ 3.10+ (pattern matching, | type syntax, asyncio improvements).

Cách đúng

Python 3.10 tối thiểu. 3.11 hoặc 3.12 tốt hơn.

Mẹo nâng cao

Mẹo 1: Dùng uv run thay vì activate venv

Thay vì:

source .venv/bin/activate
python main.py

Dùng:

uv run main.py

uv run tự activate venv cho mỗi command. Không quên deactivate.

Mẹo 2: Script cho setup 1-command

Tạo Makefile:

setup:
	uv sync
	cp -n .env.example .env || true
	@echo "Remember to fill ANTHROPIC_API_KEY in .env"

server:
	uv run mcp dev mcp_server.py

chat:
	uv run main.py

Sau đó chỉ cần make setup, make server, make chat.

Mẹo 3: Pre-commit hook chống leak

Cài gitleaks hoặc trufflehog:

uv add --dev pre-commit detect-secrets

Config .pre-commit-config.yaml scan mọi commit cho API key patterns. Tránh .env bị commit vô tình.

Mẹo 4: Multi-project workspace

Nếu bạn build nhiều MCP server cho công ty (một cho Jira, một cho Postgres, một cho internal API), dùng uv workspace để share deps:

[tool.uv.workspace]
members = ["servers/*"]

Mỗi subfolder là một MCP server riêng nhưng share mcp SDK version.

Áp dụng ngay

Bài tập 1: Setup environment (~15 phút)

Bước 1

Cài uv theo hướng dẫn ở trên.

Bước 2

Tạo project MCP mới:

mkdir my-mcp-lab && cd my-mcp-lab
uv init --python 3.10
uv add "mcp[cli]" anthropic python-dotenv

Bước 3

Tạo .env với ANTHROPIC_API_KEY của bạn. Tạo .gitignore loại trừ .env và .venv/.

Bước 4

Verify bằng lệnh:

uv run python -c "from mcp.server.fastmcp import FastMCP; print('✅ MCP SDK loaded')"
uv run python -c "from anthropic import Anthropic; print('✅ Anthropic SDK loaded')"

Bước 5: Ghi lại:

• Thời gian setup: ___________
• Python version: ___________
• MCP SDK version: ___________
• Lỗi bạn gặp (nếu có): ___________

Bài tập 2 (optional): Test API key (~5 phút)

Tạo file test_api.py:

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()

client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=100,
    messages=[{"role": "user", "content": "Say 'MCP setup OK'"}]
)
print(response.content[0].text)

Chạy:

uv run test_api.py

Nếu in ra "MCP setup OK" → API key hoạt động. Nếu lỗi 401 → key sai. Nếu lỗi network → check internet.

Tóm tắt bài học

Tài liệu tham khảo

• uv docs — Official
• MCP Python SDK README
• Anthropic API docs
• python-dotenv