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

Tài nguyên tải về

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

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

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.

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

Cài đặt uv

macOS / Linux

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

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

macOS / Linux

Windows (PowerShell)

source $HOME/.local/bin/env

Windows (PowerShell)

Verify cài đặt

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

Verify cài đặt

uv --version
# Ra: uv 0.x.x hoặc tương tự

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

Bước 2: Init uv project

mkdir mcp-course
cd mcp-course

Bước 2: Init uv project

Lệnh này tạo:

Bước 3: Thêm dependencies

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

uv init --python 3.10

Bước 3: Thêm dependencies

pyproject.toml sau khi add sẽ có:

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

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

Khởi tạo dự án từ đầu (tiếp)

Bước 4: Verify dependencies

[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

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

uv sync

Khởi tạo dự án từ đầu (tiếp)

uv run python -c "import mcp; print(mcp.__version__)"
# Ra: version của MCP SDK, ví dụ 1.2.0

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:

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

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

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

# Environment
.env
.env.local

# IDE
.vscode/
.idea/
*.swp

# uv
# uv.lock NÊN commit (reproducible), chỉ exclude build artifacts
dist/
build/
*.egg-info/

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

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

Tại root project:

Mở .env và thêm:

touch .env

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

(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=sk-ant-api03-xxxxxxxxxxxxxxxx
CLAUDE_MODEL=claude-sonnet-5

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

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

Bước 3: Load trong code

Ở đầu main.py:

ANTHROPIC_API_KEY=
CLAUDE_MODEL=claude-sonnet-5

Bước 3: Load trong code

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

from dotenv import load_dotenv
import os

load_dotenv()

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

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)

Bước 2: Tạo project (15 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)

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

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

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

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

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

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

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

Bước 5: Verify (15 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)

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.

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

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:

(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:

pip install mcp anthropic

❌ Commit .env

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:

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

❌ Hard-code API key trong code

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.

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

Mẹo nâng cao

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

Thay vì:

Dùng:

source .venv/bin/activate
python main.py

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

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:

uv run main.py

Mẹo 2: Script cho setup 1-command

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:

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

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

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:

uv add --dev pre-commit detect-secrets

Mẹo 4: Multi-project workspace

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

# pyproject.toml root
[tool.uv.workspace]
members = ["servers/*"]

Á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:

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:

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

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

Bước 5: Ghi lại:

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

Tạo file test_api.py:

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

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ài tập 2 (optional): Test API key (~5 phút)

Chạy:

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()

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

Áp dụng ngay (tiếp)

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.

uv run test_api.py

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

🎯 uv là chuẩn de facto cho MCP — Nhanh, có lock file, quản lý cả Python version. Đầu tư 5 phút học là đủ dùng xuyên suốt career.

🎯 Project structure 3 file cốt lõi — mcp_server.py (server), mcp_client.py (client wrapper), main.py (CLI entry). Scale từ đây.

🎯 .env là không-thương-lượng — Key trong .env, .env trong .gitignore, .env.example trong git. Vi phạm = rủi ro.

🎯 Lock file là reproducible builds — Commit uv.lock. CI dùng uv sync --locked. Không cái này, "it works on my machine" sẽ quay lại ám bạn.

🎯 Setup 2 phút cho project mới — Với uv init + uv add + .env, bạn đi từ trắng tới ready trong thời gian pha cà phê.