24 KiB
Configurarea Mediului
🎯 Ce Acoperă Acest Laborator
Acest laborator practic te ghidează prin configurarea unui mediu complet de dezvoltare pentru construirea serverelor MCP cu integrare PostgreSQL. Vei configura toate uneltele necesare, vei implementa resurse Azure și vei valida configurarea înainte de a continua cu implementarea.
Prezentare Generală
Un mediu de dezvoltare adecvat este esențial pentru succesul dezvoltării serverelor MCP. Acest laborator furnizează instrucțiuni pas cu pas pentru configurarea Docker, serviciilor Azure, uneltelor de dezvoltare și validarea funcționării corecte a tuturor împreună.
La finalul acestui laborator, vei avea un mediu de dezvoltare complet funcțional, pregătit pentru construirea serverului Zava Retail MCP.
Obiective de Învățare
La finalul acestui laborator, vei putea să:
- Instalezi și configurezi toate uneltele de dezvoltare necesare
- Implementezi resurse Azure necesare pentru serverul MCP
- Configurezi containere Docker pentru PostgreSQL și serverul MCP
- Validezi configurarea mediului prin conexiuni de test
- Depanezi probleme comune de configurare și setare
- Înțelegi fluxul de dezvoltare și structura fișierelor
📋 Verificare Prealabilă
Înainte de a începe, asigură-te că ai:
Cunoștințe Necesare
- Utilizare de bază a liniei de comandă (Windows Command Prompt/PowerShell)
- Înțelegerea variabilelor de mediu
- Familiaritate cu controlul versiunilor Git
- Concepte de bază Docker (containere, imagini, volume)
Cerințe de Sistem
- Sistem de Operare: Windows 10/11, macOS sau Linux
- RAM: Minim 8GB (16GB recomandat)
- Stocare: Cel puțin 10GB spațiu liber
- Rețea: Conexiune la internet pentru descărcări și implementare Azure
Cerințe de Cont
- Abonament Azure: Nivel gratuit este suficient
- Cont GitHub: Pentru acces la depozit
- Cont Docker Hub: (Opțional) Pentru publicarea imaginilor personalizate
🛠️ Instalarea Uneltelor
1. Instalează Docker Desktop
Docker oferă mediul containerizat pentru configurația noastră de dezvoltare.
Instalare pe Windows
-
Descarcă Docker Desktop:
# Visit https://desktop.docker.com/win/stable/Docker%20Desktop%20Installer.exe # Or use Windows Package Manager winget install Docker.DockerDesktop -
Instalează și Configurează:
- Rulează instalatorul ca Administrator
- Activează integrarea WSL 2 când ți se solicită
- Repornește calculatorul după finalizarea instalării
-
Verifică Instalarea:
docker --version docker-compose --version
Instalare pe macOS
-
Descarcă și Instalează:
# Descărcați de la https://desktop.docker.com/mac/stable/Docker.dmg # Sau folosiți Homebrew brew install --cask docker -
Pornește Docker Desktop:
- Lansează Docker Desktop din Aplicații
- Finalizează wizard-ul inițial de configurare
-
Verifică Instalarea:
docker --version docker-compose --version
Instalare pe Linux
-
Instalează Docker Engine:
# Ubuntu/Debian curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # Deconectați-vă și conectați-vă din nou pentru ca modificările grupului să intre în vigoare -
Instalează Docker Compose:
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose
2. Instalează Azure CLI
Azure CLI permite implementarea și gestionarea resurselor Azure.
Instalare pe Windows
# Using Windows Package Manager
winget install Microsoft.AzureCLI
# Or download MSI from: https://aka.ms/installazurecliwindows
Instalare pe macOS
# Utilizând Homebrew
brew install azure-cli
# Sau folosind programul de instalare
curl -L https://aka.ms/InstallAzureCli | bash
Instalare pe Linux
# Ubuntu/Debian
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
# RHEL/CentOS
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo dnf install azure-cli
Verifică și Autentifică-te
# Verifică instalarea
az version
# Autentificare în Azure
az login
# Setează subscripția implicită (dacă ai mai multe)
az account list --output table
az account set --subscription "Your-Subscription-Name"
3. Instalează Git
Git este necesar pentru clonarea depozitului și controlul versiunilor.
Windows
# Using Windows Package Manager
winget install Git.Git
# Or download from: https://git-scm.com/download/win
macOS
# Git este de obicei preinstalat, dar îl poți actualiza prin Homebrew
brew install git
Linux
# Ubuntu/Debian
sudo apt update && sudo apt install git
# RHEL/CentOS
sudo dnf install git
4. Instalează VS Code
Visual Studio Code oferă mediul de dezvoltare integrat cu suport MCP.
Instalare
# Windows
winget install Microsoft.VisualStudioCode
# macOS
brew install --cask visual-studio-code
# Linux (Ubuntu/Debian)
sudo snap install code --classic
Extensii Necesare
Instalează aceste extensii VS Code:
# Instalați prin linia de comandă
code --install-extension ms-python.python
code --install-extension ms-vscode.vscode-json
code --install-extension ms-azuretools.vscode-docker
code --install-extension ms-vscode.azure-account
Sau instalează prin VS Code:
- Deschide VS Code
- Mergi la Extensii (Ctrl+Shift+X)
- Instalează:
- Python (Microsoft)
- Docker (Microsoft)
- Azure Account (Microsoft)
- JSON (Microsoft)
5. Instalează Python
Python 3.8+ este necesar pentru dezvoltarea serverului MCP.
Windows
# Using Windows Package Manager
winget install Python.Python.3.11
# Or download from: https://www.python.org/downloads/
macOS
# Folosind Homebrew
brew install python@3.11
Linux
# Ubuntu/Debian
sudo apt update && sudo apt install python3.11 python3.11-pip python3.11-venv
# RHEL/CentOS
sudo dnf install python3.11 python3.11-pip
Verifică Instalarea
python --version # Ar trebui să afișeze Python 3.11.x
pip --version # Ar trebui să afișeze versiunea pip
🚀 Configurarea Proiectului
1. Clonarea Depozitului
# Clonează depozitul principal
git clone https://github.com/microsoft/MCP-Server-and-PostgreSQL-Sample-Retail.git
# Navighează către directorul proiectului
cd MCP-Server-and-PostgreSQL-Sample-Retail
# Verifică structura depozitului
ls -la
2. Creează Mediu Virtual Python
# Creează mediu virtual
python -m venv mcp-env
# Activează mediul virtual
# Windows
mcp-env\Scripts\activate
# macOS/Linux
source mcp-env/bin/activate
# Actualizează pip
python -m pip install --upgrade pip
3. Instalează Dependențele Python
# Instalează dependențele de dezvoltare
pip install -r requirements.lock.txt
# Verifică pachetele cheie
pip list | grep fastmcp
pip list | grep asyncpg
pip list | grep azure
☁️ Implementarea Resurselor Azure
1. Înțelege Cerințele Resurselor
Serverul nostru MCP necesită aceste resurse Azure:
| Resursă | Scop | Cost Estimat |
|---|---|---|
| Microsoft Foundry | Găzduire și gestionare modele AI | 10-50 USD/lună |
| Implementare OpenAI | Model embedding text (text-embedding-3-small) | 5-20 USD/lună |
| Application Insights | Monitorizare și telemetrie | 5-15 USD/lună |
| Grup de Resurse | Organizarea resurselor | Gratuit |
2. Implementează Resursele Azure
Opțiunea A: Implementare Automată (Recomandată)
# Navighează la directorul infrastructure
cd infra
# Windows - PowerShell
./deploy.ps1
# macOS/Linux - Bash
./deploy.sh
Scriptul de implementare va:
- Crea un grup de resurse unic
- Implementa resurse Microsoft Foundry
- Implementa modelul text-embedding-3-small
- Configura Application Insights
- Crea un service principal pentru autentificare
- Genera fișierul
.envcu configurația
Opțiunea B: Implementare Manuală
Dacă preferi controlul manual sau scriptul automatizat eșuează:
# Setează variabilele
RESOURCE_GROUP="rg-zava-mcp-$(date +%s)"
LOCATION="westus2"
AI_PROJECT_NAME="zava-ai-project"
# Creează grupul de resurse
az group create --name $RESOURCE_GROUP --location $LOCATION
# Desfășoară șablonul principal
az deployment group create \
--resource-group $RESOURCE_GROUP \
--template-file main.bicep \
--parameters location=$LOCATION \
--parameters resourcePrefix="zava-mcp"
3. Verifică Implementarea Azure
# Verifică grupul de resurse
az group show --name $RESOURCE_GROUP --output table
# Listează resursele implementate
az resource list --resource-group $RESOURCE_GROUP --output table
# Testează serviciul AI
az cognitiveservices account show \
--name "your-ai-service-name" \
--resource-group $RESOURCE_GROUP
4. Configurează Variabilele de Mediu
După implementare, ar trebui să ai un fișier .env. Verifică să conțină:
# Conținutul fișierului .env
PROJECT_ENDPOINT=https://your-project.cognitiveservices.azure.com/
AZURE_OPENAI_ENDPOINT=https://your-openai.openai.azure.com/
EMBEDDING_MODEL_DEPLOYMENT_NAME=text-embedding-3-small
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id
APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=your-key;...
# Configurarea bazei de date (pentru dezvoltare)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=zava
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-secure-password
🐳 Configurarea Mediului Docker
1. Înțelege Compoziția Docker
Mediul nostru de dezvoltare utilizează Docker Compose:
# docker-compose.yml overview
version: '3.8'
services:
postgres:
image: pgvector/pgvector:pg17
environment:
POSTGRES_DB: zava
POSTGRES_USER: postgres
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-secure_password}
ports:
- "5432:5432"
volumes:
- ./data:/backup_data:ro
- ./docker-init:/docker-entrypoint-initdb.d:ro
mcp_server:
build: .
depends_on:
postgres:
condition: service_healthy
ports:
- "8000:8000"
env_file:
- .env
2. Pornește Mediul de Dezvoltare
# Asigură-te că ești în directorul rădăcină al proiectului
cd /path/to/MCP-Server-and-PostgreSQL-Sample-Retail
# Pornește serviciile
docker-compose up -d
# Verifică starea serviciului
docker-compose ps
# Vizualizează jurnalele
docker-compose logs -f
3. Verifică Configurarea Bazei de Date
# Conectează-te la containerul PostgreSQL
docker-compose exec postgres psql -U postgres -d zava
# Verifică structura bazei de date
\dt retail.*
# Verifică datele de probă
SELECT COUNT(*) FROM retail.stores;
SELECT COUNT(*) FROM retail.products;
SELECT COUNT(*) FROM retail.orders;
# Ieși din PostgreSQL
\q
4. Testează Serverul MCP
# Verificați sănătatea serverului MCP
curl http://localhost:8000/health
# Testați punctul final MCP de bază
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "x-rls-user-id: 00000000-0000-0000-0000-000000000000" \
-d '{"method": "tools/list", "params": {}}'
🔧 Configurarea VS Code
1. Configurează Integrarea MCP
Creează configurația MCP pentru VS Code:
// .vscode/mcp.json
{
"servers": {
"zava-sales-analysis-headoffice": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http",
"headers": {"x-rls-user-id": "00000000-0000-0000-0000-000000000000"}
},
"zava-sales-analysis-seattle": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http",
"headers": {"x-rls-user-id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}
},
"zava-sales-analysis-redmond": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http",
"headers": {"x-rls-user-id": "e7f8a9b0-c1d2-3e4f-5678-90abcdef1234"}
}
},
"inputs": []
}
2. Configurează Mediul Python
// .vscode/settings.json
{
"python.defaultInterpreterPath": "./mcp-env/bin/python",
"python.linting.enabled": true,
"python.linting.pylintEnabled": true,
"python.formatting.provider": "black",
"python.testing.pytestEnabled": true,
"python.testing.pytestArgs": ["tests"],
"files.exclude": {
"**/__pycache__": true,
"**/.pytest_cache": true,
"**/mcp-env": true
}
}
3. Testează Integrarea VS Code
-
Deschide proiectul în VS Code:
code . -
Deschide Chat AI:
- Apasă
Ctrl+Shift+P(Windows/Linux) sauCmd+Shift+P(macOS) - Tastează „AI Chat” și selectează „AI Chat: Open Chat”
- Apasă
-
Testează Conexiunea Server MCP:
- În AI Chat, tastează
#zavași selectează unul dintre serverele configurate - Întreabă: „Ce tabele sunt disponibile în baza de date?”
- Ar trebui să primești un răspuns cu lista tabelelor bazei de date retail
- În AI Chat, tastează
✅ Validarea Mediului
1. Verificare Comprehensivă a Sistemului
Rulează acest script de validare pentru a verifica configurarea:
# Creează script de validare
cat > validate_setup.py << 'EOF'
#!/usr/bin/env python3
"""
Environment validation script for MCP Server setup.
"""
import asyncio
import os
import sys
import subprocess
import requests
import asyncpg
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
async def validate_environment():
"""Comprehensive environment validation."""
results = {}
# Verifică versiunea Python
python_version = sys.version_info
results['python'] = {
'status': 'pass' if python_version >= (3, 8) else 'fail',
'version': f"{python_version.major}.{python_version.minor}.{python_version.micro}",
'required': '3.8+'
}
# Verifică pachetele necesare
required_packages = ['fastmcp', 'asyncpg', 'azure-ai-projects']
for package in required_packages:
try:
__import__(package)
results[f'package_{package}'] = {'status': 'pass'}
except ImportError:
results[f'package_{package}'] = {'status': 'fail', 'error': 'Not installed'}
# Verifică Docker
try:
result = subprocess.run(['docker', '--version'], capture_output=True, text=True)
results['docker'] = {
'status': 'pass' if result.returncode == 0 else 'fail',
'version': result.stdout.strip() if result.returncode == 0 else 'Not available'
}
except FileNotFoundError:
results['docker'] = {'status': 'fail', 'error': 'Docker not found'}
# Verifică Azure CLI
try:
result = subprocess.run(['az', '--version'], capture_output=True, text=True)
results['azure_cli'] = {
'status': 'pass' if result.returncode == 0 else 'fail',
'version': result.stdout.split('\n')[0] if result.returncode == 0 else 'Not available'
}
except FileNotFoundError:
results['azure_cli'] = {'status': 'fail', 'error': 'Azure CLI not found'}
# Verifică variabilele de mediu
required_env_vars = [
'PROJECT_ENDPOINT',
'AZURE_OPENAI_ENDPOINT',
'EMBEDDING_MODEL_DEPLOYMENT_NAME',
'AZURE_CLIENT_ID',
'AZURE_CLIENT_SECRET',
'AZURE_TENANT_ID'
]
for var in required_env_vars:
value = os.getenv(var)
results[f'env_{var}'] = {
'status': 'pass' if value else 'fail',
'value': '***' if value and 'SECRET' in var else value
}
# Verifică conexiunea la baza de date
try:
conn = await asyncpg.connect(
host=os.getenv('POSTGRES_HOST', 'localhost'),
port=int(os.getenv('POSTGRES_PORT', 5432)),
database=os.getenv('POSTGRES_DB', 'zava'),
user=os.getenv('POSTGRES_USER', 'postgres'),
password=os.getenv('POSTGRES_PASSWORD', 'secure_password')
)
# Testează interogarea
result = await conn.fetchval('SELECT COUNT(*) FROM retail.stores')
await conn.close()
results['database'] = {
'status': 'pass',
'store_count': result
}
except Exception as e:
results['database'] = {
'status': 'fail',
'error': str(e)
}
# Verifică serverul MCP
try:
response = requests.get('http://localhost:8000/health', timeout=5)
results['mcp_server'] = {
'status': 'pass' if response.status_code == 200 else 'fail',
'response': response.json() if response.status_code == 200 else response.text
}
except Exception as e:
results['mcp_server'] = {
'status': 'fail',
'error': str(e)
}
# Verifică serviciul Azure AI
try:
credential = DefaultAzureCredential()
project_client = AIProjectClient(
endpoint=os.getenv('PROJECT_ENDPOINT'),
credential=credential
)
# Aceasta va eșua dacă acreditările sunt invalide
results['azure_ai'] = {'status': 'pass'}
except Exception as e:
results['azure_ai'] = {
'status': 'fail',
'error': str(e)
}
return results
def print_results(results):
"""Print formatted validation results."""
print("🔍 Environment Validation Results\n")
print("=" * 50)
passed = 0
failed = 0
for component, result in results.items():
status = result.get('status', 'unknown')
if status == 'pass':
print(f"✅ {component}: PASS")
passed += 1
else:
print(f"❌ {component}: FAIL")
if 'error' in result:
print(f" Error: {result['error']}")
failed += 1
print("\n" + "=" * 50)
print(f"Summary: {passed} passed, {failed} failed")
if failed > 0:
print("\n❗ Please fix the failed components before proceeding.")
return False
else:
print("\n🎉 All validations passed! Your environment is ready.")
return True
if __name__ == "__main__":
asyncio.run(main())
async def main():
results = await validate_environment()
success = print_results(results)
sys.exit(0 if success else 1)
EOF
# Rulează validarea
python validate_setup.py
2. Listă Manuală de Validare
✅ Unelte de bază
- Docker versiunea 20.10+ instalat și rulează
- Azure CLI 2.40+ instalat și autentificat
- Python 3.8+ cu pip instalat
- Git 2.30+ instalat
- VS Code cu extensiile necesare
✅ Resurse Azure
- Grup de resurse creat cu succes
- Proiect AI Foundry implementat
- Model OpenAI text-embedding-3-small implementat
- Application Insights configurat
- Service principal creat cu permisiunile corecte
✅ Configurare Mediu
- Fișier
.envcreat cu toate variabilele necesare - Credențiale Azure funcționale (testează cu
az account show) - Container PostgreSQL rulează și este accesibil
- Date de probă încărcate în baza de date
✅ Integrare VS Code
.vscode/mcp.jsonconfigurat- Interpret Python setat la mediul virtual
- Servere MCP apar în AI Chat
- Capacitatea de a executa interogări de test prin AI Chat
🛠️ Depanarea Problemelor Comune
Probleme Docker
Problema: Containerele Docker nu pornesc
# Verifică starea serviciului Docker
docker info
# Verifică resursele disponibile
docker system df
# Curăță dacă este necesar
docker system prune -f
# Repornește Docker Desktop (Windows/macOS)
# Sau repornește serviciul Docker (Linux)
sudo systemctl restart docker
Problema: Conexiunea PostgreSQL eșuează
# Verificați jurnalele containerului
docker-compose logs postgres
# Verificați dacă containerul este sănătos
docker-compose ps
# Testați conexiunea directă
docker-compose exec postgres psql -U postgres -d zava -c "SELECT 1;"
Probleme Implementare Azure
Problema: Implementarea Azure eșuează
# Verificați autentificarea Azure CLI
az account show
# Verificați permisiunile abonamentului
az role assignment list --assignee $(az account show --query user.name -o tsv)
# Verificați înregistrarea furnizorului de resurse
az provider register --namespace Microsoft.CognitiveServices
az provider register --namespace Microsoft.Insights
Problema: Autentificarea serviciului AI eșuează
# Testați principalul serviciului
az login --service-principal \
--username $AZURE_CLIENT_ID \
--password $AZURE_CLIENT_SECRET \
--tenant $AZURE_TENANT_ID
# Verificați implementarea serviciului AI
az cognitiveservices account list --query "[].{Name:name,Kind:kind,Location:location}"
Probleme Mediu Python
Problema: Instalarea pachetelor eșuează
# Actualizați pip și setuptools
python -m pip install --upgrade pip setuptools wheel
# Goliți cache-ul pip
pip cache purge
# Instalați pachetele unul câte unul pentru a identifica problemele
pip install fastmcp
pip install asyncpg
pip install azure-ai-projects
Problema: VS Code nu poate găsi interpretul Python
# Afișează căile interpretorului Python
which python # macOS/Linux
where python # Windows
# Activează mai întâi mediul virtual
source mcp-env/bin/activate # macOS/Linux
mcp-env\Scripts\activate # Windows
# Apoi deschide VS Code
code .
🎯 Concluzii Cheie
După finalizarea acestui laborator, ar trebui să ai:
✅ Mediu complet de dezvoltare: Toate uneltele instalate și configurate
✅ Resurse Azure implementate: Servicii AI și infrastructura suport
✅ Mediu Docker funcțional: Containere PostgreSQL și server MCP
✅ Integrare VS Code: Servere MCP configurate și accesibile
✅ Configurare validată: Toate componentele testate și lucrând împreună
✅ Cunoștințe de depanare: Probleme comune și soluții
🚀 Ce Urmează
Cu mediul pregătit, continuă cu Laboratorul 04: Designul Bazei de Date și Schema pentru a:
- Explora schema bazei de date retail în detaliu
- Înțelege modelarea datelor multi-chiriaș
- Învață despre implementarea Row Level Security
- Lucra cu date de probă retail
📚 Resurse Suplimentare
Unelte de Dezvoltare
- Documentația Docker - Referință completă Docker
- Referința Azure CLI - Comenzi Azure CLI
- Documentația VS Code - Configurare editor și extensii
Servicii Azure
- Documentația Microsoft Foundry - Configurare serviciu AI
- Serviciul Azure OpenAI - Implementare model AI
- Application Insights - Configurare monitorizare
Dezvoltare Python
- Medii Virtuale Python - Managementul mediilor
- Documentația AsyncIO - Modele programare asincronă
- Documentația FastAPI - Modele framework web
Următorul pas: Mediu gata? Continuă cu Laboratorul 04: Designul Bazei de Date și Schema
Declinare a responsabilității: Acest document a fost tradus folosind serviciul de traducere AI Co-op Translator. În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri.