MCP Server en PostgreSQL Voorbeeld - Analyse van Retailverkopen

September 30, 2025 · View on GitHub

Leer MCP met Database-integratie via Praktische Voorbeelden

Volg deze stappen om aan de slag te gaan met deze bronnen:

Fork de Repository: Klik hier om te forken
Clone de Repository: git clone https://github.com/JOUW-GEBRUIKERSNAAM/MCP-Server-and-PostgreSQL-Sample-Retail.git
Word lid van de Azure AI Foundry Discord: Ontmoet experts en medeontwikkelaars

🌐 Meertalige Ondersteuning

Ondersteund via GitHub Action (Automatisch & Altijd Actueel)

Als je extra vertalingen wilt, kun je de ondersteunde talen vinden hier

Dit voorbeeld laat zien hoe je een uitgebreide Model Context Protocol (MCP) server kunt bouwen en implementeren die AI-assistenten veilige, intelligente toegang biedt tot retailverkoopdata via PostgreSQL. Het project toont functies van ondernemingsniveau, zoals Row Level Security (RLS), semantische zoekmogelijkheden, en Azure AI-integratie voor real-world retailanalyses.

Belangrijke Gebruiksscenario's:

AI-gestuurde Verkoopanalyse: AI-assistenten in staat stellen om retailverkoopdata te analyseren via natuurlijke taal
Veilige Multi-Tenant Toegang: Implementatie van Row Level Security waarbij verschillende winkelmanagers alleen toegang hebben tot hun eigen winkeldata
Semantische Productzoekfunctie: AI-gestuurde productontdekking met behulp van tekstembeddings
Integratie op Ondernemingsniveau: Illustratie van hoe MCP-servers kunnen worden geïntegreerd met Azure-services en PostgreSQL-databases

Perfect voor:

Ontwikkelaars die MCP-servers willen bouwen met database-integratie
Data engineers die veilige multi-tenant analysemogelijkheden implementeren
AI-applicatieontwikkelaars die werken met retail- of e-commercedata
Iedereen die geïnteresseerd is in het combineren van AI-assistenten met ondernemingsdatabases

Word lid van de Azure AI Foundry Discord Community

Deel je ervaringen met MCP en ontmoet experts en productgroepen

Verkoopanalyse MCP Server

Een Model Context Protocol (MCP) server die uitgebreide toegang biedt tot klantverkoopdatabases voor Zava Retail DIY Business. Deze server stelt AI-assistenten in staat om retailverkoopdata te analyseren via een veilige, schema-bewuste interface.

📚 Complete Implementatiehandleiding

Voor een gedetailleerde uitleg over hoe deze oplossing is gebouwd en hoe je soortgelijke MCP-servers kunt implementeren, zie onze uitgebreide Voorbeeld Walkthrough. Deze handleiding biedt:

Architectuur Uitleg: Analyse van componenten en ontwerpprincipes
Stap-voor-Stap Bouwproces: Van projectopzet tot implementatie
Code Uitleg: Gedetailleerde uitleg van MCP-serverimplementatie
Geavanceerde Functies: Row Level Security, semantische zoekfunctie en monitoring
Best Practices: Richtlijnen voor beveiliging, prestaties en ontwikkeling
Probleemoplossing: Veelvoorkomende problemen en oplossingen

Perfect voor ontwikkelaars die de implementatiedetails willen begrijpen en soortgelijke oplossingen willen bouwen.

🤖 Wat is MCP (Model Context Protocol)?

Model Context Protocol (MCP) is een open standaard die AI-assistenten in staat stelt om veilig toegang te krijgen tot externe databronnen en tools in real-time. Zie het als een brug die AI-modellen verbindt met databases, API's, bestandssystemen en andere bronnen, terwijl beveiliging en controle behouden blijven.

Belangrijke Voordelen:

Real-time Data Toegang: AI-assistenten kunnen live databases en API's raadplegen
Veilige Integratie: Gecontroleerde toegang met authenticatie en machtigingen
Tool Uitbreidbaarheid: Voeg aangepaste mogelijkheden toe aan AI-assistenten
Gestandaardiseerd Protocol: Werkt met verschillende AI-platforms en tools

Nieuw bij MCP?

Als je nieuw bent met Model Context Protocol, raden we aan om te beginnen met Microsoft's uitgebreide beginnersbronnen:

📖 MCP voor Beginners Handleiding

Deze bron biedt:

Introductie tot MCP-concepten en architectuur
Stap-voor-stap tutorials voor het bouwen van je eerste MCP-server
Best practices voor MCP-ontwikkeling
Integratievoorbeelden met populaire AI-platforms
Communitybronnen en ondersteuning

Zodra je de basis begrijpt, kom dan hier terug om deze geavanceerde retailanalyse-implementatie te verkennen!

📚 Uitgebreide Leerhandleiding: /walkthrough

Deze repository bevat een complete 12-module leerwalkthrough die dit MCP-retailservervoorbeeld opsplitst in behapbare, stap-voor-stap lessen. De walkthrough transformeert dit werkende voorbeeld in een uitgebreide educatieve bron, perfect voor ontwikkelaars die willen begrijpen hoe ze productieklare MCP-servers met database-integratie kunnen bouwen.

Wat Je Leert

De walkthrough behandelt alles, van basis MCP-concepten tot geavanceerde productie-implementatie, inclusief:

MCP Basisprincipes: Begrip van het Model Context Protocol en de toepassingen in de praktijk
Database-integratie: Implementatie van veilige PostgreSQL-connectiviteit met Row Level Security
AI-Verbeterde Functies: Toevoegen van semantische zoekmogelijkheden met Azure OpenAI embeddings
Beveiligingsimplementatie: Authenticatie, autorisatie en data-isolatie op ondernemingsniveau
Toolontwikkeling: Het bouwen van geavanceerde MCP-tools voor data-analyse en bedrijfsinformatie
Testen & Debuggen: Uitgebreide teststrategieën en debuggingtechnieken
VS Code Integratie: Configuratie van AI Chat voor natuurlijke taal database queries
Productie-implementatie: Containerisatie, schaalbaarheid en cloud-implementatiestrategieën
Monitoring & Observatie: Application Insights, logging en prestatiemonitoring

Overzicht Leerpad

De walkthrough volgt een progressieve leerstructuur, ontworpen voor ontwikkelaars van alle niveaus:

Module	Focusgebied	Beschrijving	Tijdschatting
00-Introductie	Basis	MCP-concepten, Zava Retail casestudy, architectuuroverzicht	30 minuten
01-Architectuur	Ontwerpprincipes	Technische architectuur, gelaagd ontwerp, systeemcomponenten	45 minuten
02-Beveiliging	Ondernemingsbeveiliging	Azure-authenticatie, Row Level Security, multi-tenant isolatie	60 minuten
03-Setup	Omgeving	Docker setup, Azure CLI, projectconfiguratie, validatie	45 minuten
04-Database	Datalaag	PostgreSQL-schema, pgvector, RLS-beleid, voorbeelddata	60 minuten
05-MCP-Server	Kernimplementatie	FastMCP-framework, database-integratie, connectiebeheer	90 minuten
06-Tools	Toolontwikkeling	MCP-toolcreatie, queryvalidatie, bedrijfsinformatie functies	75 minuten
07-Semantische Zoekfunctie	AI-integratie	Azure OpenAI embeddings, vectorzoekfunctie, hybride zoekstrategieën	60 minuten
08-Testen	Kwaliteitsborging	Unit testing, integratietesten, prestatietesten, debugging	75 minuten
09-VS-Code	Ontwikkelaarservaring	VS Code configuratie, AI Chat integratie, debugging workflows	45 minuten
10-Implementatie	Productieklaar	Containerisatie, Azure Container Apps, CI/CD-pipelines, schaalbaarheid	90 minuten
11-Monitoring	Observatie	Application Insights, gestructureerde logging, prestatiemetrics	60 minuten
12-Best Practices	Productie-excellentie	Beveiligingsversterking, prestatieoptimalisatie, ondernemingspatronen	45 minuten

Totale Leertijd: ~12-15 uur aan uitgebreide praktische leerervaring

🎯 Hoe de Walkthrough te Gebruiken

Voor Beginners:

Begin met Module 00: Introductie om MCP-basisprincipes te begrijpen
Volg de modules in volgorde voor een complete leerervaring
Elke module bouwt voort op eerdere concepten en bevat praktische oefeningen

Voor Ervaren Ontwikkelaars:

Bekijk de Hoofdoverzicht Walkthrough voor een samenvatting van alle modules
Spring naar specifieke modules die je interesseren (bijv. Module 07 voor AI-integratie)
Gebruik individuele modules als referentiemateriaal voor je eigen projecten

Voor Productie-implementatie:

Focus op Modules 02 (Beveiliging), 10 (Implementatie), en 11 (Monitoring)
Bekijk Module 12 (Best Practices) voor richtlijnen op ondernemingsniveau
Gebruik de codevoorbeelden als productieklare templates

🚀 Snelle Startopties

Optie 1: Compleet Leerpad (Aanbevolen voor nieuwkomers)

# Clone and start with the introduction
git clone https://github.com/microsoft/MCP-Server-and-PostgreSQL-Sample-Retail.git
cd MCP-Server-and-PostgreSQL-Sample-Retail/walkthrough
# Follow along starting with 00-Introduction/README.md

Optie 2: Praktische Implementatie (Direct beginnen met bouwen)

# Start with setup and build as you learn
cd walkthrough/03-Setup
# Follow the setup guide and continue through implementation modules

Optie 3: Productiefocus (Ondernemingsimplementatie)

# Focus on production-ready aspects
# Review modules: 02-Security, 10-Deployment, 11-Monitoring, 12-Best-Practices

📋 Leervereisten

Aanbevolen achtergrond:

Basiservaring met Python-programmering
Bekendheid met REST API's en databases
Algemeen begrip van AI/ML-concepten
Basiskennis van de command-line en Docker

Niet vereist (maar handig):

Eerdere MCP-ervaring (we behandelen dit vanaf het begin)
Ervaring met Azure-cloud (we bieden stapsgewijze begeleiding)
Geavanceerde kennis van PostgreSQL (we leggen concepten uit indien nodig)

💡 Leertips

Praktische aanpak: Elk module bevat werkende codevoorbeelden die je kunt uitvoeren en aanpassen
Geleidelijke complexiteit: Concepten bouwen geleidelijk op van eenvoudig naar geavanceerd
Reële context: Alle voorbeelden gebruiken realistische scenario's uit de retailsector
Productieklaar: Codevoorbeelden zijn ontworpen voor daadwerkelijk gebruik in productie
Communityondersteuning: Word lid van onze Discord-community voor hulp en discussies

🔗 Gerelateerde bronnen

MCP voor beginners: Essentiële achtergrondinformatie
Voorbeeld walkthrough: Technisch overzicht op hoog niveau
Azure AI Foundry: Cloudplatform gebruikt in de voorbeelden
FastMCP Framework: Python MCP-implementatiekader

Klaar om te beginnen? Start met Module 00: Introductie of bekijk het volledige walkthrough-overzicht.

Vereisten

Docker Desktop geïnstalleerd
Git geïnstalleerd
Azure CLI: Installeer en log in met Azure CLI
Toegang tot het OpenAI-model text-embedding-3-small en optioneel het model gpt-4o-mini.

Aan de slag

Open een terminalvenster en voer de volgende opdrachten uit:

Clone de repository

git clone https://github.com/gloveboxes/Zava-MCP-Server-and-PostgreSQL-Sample

Navigeer naar de projectmap

cd Zava-MCP-Server-and-PostgreSQL-Sample

Azure-resources implementeren

Voer de volgende scripts uit om de implementatie van Azure-resources die nodig zijn voor de MCP-server te automatiseren.

De implementatiescripts zullen automatisch het model text-embedding-3-small implementeren. Tijdens de implementatie heb je de optie om ook het model gpt-4o-mini op te nemen. Let op: gpt-4o-mini is niet vereist voor dit project en is alleen opgenomen voor mogelijke toekomstige uitbreidingen.

Kies het script voor jouw platform:

Windows (PowerShell)

# Run from the project root directory
cd infra && ./deploy.ps1

macOS/Linux (Bash)

# Run from the project root directory
cd infra && ./deploy.sh

De MCP-server uitvoeren

De eenvoudigste manier om de volledige stack (PostgreSQL + MCP-server) uit te voeren is met Docker Compose:

Start de stack

# Start PostgreSQL and MCP Server
docker compose up -d

# View logs
docker compose logs -f

# View MCP Server Logs
docker compose logs -f mcp_server

# View the PostgreSQL Logs
docker compose logs -f pg17

# Stop the stack
docker compose down -v

Gebruik

De volgende stappen gaan ervan uit dat je de ingebouwde ondersteuning voor MCP-servers in VS Code gebruikt.

Open het project in VS Code. Voer vanuit de terminal uit:
```
code .
```

Start een of meer MCP-servers met behulp van de configuraties in .vscode/mcp.json. Het bestand bevat vier verschillende serverconfiguraties, die elk een andere rol van een winkelmanager vertegenwoordigen:

Elke configuratie gebruikt een unieke RLS (Row Level Security) gebruikers-ID
Deze gebruikers-ID's simuleren verschillende identiteiten van winkelmanagers die toegang hebben tot de database
Het RLS-systeem beperkt de toegang tot gegevens op basis van de toegewezen winkel van de manager
Dit bootst realistische scenario's na waarin winkelmanagers inloggen met verschillende Entra ID-accounts

{
    "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"}
        },
        "zava-sales-analysis-online": {
            "url": "http://127.0.0.1:8000/mcp",
            "type": "http",
            "headers": {"x-rls-user-id": "2f4e6d8c-1a3b-5c7e-9f0a-b2d4f6e8c0a2"}
        }
    },
    "inputs": []
}

Open VS Code AI Chat

Open de AI Chat-modus in VS Code
Typ #zava en selecteer een van de MCP-servers die je hebt gestart
Stel vragen over de verkoopgegevens - Zie voorbeeldvragen hieronder

Voorbeeldvragen

Toon de top 20 producten op basis van omzet
Toon verkoop per winkel
Wat waren de verkoopcijfers per categorie van het afgelopen kwartaal?
Welke producten verkopen we die vergelijkbaar zijn met "containers voor verf"?

Functies

Toegang tot meerdere tabellen: Haal schema's op voor meerdere databasetabellen in één verzoek
Veilige query-uitvoering: Voer PostgreSQL-query's uit met ondersteuning voor Row Level Security (RLS)
Realtime gegevens: Toegang tot actuele verkoop-, voorraad- en klantgegevens
Datum/tijd-hulpmiddelen: Verkrijg huidige UTC-tijdstempels voor tijdgevoelige analyses
Flexibele implementatie: Ondersteunt HTTP-servermodus

Ondersteunde tabellen

De server biedt toegang tot de volgende retail-databasetabellen:

retail.customers - Klantinformatie en profielen
retail.stores - Winkellocaties en details
retail.categories - Productcategorieën en hiërarchieën
retail.product_types - Classificaties van producttypen
retail.products - Productcatalogus en specificaties
retail.orders - Klantbestellingen en transacties
retail.order_items - Individuele items binnen bestellingen
retail.inventory - Huidige voorraadniveaus en voorraadgegevens

Beschikbare tools

`get_multiple_table_schemas`

Haal databasetabellen op voor meerdere tabellen in één verzoek.

Parameters:

table_names (list[str]): Lijst met geldige tabelnamen van de bovenstaande ondersteunde tabellen

Retourneert: Gecombineerde schema-strings voor de gevraagde tabellen

`execute_sales_query`

Voer PostgreSQL-query's uit op de verkoopdatabase met Row Level Security.

Parameters:

postgresql_query (str): Een goed gevormde PostgreSQL-query

Retourneert: Queryresultaten geformatteerd als een string (beperkt tot 20 rijen voor leesbaarheid)

Best practices:

Haal altijd eerst tabelschema's op
Gebruik exacte kolomnamen uit schema's
Combineer gerelateerde tabellen voor uitgebreide analyses
Aggregeer resultaten waar nodig
Beperk de uitvoer voor leesbaarheid

`get_current_utc_date`

Verkrijg de huidige UTC-datum en -tijd in ISO-formaat.

Retourneert: Huidige UTC-datum/tijd in ISO-formaat (YYYY-MM-DDTHH:MM:SS.fffffZ)

`semantic_search_products`

Voer een semantische zoekopdracht uit naar producten op basis van gebruikersvragen.

Retourneert: Een lijst met producten die overeenkomen met de zoekcriteria

Parameters:

query (str): De zoekopdrachtstring

Retourneert: Een lijst met producten die overeenkomen met de zoekcriteria

Beveiligingsfuncties

Row Level Security (RLS)

De server implementeert Row Level Security om ervoor te zorgen dat gebruikers alleen toegang hebben tot gegevens waarvoor ze geautoriseerd zijn:

HTTP-modus: Gebruikt de x-rls-user-id-header om de verzoekende gebruiker te identificeren
Standaard fallback: Gebruikt een placeholder UUID wanneer geen gebruikers-ID wordt verstrekt

Winkel-specifieke RLS-gebruikers-ID's

Elke Zava Retail-winkellocatie heeft een unieke RLS-gebruikers-ID die bepaalt welke gegevens de gebruiker kan bekijken:

Winkellocatie	RLS-gebruikers-ID	Beschrijving
Globale toegang	`00000000-0000-0000-0000-000000000000`	Standaard fallback - toegang tot alle winkels
Seattle	`f47ac10b-58cc-4372-a567-0e02b2c3d479`	Zava Retail Seattle winkelgegevens
Bellevue	`6ba7b810-9dad-11d1-80b4-00c04fd430c8`	Zava Retail Bellevue winkelgegevens
Tacoma	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`	Zava Retail Tacoma winkelgegevens
Spokane	`d8e9f0a1-b2c3-4567-8901-234567890abc`	Zava Retail Spokane winkelgegevens
Everett	`3b9ac9fa-cd5e-4b92-a7f2-b8c1d0e9f2a3`	Zava Retail Everett winkelgegevens
Redmond	`e7f8a9b0-c1d2-3e4f-5678-90abcdef1234`	Zava Retail Redmond winkelgegevens
Kirkland	`9c8b7a65-4321-fed0-9876-543210fedcba`	Zava Retail Kirkland winkelgegevens
Online	`2f4e6d8c-1a3b-5c7e-9f0a-b2d4f6e8c0a2`	Zava Retail Online winkelgegevens

RLS-implementatie

Wanneer een gebruiker verbinding maakt met een specifieke winkel-RLS-gebruikers-ID, ziet hij alleen:

Klanten die aan die winkel zijn gekoppeld
Bestellingen geplaatst bij die winkellocatie
Voorraadgegevens voor die specifieke winkel
Winkel-specifieke verkoop- en prestatiestatistieken

Dit zorgt voor gegevensisolatie tussen verschillende winkellocaties terwijl een uniforme databasestructuur behouden blijft.

Architectuur

Applicatiecontext

De server gebruikt een beheerde applicatiecontext met:

Databaseverbindingpool: Efficiënt beheer van verbindingen voor HTTP-modus
Levenscyclusbeheer: Correcte opruiming van resources bij afsluiten
Typeveiligheid: Sterk getypeerde context met AppContext dataclass

Verzoekcontext

Headerextractie: Veilige header parsing voor gebruikersidentificatie
RLS-integratie: Automatische gebruikers-ID-resolutie vanuit de verzoekcontext
Foutafhandeling: Uitgebreide foutafhandeling met gebruiksvriendelijke berichten

Database-integratie

De server integreert met een PostgreSQL-database via de klasse PostgreSQLSchemaProvider:

Verbindingspooling: Gebruikt asynchrone verbindingspools voor schaalbaarheid
Schema-metadata: Biedt gedetailleerde informatie over tabelschema's
Query-uitvoering: Veilige query-uitvoering met RLS-ondersteuning
Resourcebeheer: Automatische opruiming van databasebronnen

Foutafhandeling

De server implementeert robuuste foutafhandeling:

Tabelvalidatie: Zorgt ervoor dat alleen geldige tabelnamen worden benaderd
Queryvalidatie: Valideert PostgreSQL-query's voordat ze worden uitgevoerd
Resourcebeheer: Correcte opruiming, zelfs tijdens fouten
Gebruiksvriendelijke berichten: Duidelijke foutmeldingen voor probleemoplossing

Beveiligingsoverwegingen

Row Level Security: Alle query's respecteren RLS-beleid op basis van gebruikersidentiteit
Gegevensisolatie per winkel: Elke winkel-RLS-gebruikers-ID zorgt ervoor dat alleen gegevens van die winkel toegankelijk zijn
Invoervalidatie: Tabelnamen en query's worden gevalideerd voordat ze worden uitgevoerd
Resourcebeperkingen: Queryresultaten zijn beperkt om overmatig gebruik van resources te voorkomen
Veilige verbindingen: Gebruikt veilige databaseverbindingen
Verificatie van gebruikersidentiteit: Zorg altijd dat de juiste RLS-gebruikers-ID wordt gebruikt voor de beoogde winkellocatie

Belangrijke beveiligingsnotities

Gebruik nooit productie-RLS-gebruikers-ID's in ontwikkelomgevingen
Controleer altijd of de RLS-gebruikers-ID overeenkomt met de beoogde winkel voordat je query's uitvoert
De standaard UUID (00000000-0000-0000-0000-000000000000) biedt beperkte toegang
Elke winkelmanager mag alleen toegang hebben tot de RLS-gebruikers-ID van zijn winkel

Ontwikkeling

Projectstructuur

mcp_server/
├── sales_analysis.py          # Main MCP server implementation
├── sales_analysis_postgres.py # PostgreSQL integration layer
├── sales_analysis_text_embedding.py # Text embedding for semantic search tool

Belangrijke componenten

FastMCP-server: Moderne MCP-serverimplementatie met ondersteuning voor async
PostgreSQL-provider: Database-abstractielaag met RLS-ondersteuning
Contextbeheer: Typeveilig applicatie- en verzoekcontextbeheer
Toolregistratie: Declaratieve toolregistratie met Pydantic-validatie

Bijdragen

Bij het bijdragen aan deze server:

Zorg ervoor dat alle databasequery's Row Level Security respecteren
Voeg correcte foutafhandeling toe voor nieuwe tools
Werk deze README bij met nieuwe functies of wijzigingen
Test de HTTP-servermodus
Valideer invoerparameters en geef duidelijke foutmeldingen

Licentie

Deze MCP-server biedt veilige, efficiënte toegang tot Zava Retail-verkoopgegevens voor AI-gestuurde analyses en inzichten.

Disclaimer:
Dit document is vertaald met behulp van de AI-vertalingsservice Co-op Translator. Hoewel we streven naar nauwkeurigheid, dient u zich ervan bewust te zijn dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor cruciale informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling.