24 KiB
Miljöinställning
🎯 Vad denna labb täcker
Denna praktiska labb vägleder dig genom att sätta upp en komplett utvecklingsmiljö för att bygga MCP-servrar med PostgreSQL-integration. Du kommer att konfigurera alla nödvändiga verktyg, distribuera Azure-resurser och validera din installation innan du går vidare med implementeringen.
Översikt
En korrekt utvecklingsmiljö är avgörande för framgångsrik MCP-serverutveckling. Denna labb ger steg-för-steg-instruktioner för att installera Docker, Azure-tjänster, utvecklingsverktyg, och att validera att allt fungerar korrekt tillsammans.
I slutet av denna labb kommer du att ha en fullt fungerande utvecklingsmiljö redo för att bygga Zava Retail MCP-servern.
Lärandemål
Efter denna labb kommer du att kunna:
- Installera och konfigurera alla nödvändiga utvecklingsverktyg
- Distribuera Azure-resurser som behövs för MCP-servern
- Sätta upp Docker-containrar för PostgreSQL och MCP-servern
- Validera din miljö med testanslutningar
- Felsöka vanliga installationsproblem och konfigurationsproblem
- Förstå utvecklingsflödet och filstrukturen
📋 Kontroll av förutsättningar
Innan du börjar, säkerställ att du har:
Nödvändiga kunskaper
- Grundläggande användning av kommandoraden (Windows Command Prompt/PowerShell)
- Förståelse för miljövariabler
- Bekantskap med Git versionshantering
- Grundläggande Docker-koncept (containrar, images, volymer)
Systemkrav
- Operativsystem: Windows 10/11, macOS eller Linux
- RAM: Minst 8GB (16GB rekommenderas)
- Lagring: Minst 10GB ledigt utrymme
- Nätverk: Internetanslutning för nedladdningar och Azure-distribution
Kontokrav
- Azure-prenumeration: Gratisnivå räcker
- GitHub-konto: För åtkomst till repository
- Docker Hub-konto: (Valfritt) För publicering av egna images
🛠️ Verktyg installation
1. Installera Docker Desktop
Docker tillhandahåller den containeriserade miljön för vår utvecklingssetup.
Windows Installation
-
Ladda ner Docker Desktop:
# Visit https://desktop.docker.com/win/stable/Docker%20Desktop%20Installer.exe # Or use Windows Package Manager winget install Docker.DockerDesktop -
Installera och konfigurera:
- Kör installationsprogrammet som administratör
- Aktivera WSL 2-integrering när du blir ombedd
- Starta om datorn efter installationen
-
Verifiera installation:
docker --version docker-compose --version
macOS Installation
-
Ladda ner och installera:
# Ladda ner från https://desktop.docker.com/mac/stable/Docker.dmg # Eller använd Homebrew brew install --cask docker -
Starta Docker Desktop:
- Öppna Docker Desktop från Applikationer
- Slutför installationsguiden
-
Verifiera installation:
docker --version docker-compose --version
Linux Installation
-
Installera Docker Engine:
# Ubuntu/Debian curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # Logga ut och logga in igen för att gruppändringar ska träda i kraft -
Installera 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. Installera Azure CLI
Azure CLI möjliggör distribution och hantering av Azure-resurser.
Windows Installation
# Using Windows Package Manager
winget install Microsoft.AzureCLI
# Or download MSI from: https://aka.ms/installazurecliwindows
macOS Installation
# Använda Homebrew
brew install azure-cli
# Eller använda installatör
curl -L https://aka.ms/InstallAzureCli | bash
Linux Installation
# 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
Verifiera och autentisera
# Kontrollera installation
az version
# Logga in på Azure
az login
# Ange standardprenumeration (om du har flera)
az account list --output table
az account set --subscription "Your-Subscription-Name"
3. Installera Git
Git krävs för att klona repository och versionshantering.
Windows
# Using Windows Package Manager
winget install Git.Git
# Or download from: https://git-scm.com/download/win
macOS
# Git är vanligtvis förinstallerat, men du kan uppdatera via Homebrew
brew install git
Linux
# Ubuntu/Debian
sudo apt update && sudo apt install git
# RHEL/CentOS
sudo dnf install git
4. Installera VS Code
Visual Studio Code är den integrerade utvecklingsmiljön med stöd för MCP.
Installation
# Windows
winget install Microsoft.VisualStudioCode
# macOS
brew install --cask visual-studio-code
# Linux (Ubuntu/Debian)
sudo snap install code --classic
Nödvändiga tillägg
Installera dessa tillägg i VS Code:
# Installera via kommandoraden
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
Eller installera via VS Code:
- Öppna VS Code
- Gå till Extensions (Ctrl+Shift+X)
- Installera:
- Python (Microsoft)
- Docker (Microsoft)
- Azure Account (Microsoft)
- JSON (Microsoft)
5. Installera Python
Python 3.8+ krävs för MCP-serverutveckling.
Windows
# Using Windows Package Manager
winget install Python.Python.3.11
# Or download from: https://www.python.org/downloads/
macOS
# Använder 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
Verifiera installation
python --version # Bör visa Python 3.11.x
pip --version # Bör visa pip-version
🚀 Projektsetup
1. Klona repository
# Klona huvudförvaret
git clone https://github.com/microsoft/MCP-Server-and-PostgreSQL-Sample-Retail.git
# Navigera till projektkatalogen
cd MCP-Server-and-PostgreSQL-Sample-Retail
# Verifiera förvarsstruktur
ls -la
2. Skapa Python virtuellt miljö
# Skapa virtuellt miljö
python -m venv mcp-env
# Aktivera virtuellt miljö
# Windows
mcp-env\Scripts\activate
# macOS/Linux
source mcp-env/bin/activate
# Uppgradera pip
python -m pip install --upgrade pip
3. Installera Python-beroenden
# Installera utvecklingsberoenden
pip install -r requirements.lock.txt
# Verifiera nyckelpaket
pip list | grep fastmcp
pip list | grep asyncpg
pip list | grep azure
☁️ Azure resursdistribution
1. Förstå resurskraven
Vår MCP-server kräver dessa Azure-resurser:
| Resurs | Syfte | Uppskattad kostnad |
|---|---|---|
| Microsoft Foundry | AI-modellvärd och hantering | $10-50/månad |
| OpenAI-distribution | Textembeddingmodell (text-embedding-3-small) | $5-20/månad |
| Application Insights | Övervakning och telemetri | $5-15/månad |
| Resursgrupp | Organisation av resurser | Gratis |
2. Distribuera Azure-resurser
Alternativ A: Automatiserad distribution (Rekommenderas)
# Navigera till infrastrukturkatalogen
cd infra
# Windows - PowerShell
./deploy.ps1
# macOS/Linux - Bash
./deploy.sh
Distributionsskriptet kommer att:
- Skapa en unik resursgrupp
- Distribuera Microsoft Foundry-resurser
- Distribuera modellen text-embedding-3-small
- Konfigurera Application Insights
- Skapa en service principal för autentisering
- Generera
.env-fil med konfiguration
Alternativ B: Manuell distribution
Om du föredrar manuell kontroll eller om det automatiserade skriptet misslyckas:
# Sätt variabler
RESOURCE_GROUP="rg-zava-mcp-$(date +%s)"
LOCATION="westus2"
AI_PROJECT_NAME="zava-ai-project"
# Skapa resursgrupp
az group create --name $RESOURCE_GROUP --location $LOCATION
# Distribuera huvudmall
az deployment group create \
--resource-group $RESOURCE_GROUP \
--template-file main.bicep \
--parameters location=$LOCATION \
--parameters resourcePrefix="zava-mcp"
3. Verifiera Azure-distribution
# Kontrollera resursgrupp
az group show --name $RESOURCE_GROUP --output table
# Lista distribuerade resurser
az resource list --resource-group $RESOURCE_GROUP --output table
# Testa AI-tjänst
az cognitiveservices account show \
--name "your-ai-service-name" \
--resource-group $RESOURCE_GROUP
4. Konfigurera miljövariabler
Efter distribution ska du ha en .env-fil. Kontrollera att den innehåller:
# .env-fil innehåll
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;...
# Databaskonfiguration (för utveckling)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=zava
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-secure-password
🐳 Docker-miljöuppsättning
1. Förstå Docker Composition
Vår utvecklingsmiljö använder 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. Starta utvecklingsmiljön
# Se till att du är i projektets rotmapp
cd /path/to/MCP-Server-and-PostgreSQL-Sample-Retail
# Starta tjänsterna
docker-compose up -d
# Kontrollera tjänstens status
docker-compose ps
# Visa loggar
docker-compose logs -f
3. Verifiera databasinställning
# Anslut till PostgreSQL-behållare
docker-compose exec postgres psql -U postgres -d zava
# Kontrollera databassstruktur
\dt retail.*
# Verifiera exempeldata
SELECT COUNT(*) FROM retail.stores;
SELECT COUNT(*) FROM retail.products;
SELECT COUNT(*) FROM retail.orders;
# Avsluta PostgreSQL
\q
4. Testa MCP-server
# Kontrollera MCP-serverns hälsa
curl http://localhost:8000/health
# Testa grundläggande MCP-endpoint
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": {}}'
🔧 VS Code konfiguration
1. Konfigurera MCP-integration
Skapa VS Code MCP-konfiguration:
// .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. Konfigurera Python-miljö
// .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. Testa VS Code-integration
-
Öppna projektet i VS Code:
code . -
Öppna AI Chat:
- Tryck
Ctrl+Shift+P(Windows/Linux) ellerCmd+Shift+P(macOS) - Skriv "AI Chat" och välj "AI Chat: Open Chat"
- Tryck
-
Testa MCP-serveranslutning:
- I AI Chat, skriv
#zavaoch välj en av de konfigurerade servrarna - Fråga: "Vilka tabeller finns i databasen?"
- Du ska få ett svar med en lista över butikens databastabeller
- I AI Chat, skriv
✅ Miljövalidering
1. Omfattande systemkontroll
Kör detta valideringsskript för att verifiera din installation:
# Skapa valideringsskript
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 = {}
# Kontrollera Python-version
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+'
}
# Kontrollera nödvändiga paket
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'}
# Kontrollera 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'}
# Kontrollera 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'}
# Kontrollera miljövariabler
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
}
# Kontrollera databasanslutning
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')
)
# Testfråga
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)
}
# Kontrollera MCP-server
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)
}
# Kontrollera Azure AI-tjänst
try:
credential = DefaultAzureCredential()
project_client = AIProjectClient(
endpoint=os.getenv('PROJECT_ENDPOINT'),
credential=credential
)
# Detta kommer att misslyckas om autentiseringsuppgifterna är ogiltiga
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
# Kör validering
python validate_setup.py
2. Manuellt valideringschecklista
✅ Grundläggande verktyg
- Docker version 20.10+ installerad och igång
- Azure CLI 2.40+ installerad och autentiserad
- Python 3.8+ med pip installerad
- Git 2.30+ installerad
- VS Code med nödvändiga tillägg
✅ Azure-resurser
- Resursgrupp skapad framgångsrikt
- AI Foundry-projekt distribuerat
- OpenAI text-embedding-3-small model distribuerad
- Application Insights konfigurerad
- Service principal skapad med rätt behörigheter
✅ Miljökonfiguration
.env-fil skapad med alla nödvändiga variabler- Azure-referenser fungerar (testa med
az account show) - PostgreSQL-container körs och är tillgänglig
- Exempeldata inläst i databasen
✅ VS Code-integration
.vscode/mcp.jsonkonfigurerad- Python interpreter inställd på virtuellt miljö
- MCP-servrar syns i AI Chat
- Kan köra testfrågor via AI Chat
🛠️ Felsökning av vanliga problem
Docker-problem
Problem: Docker-containrar startar inte
# Kontrollera Docker-tjänstens status
docker info
# Kontrollera tillgängliga resurser
docker system df
# Rensa upp vid behov
docker system prune -f
# Starta om Docker Desktop (Windows/macOS)
# Eller starta om Docker-tjänsten (Linux)
sudo systemctl restart docker
Problem: PostgreSQL-anslutning misslyckas
# Kontrollera containerloggar
docker-compose logs postgres
# Verifiera att containern är frisk
docker-compose ps
# Testa direktanslutning
docker-compose exec postgres psql -U postgres -d zava -c "SELECT 1;"
Azure-distributionsproblem
Problem: Azure-distribution misslyckas
# Kontrollera Azure CLI-autentisering
az account show
# Verifiera prenumerationsbehörigheter
az role assignment list --assignee $(az account show --query user.name -o tsv)
# Kontrollera registrering av resursleverantör
az provider register --namespace Microsoft.CognitiveServices
az provider register --namespace Microsoft.Insights
Problem: AI-tjänstautentisering misslyckas
# Testa serviceprincipal
az login --service-principal \
--username $AZURE_CLIENT_ID \
--password $AZURE_CLIENT_SECRET \
--tenant $AZURE_TENANT_ID
# Verifiera AI-tjänstdistribution
az cognitiveservices account list --query "[].{Name:name,Kind:kind,Location:location}"
Python-miljöproblem
Problem: Paketinstallation misslyckas
# Uppgradera pip och setuptools
python -m pip install --upgrade pip setuptools wheel
# Rensa pip-cache
pip cache purge
# Installera paket ett i taget för att identifiera problem
pip install fastmcp
pip install asyncpg
pip install azure-ai-projects
Problem: VS Code kan inte hitta Python interpreter
# Visa Python-tolkens sökvägar
which python # macOS/Linux
where python # Windows
# Aktivera virtuellt miljö först
source mcp-env/bin/activate # macOS/Linux
mcp-env\Scripts\activate # Windows
# Öppna sedan VS Code
code .
🎯 Viktiga punkter
Efter att ha slutfört denna labb bör du ha:
✅ Komplett utvecklingsmiljö: Alla verktyg installerade och konfigurerade
✅ Azure-resurser distribuerade: AI-tjänster och stödjande infrastruktur
✅ Docker-miljö igång: PostgreSQL och MCP-servercontainrar
✅ VS Code-integration: MCP-servrar konfigurerade och åtkomliga
✅ Verifierad installation: Alla komponenter testade och fungerar tillsammans
✅ Felsökningskunskap: Vanliga problem och lösningar
🚀 Vad är nästa steg
Med din miljö klar, fortsätt till Labb 04: Databasedesign och schema för att:
- Utforska detaljrikedom i retaildatabasens schema
- Förstå multi-tenant datamodellering
- Lära dig om implementering av Row Level Security
- Arbeta med exempeldata från retail
📚 Ytterligare resurser
Utvecklingsverktyg
- Docker Documentation - Komplett Docker-referens
- Azure CLI Reference - Azure CLI-kommandon
- VS Code Documentation - Editor-konfiguration och tillägg
Azure-tjänster
- Microsoft Foundry Documentation - AI-tjänstekonfiguration
- Azure OpenAI Service - AI-modell distribution
- Application Insights - Övervakningsinställningar
Python-utveckling
- Python Virtual Environments - Miljöhantering
- AsyncIO Documentation - Async programmeringsmönster
- FastAPI Documentation - Webb ramverksmönster
Nästa: Miljön klar? Fortsätt med Labb 04: Databasedesign och schema
Ansvarsfriskrivning: Detta dokument har översatts med hjälp av AI-översättningstjänsten Co-op Translator. Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning.