MCP सर्भर र PostgreSQL नमूना - खुद्रा बिक्री विश्लेषण

September 30, 2025 · View on GitHub

डेटाबेस एकीकरणसहित MCP सिक्ने व्यावहारिक उदाहरणहरू

यी स्रोतहरू प्रयोग गर्न सुरु गर्नका लागि निम्न चरणहरू पालना गर्नुहोस्:

रिपोजिटरी फोर्क गर्नुहोस्: यहाँ क्लिक गरेर फोर्क गर्नुहोस्
रिपोजिटरी क्लोन गर्नुहोस्: git clone https://github.com/YOUR-USERNAME/MCP-Server-and-PostgreSQL-Sample-Retail.git
Azure AI Foundry Discord मा सामेल हुनुहोस्: विशेषज्ञहरू र अन्य विकासकर्तासँग भेट्नुहोस्

🌐 बहुभाषी समर्थन

GitHub Action मार्फत समर्थित (स्वचालित र सधैं अद्यावधिक)

यदि तपाईं थप भाषाहरूको अनुवाद चाहनुहुन्छ भने, समर्थित भाषाहरूको सूची यहाँ उपलब्ध छ।

परिचय

यो नमूनाले Model Context Protocol (MCP) सर्भर निर्माण र परिनियोजन कसरी गर्ने भनेर देखाउँछ, जसले AI सहायकहरूलाई PostgreSQL मार्फत खुद्रा बिक्री डाटामा सुरक्षित र बुद्धिमानी पहुँच प्रदान गर्दछ। परियोजनाले Row Level Security (RLS), अर्थपूर्ण खोज क्षमता, र Azure AI एकीकरण जस्ता उद्यम-स्तरीय सुविधाहरू प्रदर्शन गर्दछ, वास्तविक खुद्रा विश्लेषण परिदृश्यहरूको लागि।

मुख्य प्रयोगका केसहरू:

AI-संचालित बिक्री विश्लेषण: AI सहायकहरूलाई प्राकृतिक भाषाको माध्यमबाट खुद्रा बिक्री डाटा सोधपुछ र विश्लेषण गर्न सक्षम बनाउनुहोस्
सुरक्षित बहु-प्रयोगकर्ता पहुँच: Row Level Security कार्यान्वयन देखाउनुहोस् जहाँ विभिन्न स्टोर प्रबन्धकहरूले केवल आफ्नो स्टोरको डाटामा पहुँच गर्न सक्छन्
अर्थपूर्ण उत्पादन खोज: पाठ एम्बेडिङ प्रयोग गरेर AI-सुधारिएको उत्पादन खोज प्रदर्शन गर्नुहोस्
उद्यम एकीकरण: MCP सर्भरहरूलाई Azure सेवाहरू र PostgreSQL डेटाबेसहरूसँग कसरी एकीकृत गर्ने भनेर देखाउनुहोस्

उपयुक्त छ:

MCP सर्भरहरू निर्माण गर्न सिक्ने विकासकर्ताहरू
सुरक्षित बहु-प्रयोगकर्ता विश्लेषण समाधान कार्यान्वयन गर्ने डाटा इन्जिनियरहरू
खुद्रा वा ई-कमर्स डाटासँग काम गर्ने AI अनुप्रयोग विकासकर्ताहरू
AI सहायकहरूलाई उद्यम डेटाबेसहरूसँग संयोजन गर्न इच्छुक जो कोही

Azure AI Foundry Discord समुदायमा सामेल हुनुहोस्

MCP को अनुभव साझा गर्नुहोस् र विशेषज्ञहरू तथा उत्पादन समूहहरूसँग भेट्नुहोस्

बिक्री विश्लेषण MCP सर्भर

Zava Retail DIY व्यवसायको लागि व्यापक ग्राहक बिक्री डेटाबेस पहुँच प्रदान गर्ने Model Context Protocol (MCP) सर्भर। यो सर्भरले AI सहायकहरूलाई सुरक्षित, स्कीमा-सचेत इन्टरफेस मार्फत खुद्रा बिक्री डाटा सोधपुछ र विश्लेषण गर्न सक्षम बनाउँछ।

📚 पूर्ण कार्यान्वयन मार्गदर्शन

यो समाधान कसरी निर्माण गरिएको छ र समान MCP सर्भरहरू कार्यान्वयन गर्ने तरिकाको विस्तृत विवरणको लागि हाम्रो नमूना वाकथ्रु हेर्नुहोस्। यो मार्गदर्शनले प्रदान गर्दछ:

आर्किटेक्चर गहिरो विश्लेषण: घटक विश्लेषण र डिजाइन ढाँचा
चरण-दर-चरण निर्माण: परियोजना सेटअपदेखि परिनियोजनसम्म
कोड ब्रेकडाउन: MCP सर्भर कार्यान्वयनको विस्तृत व्याख्या
उन्नत सुविधाहरू: Row Level Security, अर्थपूर्ण खोज, र निगरानी
सर्वोत्तम अभ्यासहरू: सुरक्षा, प्रदर्शन, र विकास दिशानिर्देशहरू
समस्या समाधान: सामान्य समस्याहरू र समाधानहरू

समान समाधानहरू निर्माण गर्न चाहने विकासकर्ताहरूका लागि उपयुक्त।

🤖 MCP (Model Context Protocol) के हो?

Model Context Protocol (MCP) एक खुला मानक हो जसले AI सहायकहरूलाई वास्तविक समयमा बाह्य डाटा स्रोतहरू र उपकरणहरूमा सुरक्षित पहुँच प्रदान गर्दछ। यसलाई AI मोडेलहरूलाई डेटाबेस, API, फाइल प्रणाली, र अन्य स्रोतहरूसँग सुरक्षा र नियन्त्रण कायम राख्दै जडान गर्न अनुमति दिने पुलको रूपमा सोच्न सकिन्छ।

मुख्य फाइदाहरू:

वास्तविक-समय डाटा पहुँच: AI सहायकहरूले प्रत्यक्ष डेटाबेस र API सोधपुछ गर्न सक्छन्
सुरक्षित एकीकरण: प्रमाणीकरण र अनुमति सहितको नियन्त्रण गरिएको पहुँच
उपकरण विस्तारशीलता: AI सहायकहरूमा अनुकूलित क्षमता थप्नुहोस्
मानकीकृत प्रोटोकल: विभिन्न AI प्लेटफर्महरू र उपकरणहरूमा काम गर्दछ

MCP नयाँ हो?

यदि तपाईं Model Context Protocol मा नयाँ हुनुहुन्छ भने, Microsoft को व्यापक प्रारम्भिक स्रोतहरूबाट सुरु गर्न सिफारिस गरिन्छ:

📖 MCP प्रारम्भिक मार्गदर्शन

यो स्रोतले प्रदान गर्दछ:

MCP अवधारणाहरू र आर्किटेक्चरको परिचय
पहिलो MCP सर्भर निर्माणका लागि चरण-दर-चरण ट्यूटोरियलहरू
MCP विकासका लागि सर्वोत्तम अभ्यासहरू
लोकप्रिय AI प्लेटफर्महरूसँग एकीकरणका उदाहरणहरू
समुदाय स्रोतहरू र समर्थन

एकपटक तपाईंले आधारभूत कुरा बुझ्नुभयो भने, यहाँ फर्केर खुद्रा विश्लेषणको यो उन्नत कार्यान्वयन अन्वेषण गर्नुहोस्!

📚 व्यापक सिक्ने मार्गदर्शन: /walkthrough

यो रिपोजिटरीले 12-मोड्युल सिक्ने वाकथ्रु समावेश गर्दछ, जसले यो MCP खुद्रा सर्भर नमूनालाई चरण-दर-चरण पाठहरूमा विभाजन गर्दछ। वाकथ्रुले यो कार्यरत उदाहरणलाई उत्पादन-तयार MCP सर्भरहरू डेटाबेस एकीकरणसहित निर्माण गर्न चाहने विकासकर्ताहरूका लागि व्यापक शैक्षिक स्रोतमा रूपान्तरण गर्दछ।

तपाईंले के सिक्नुहुनेछ

वाकथ्रुले आधारभूत MCP अवधारणाहरूदेखि उन्नत उत्पादन परिनियोजनसम्म सबै कुरा समेट्छ, जसमा समावेश छ:

MCP आधारभूत कुरा: Model Context Protocol र यसको वास्तविक-विश्व अनुप्रयोगहरू बुझ्दै
डेटाबेस एकीकरण: Row Level Security सहित सुरक्षित PostgreSQL कनेक्टिविटी कार्यान्वयन गर्दै
AI-सुधारिएको सुविधाहरू: Azure OpenAI एम्बेडिङसहित अर्थपूर्ण खोज क्षमता थप्दै
सुरक्षा कार्यान्वयन: उद्यम-स्तरीय प्रमाणीकरण, अनुमति, र डाटा अलगाव
उपकरण विकास: डाटा विश्लेषण र व्यापार बुद्धिमत्ताका लागि परिष्कृत MCP उपकरणहरू निर्माण गर्दै
परीक्षण र डिबगिङ: व्यापक परीक्षण रणनीतिहरू र डिबगिङ प्रविधिहरू
VS Code एकीकरण: प्राकृतिक भाषाको डेटाबेस सोधपुछका लागि AI च्याट कन्फिगर गर्दै
उत्पादन परिनियोजन: कन्टेनराइजेशन, स्केलिङ, र क्लाउड परिनियोजन रणनीतिहरू
निगरानी र अवलोकनीयता: एप्लिकेशन इनसाइट्स, लगिङ, र प्रदर्शन निगरानी

सिक्ने मार्ग अवलोकन

वाकथ्रुले सबै स्तरका विकासकर्ताहरूका लागि डिजाइन गरिएको प्रगतिशील सिक्ने संरचना पालना गर्दछ:

मोड्युल	केन्द्रित क्षेत्र	विवरण	समय अनुमान
00-परिचय	आधार	MCP अवधारणाहरू, Zava Retail केस अध्ययन, आर्किटेक्चर अवलोकन	३० मिनेट
01-आर्किटेक्चर	डिजाइन ढाँचा	प्राविधिक आर्किटेक्चर, स्तरित डिजाइन, प्रणाली घटकहरू	४५ मिनेट
02-सुरक्षा	उद्यम सुरक्षा	Azure प्रमाणीकरण, Row Level Security, बहु-प्रयोगकर्ता अलगाव	६० मिनेट
03-सेटअप	वातावरण	Docker सेटअप, Azure CLI, परियोजना कन्फिगरेसन, मान्यता	४५ मिनेट
04-डेटाबेस	डाटा तह	PostgreSQL स्कीमा, pgvector, RLS नीतिहरू, नमूना डाटा	६० मिनेट
05-MCP-सर्भर	मुख्य कार्यान्वयन	FastMCP फ्रेमवर्क, डेटाबेस एकीकरण, कनेक्शन व्यवस्थापन	९० मिनेट
06-उपकरणहरू	उपकरण विकास	MCP उपकरण निर्माण, सोधपुछ मान्यता, व्यापार बुद्धिमत्ता सुविधाहरू	७५ मिनेट
07-अर्थपूर्ण-खोज	AI एकीकरण	Azure OpenAI एम्बेडिङ, भेक्टर खोज, हाइब्रिड खोज रणनीतिहरू	६० मिनेट
08-परीक्षण	गुणस्तर आश्वासन	युनिट परीक्षण, एकीकरण परीक्षण, प्रदर्शन परीक्षण, डिबगिङ	७५ मिनेट
09-VS-Code	विकास अनुभव	VS Code कन्फिगरेसन, AI च्याट एकीकरण, डिबगिङ वर्कफ्लोहरू	४५ मिनेट
10-परिनियोजन	उत्पादन तयार	कन्टेनराइजेशन, Azure Container Apps, CI/CD पाइपलाइनहरू, स्केलिङ	९० मिनेट
11-निगरानी	अवलोकनीयता	एप्लिकेशन इनसाइट्स, संरचित लगिङ, प्रदर्शन मेट्रिक्स	६० मिनेट
12-सर्वोत्तम-अभ्यासहरू	उत्पादन उत्कृष्टता	सुरक्षा कडा बनाउने, प्रदर्शन अनुकूलन, उद्यम ढाँचाहरू	४५ मिनेट

कुल सिक्ने समय: ~१२-१५ घण्टा व्यापक व्यावहारिक सिकाइ

🎯 वाकथ्रु कसरी प्रयोग गर्ने

नवीनहरूका लागि:

MCP आधारभूत कुरा बुझ्न मोड्युल 00: परिचय बाट सुरु गर्नुहोस्
पूर्ण सिक्ने अनुभवका लागि मोड्युलहरू क्रमिक रूपमा पालना गर्नुहोस्
प्रत्येक मोड्युलले अघिल्लो अवधारणाहरूमा निर्माण गर्दछ र व्यावहारिक अभ्यासहरू समावेश गर्दछ

अनुभवी विकासकर्ताहरूका लागि:

मुख्य वाकथ्रु अवलोकन समीक्षा गर्नुहोस् जसले सम्पूर्ण मोड्युल सारांश प्रदान गर्दछ
तपाईंलाई चासो लाग्ने विशिष्ट मोड्युलहरूमा जानुहोस् (जस्तै, मोड्युल 07 AI एकीकरणका लागि)
आफ्ना परियोजनाहरूका लागि व्यक्तिगत मोड्युलहरूलाई सन्दर्भ सामग्रीको रूपमा प्रयोग गर्नुहोस्

उत्पादन कार्यान्वयनका लागि:

मोड्युल 02 (सुरक्षा), 10 (परिनियोजन), र 11 (निगरानी) मा ध्यान केन्द्रित गर्नुहोस्
उद्यम दिशानिर्देशहरूको लागि मोड्युल 12 (सर्वोत्तम अभ्यासहरू) समीक्षा गर्नुहोस्
उत्पादन-तयार टेम्पलेटहरूका रूपमा कोड उदाहरणहरू प्रयोग गर्नुहोस्

🚀 छिटो सुरु गर्ने विकल्पहरू

विकल्प 1: पूर्ण सिक्ने मार्ग (नवीनहरूका लागि सिफारिस गरिएको)

# 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

विकल्प 2: व्यावहारिक कार्यान्वयन (सिधै निर्माणमा सुरु गर्नुहोस्)

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

विकल्प 3: उत्पादन केन्द्रित (उद्यम परिनियोजन)

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

📋 सिक्न आवश्यकताहरू

सिफारिस गरिएको पृष्ठभूमि:

आधारभूत Python प्रोग्रामिङ अनुभव
REST APIs र डेटाबेससँग परिचितता
AI/ML अवधारणाहरूको सामान्य समझ
आधारभूत कमाण्ड-लाइन र Docker ज्ञान

आवश्यक छैन (तर उपयोगी):

पहिलेको MCP अनुभव (हामी यो सुरुबाट कभर गर्छौं)
Azure क्लाउड अनुभव (हामी चरण-दर-चरण मार्गदर्शन प्रदान गर्छौं)
उन्नत PostgreSQL ज्ञान (हामी आवश्यक परेमा अवधारणाहरू व्याख्या गर्छौं)

💡 सिक्ने सुझावहरू

व्यावहारिक दृष्टिकोण: प्रत्येक मोड्युलमा काम गर्ने कोड उदाहरणहरू समावेश छन् जुन तपाईं चलाउन र संशोधन गर्न सक्नुहुन्छ।
क्रमिक जटिलता: अवधारणाहरू सरलदेखि उन्नतसम्म क्रमिक रूपमा निर्माण गरिन्छ।
वास्तविक-विश्व सन्दर्भ: सबै उदाहरणहरू यथार्थपरक खुद्रा व्यवसाय परिदृश्यहरू प्रयोग गर्छन्।
उत्पादनको लागि तयार: कोड उदाहरणहरू वास्तविक उत्पादन प्रयोगको लागि डिजाइन गरिएको छ।
समुदाय समर्थन: मद्दत र छलफलको लागि हाम्रो Discord समुदाय मा सामेल हुनुहोस्।

🔗 सम्बन्धित स्रोतहरू

MCP for Beginners: आवश्यक पृष्ठभूमि पढाइ
Sample Walkthrough: उच्च-स्तरीय प्राविधिक अवलोकन
Azure AI Foundry: उदाहरणहरूमा प्रयोग गरिएको क्लाउड प्लेटफर्म
FastMCP Framework: Python MCP कार्यान्वयन फ्रेमवर्क

सिक्न सुरु गर्न तयार हुनुहुन्छ? Module 00: Introduction बाट सुरु गर्नुहोस् वा पूर्ण वाकथ्रु अवलोकन अन्वेषण गर्नुहोस्।

आवश्यकताहरू

Docker Desktop स्थापना गरिएको
Git स्थापना गरिएको
Azure CLI: Azure CLI स्थापना गर्नुहोस् र प्रमाणित गर्नुहोस्
OpenAI text-embedding-3-small मोडेल र वैकल्पिक रूपमा gpt-4o-mini मोडेलको पहुँच।

सुरु गर्दै

टर्मिनल विन्डो खोल्नुहोस् र निम्न कमाण्डहरू चलाउनुहोस्:

Azure CLI सँग प्रमाणित गर्नुहोस्
```
az login
```

रिपोजिटरी क्लोन गर्नुहोस्

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

परियोजना निर्देशिकामा जानुहोस्
```
cd Zava-MCP-Server-and-PostgreSQL-Sample
```

Azure स्रोतहरू तैनाथ गर्नुहोस्

MCP सर्भरको लागि आवश्यक Azure स्रोतहरूको तैनाथी स्वचालित गर्न निम्न स्क्रिप्टहरू चलाउनुहोस्।

तैनाथी स्क्रिप्टहरूले text-embedding-3-small मोडेल स्वचालित रूपमा तैनाथ गर्नेछन्। तैनाथीको क्रममा, तपाईंले gpt-4o-mini मोडेल पनि समावेश गर्न विकल्प पाउनुहुनेछ। ध्यान दिनुहोस् कि gpt-4o-mini यो परियोजनाको लागि आवश्यक छैन र केवल सम्भावित भविष्य सुधारहरूको लागि समावेश गरिएको छ।

आफ्नो प्लेटफर्मको लागि स्क्रिप्ट चयन गर्नुहोस्:

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

MCP सर्भर चलाउँदै

सबै स्ट्याक (PostgreSQL + MCP सर्भर) चलाउने सबैभन्दा सजिलो तरिका Docker Compose प्रयोग गर्नु हो:

स्ट्याक सुरु गर्नुहोस्

# 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

प्रयोग

निम्नले मान्छ कि तपाईंले VS Code मा निर्मित MCP सर्भर समर्थन प्रयोग गर्नुहुनेछ।

परियोजना VS Code मा खोल्नुहोस्। टर्मिनलबाट चलाउनुहोस्:
```
code .
```
.vscode/mcp.json मा रहेको कन्फिगरेसनहरू प्रयोग गरेर एक वा बढी MCP सर्भरहरू सुरु गर्नुहोस्। फाइलमा चार विभिन्न सर्भर कन्फिगरेसनहरू छन्, प्रत्येकले फरक स्टोर म्यानेजर भूमिकालाई प्रतिनिधित्व गर्दछ:
- प्रत्येक कन्फिगरेसनले अद्वितीय RLS (Row Level Security) प्रयोगकर्ता ID प्रयोग गर्दछ।
- यी प्रयोगकर्ता IDहरूले डेटाबेस पहुँच गर्ने विभिन्न स्टोर म्यानेजर पहिचानहरू अनुकरण गर्छन्।
- RLS प्रणालीले म्यानेजरको असाइन गरिएको स्टोरको आधारमा डेटा पहुँच प्रतिबन्धित गर्छ।
- यसले वास्तविक-विश्व परिदृश्यहरू अनुकरण गर्छ जहाँ स्टोर म्यानेजरहरूले फरक Entra ID खाताहरू प्रयोग गरेर साइन इन गर्छन्।
```
{
    "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": []
}
```

VS Code AI च्याट खोल्नुहोस्

VS Code मा AI च्याट मोड खोल्नुहोस्।
#zava टाइप गर्नुहोस् र तपाईंले सुरु गरेको MCP सर्भरहरू मध्ये एक चयन गर्नुहोस्।
बिक्री डेटा बारे प्रश्न सोध्नुहोस् - तलका नमूना क्वेरीहरू हेर्नुहोस्।

नमूना क्वेरीहरू

बिक्री राजस्वद्वारा शीर्ष 20 उत्पादनहरू देखाउनुहोस्।
स्टोरद्वारा बिक्री देखाउनुहोस्।
अन्तिम त्रैमासिकको बिक्री श्रेणीद्वारा के थियो?
"रङका लागि कन्टेनरहरू" जस्तै हामीले बेच्ने उत्पादनहरू के हुन्?

विशेषताहरू

बहु-तालिका स्कीमा पहुँच: एकल अनुरोधमा धेरै डेटाबेस तालिकाहरूको स्कीमा पुनःप्राप्त गर्नुहोस्।
सुरक्षित क्वेरी कार्यान्वयन: Row Level Security (RLS) समर्थनसहित PostgreSQL क्वेरीहरू कार्यान्वयन गर्नुहोस्।
वास्तविक-समय डेटा: वर्तमान बिक्री, सूची, र ग्राहक डेटा पहुँच गर्नुहोस्।
मिति/समय उपयोगिताहरू: समय-संवेदनशील विश्लेषणको लागि वर्तमान UTC टाइमस्ट्याम्पहरू प्राप्त गर्नुहोस्।
लचिलो तैनाथी: HTTP सर्भर मोड समर्थन गर्दछ।

समर्थित तालिकाहरू

सर्भरले निम्न खुद्रा डेटाबेस तालिकाहरूमा पहुँच प्रदान गर्दछ:

retail.customers - ग्राहक जानकारी र प्रोफाइलहरू
retail.stores - स्टोर स्थानहरू र विवरणहरू
retail.categories - उत्पादन श्रेणीहरू र पदानुक्रमहरू
retail.product_types - उत्पादन प्रकार वर्गीकरणहरू
retail.products - उत्पादन सूची र विशिष्टताहरू
retail.orders - ग्राहक अर्डरहरू र लेनदेनहरू
retail.order_items - अर्डरभित्रका व्यक्तिगत वस्तुहरू
retail.inventory - वर्तमान सूची स्तरहरू र स्टक डेटा

उपलब्ध उपकरणहरू

`get_multiple_table_schemas`

एकल अनुरोधमा धेरै तालिकाहरूको डेटाबेस स्कीमा पुनःप्राप्त गर्नुहोस्।

प्यारामिटरहरू:

table_names (list[str]): माथि समर्थित तालिकाहरूबाट मान्य तालिका नामहरूको सूची।

फिर्ता गर्छ: अनुरोध गरिएको तालिकाहरूको लागि स्कीमा स्ट्रिङहरू जोडिएको।

`execute_sales_query`

Row Level Security समर्थनसहित बिक्री डेटाबेसमा PostgreSQL क्वेरीहरू कार्यान्वयन गर्नुहोस्।

प्यारामिटरहरू:

postgresql_query (str): राम्रोसँग बनाइएको PostgreSQL क्वेरी।

फिर्ता गर्छ: स्ट्रिङको रूपमा क्वेरी परिणामहरू (पढ्न सजिलो बनाउन 20 पङ्क्तिहरूमा सीमित)।

सर्वोत्तम अभ्यासहरू:

सधैं पहिले तालिका स्कीमा पुनःप्राप्त गर्नुहोस्।
स्कीमाबाट ठ्याक्कै स्तम्भ नामहरू प्रयोग गर्नुहोस्।
व्यापक विश्लेषणको लागि सम्बन्धित तालिकाहरू जोड्नुहोस्।
उपयुक्त हुँदा परिणामहरू समग्र बनाउनुहोस्।
पढ्न सजिलो बनाउन आउटपुट सीमित गर्नुहोस्।

`get_current_utc_date`

ISO ढाँचामा वर्तमान UTC मिति र समय प्राप्त गर्नुहोस्।

फिर्ता गर्छ: वर्तमान UTC मिति/समय ISO ढाँचामा (YYYY-MM-DDTHH:MM:SS.fffffZ)।

`semantic_search_products`

प्रयोगकर्ता क्वेरीहरूमा आधारित उत्पादनहरूको लागि सेम्यान्टिक खोज गर्नुहोस्।

फिर्ता गर्छ: खोज मापदण्डसँग मेल खाने उत्पादनहरूको सूची।

प्यारामिटरहरू:

query (str): खोज क्वेरी स्ट्रिङ।

फिर्ता गर्छ: खोज मापदण्डसँग मेल खाने उत्पादनहरूको सूची।

सुरक्षा विशेषताहरू

Row Level Security (RLS)

सर्भरले प्रयोगकर्ताहरूले केवल उनीहरूलाई अधिकृत गरिएको डेटा पहुँच सुनिश्चित गर्न Row Level Security कार्यान्वयन गर्दछ:

HTTP मोड: अनुरोध गर्ने प्रयोगकर्तालाई पहिचान गर्न x-rls-user-id हेडर प्रयोग गर्दछ।
डिफल्ट फलब्याक: प्रयोगकर्ता ID प्रदान नगरिएको अवस्थामा प्लेसहोल्डर UUID प्रयोग गर्दछ।

स्टोर-विशिष्ट RLS प्रयोगकर्ता IDहरू

प्रत्येक Zava Retail स्टोर स्थानको अद्वितीय RLS प्रयोगकर्ता ID छ जसले प्रयोगकर्ताले कुन डेटा पहुँच गर्न सक्छ निर्धारण गर्दछ:

स्टोर स्थान	RLS प्रयोगकर्ता ID	विवरण
ग्लोबल पहुँच	`00000000-0000-0000-0000-000000000000`	डिफल्ट फलब्याक - सबै स्टोर पहुँच
Seattle	`f47ac10b-58cc-4372-a567-0e02b2c3d479`	Zava Retail Seattle स्टोर डेटा
Bellevue	`6ba7b810-9dad-11d1-80b4-00c04fd430c8`	Zava Retail Bellevue स्टोर डेटा
Tacoma	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`	Zava Retail Tacoma स्टोर डेटा
Spokane	`d8e9f0a1-b2c3-4567-8901-234567890abc`	Zava Retail Spokane स्टोर डेटा
Everett	`3b9ac9fa-cd5e-4b92-a7f2-b8c1d0e9f2a3`	Zava Retail Everett स्टोर डेटा
Redmond	`e7f8a9b0-c1d2-3e4f-5678-90abcdef1234`	Zava Retail Redmond स्टोर डेटा
Kirkland	`9c8b7a65-4321-fed0-9876-543210fedcba`	Zava Retail Kirkland स्टोर डेटा
Online	`2f4e6d8c-1a3b-5c7e-9f0a-b2d4f6e8c0a2`	Zava Retail Online स्टोर डेटा

RLS कार्यान्वयन

जब प्रयोगकर्ता विशिष्ट स्टोरको RLS प्रयोगकर्ता ID सँग जडान गर्छ, उनीहरूले मात्र हेर्न सक्नेछन्:

उक्त स्टोरसँग सम्बन्धित ग्राहकहरू।
उक्त स्टोर स्थानमा राखिएका अर्डरहरू।
उक्त स्टोरको लागि सूची डेटा।
स्टोर-विशिष्ट बिक्री र प्रदर्शन मेट्रिक्स।

यसले विभिन्न स्टोर स्थानहरू बीच डेटा अलगाव सुनिश्चित गर्दछ जबकि एकीकृत डेटाबेस स्कीमा कायम राख्छ।

वास्तुकला

अनुप्रयोग सन्दर्भ

सर्भरले व्यवस्थापित अनुप्रयोग सन्दर्भ प्रयोग गर्दछ:

डेटाबेस कनेक्शन पूल: HTTP मोडको लागि कुशल कनेक्शन व्यवस्थापन।
जीवनचक्र व्यवस्थापन: बन्द गर्दा उचित स्रोत सफाइ।
प्रकार सुरक्षा: AppContext dataclass सँग बलियो प्रकारको सन्दर्भ।

अनुरोध सन्दर्भ

हेडर एक्स्ट्र्याक्सन: प्रयोगकर्ता पहिचानको लागि सुरक्षित हेडर पार्सिङ।
RLS एकीकरण: अनुरोध सन्दर्भबाट स्वचालित प्रयोगकर्ता ID समाधान।
त्रुटि ह्यान्डलिङ: प्रयोगकर्ता-अनुकूल सन्देशहरू सहित व्यापक त्रुटि ह्यान्डलिङ।

डेटाबेस एकीकरण

सर्भरले PostgreSQLSchemaProvider वर्ग मार्फत PostgreSQL डेटाबेससँग एकीकरण गर्दछ:

कनेक्शन पूलिङ: स्केलेबिलिटीको लागि असिन्क कनेक्शन पूलहरू प्रयोग गर्दछ।
स्कीमा मेटाडाटा: विस्तृत तालिका स्कीमा जानकारी प्रदान गर्दछ।
क्वेरी कार्यान्वयन: RLS समर्थनसहित सुरक्षित क्वेरी कार्यान्वयन।
स्रोत व्यवस्थापन: डेटाबेस स्रोतहरूको स्वचालित सफाइ।

त्रुटि ह्यान्डलिङ

सर्भरले बलियो त्रुटि ह्यान्डलिङ कार्यान्वयन गर्दछ:

तालिका मान्यता: केवल मान्य तालिका नामहरू पहुँच सुनिश्चित गर्दछ।
क्वेरी मान्यता: कार्यान्वयन अघि PostgreSQL क्वेरीहरू मान्य गर्दछ।
स्रोत व्यवस्थापन: त्रुटिहरूको समयमा पनि उचित सफाइ।
प्रयोगकर्ता-अनुकूल सन्देशहरू: समस्या समाधानको लागि स्पष्ट त्रुटि सन्देशहरू।

सुरक्षा विचारहरू

Row Level Security: सबै क्वेरीहरूले प्रयोगकर्ता पहिचानको आधारमा RLS नीतिहरू सम्मान गर्छन्।
स्टोर डेटा अलगाव: प्रत्येक स्टोरको RLS प्रयोगकर्ता IDले केवल उक्त स्टोरको डेटा पहुँच सुनिश्चित गर्दछ।
इनपुट मान्यता: कार्यान्वयन अघि तालिका नामहरू र क्वेरीहरू मान्य गरिन्छ।
स्रोत सीमा: अत्यधिक स्रोत प्रयोग रोक्न क्वेरी परिणामहरू सीमित छन्।
कनेक्शन सुरक्षा: सुरक्षित डेटाबेस कनेक्शन अभ्यासहरू प्रयोग गर्दछ।
प्रयोगकर्ता पहिचान प्रमाणीकरण: सधैं सुनिश्चित गर्नुहोस् कि सही RLS प्रयोगकर्ता ID इच्छित स्टोरको लागि प्रयोग गरिएको छ।

महत्त्वपूर्ण सुरक्षा नोटहरू

कहिल्यै उत्पादन RLS प्रयोगकर्ता IDहरू विकास वातावरणमा प्रयोग नगर्नुहोस्।
सधैं सुनिश्चित गर्नुहोस् कि RLS प्रयोगकर्ता ID इच्छित स्टोरसँग मेल खान्छ।
डिफल्ट UUID (00000000-0000-0000-0000-000000000000) सीमित पहुँच प्रदान गर्दछ।
प्रत्येक स्टोर म्यानेजरले केवल आफ्नो स्टोरको RLS प्रयोगकर्ता ID पहुँच गर्नुपर्छ।

विकास

परियोजना संरचना

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

प्रमुख घटकहरू

FastMCP सर्भर: असिन्क समर्थनसहित आधुनिक MCP सर्भर कार्यान्वयन।
PostgreSQL प्रदायक: RLS समर्थनसहित डेटाबेस अमूर्त तह।
सन्दर्भ व्यवस्थापन: प्रकार-सुरक्षित अनुप्रयोग र अनुरोध सन्दर्भ ह्यान्डलिङ।
उपकरण दर्ता: Pydantic मान्यतासहित घोषणात्मक उपकरण दर्ता।

योगदान

सर्भरमा योगदान गर्दा:

सुनिश्चित गर्नुहोस् कि सबै डेटाबेस क्वेरीहरूले Row Level Security सम्मान गर्छन्।
नयाँ उपकरणहरूको लागि उचित त्रुटि ह्यान्डलिङ थप्नुहोस्।
कुनै पनि नयाँ सुविधाहरू वा परिवर्तनहरूको साथ यो README अपडेट गर्नुहोस्।
HTTP सर्भर मोड परीक्षण गर्नुहोस्।
इनपुट प्यारामिटरहरू मान्य गर्नुहोस् र स्पष्ट त्रुटि सन्देशहरू प्रदान गर्नुहोस्।

लाइसेन्स

यो MCP सर्भरले Zava Retail बिक्री डेटा सुरक्षित, कुशल पहुँच सक्षम गर्दछ AI-संचालित विश्लेषण र अन्तर्दृष्टिको लागि।

अस्वीकरण:
यो दस्तावेज़ AI अनुवाद सेवा Co-op Translator प्रयोग गरेर अनुवाद गरिएको हो। हामी यथार्थताको लागि प्रयास गर्छौं, तर कृपया ध्यान दिनुहोस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छ। यसको मूल भाषा मा रहेको मूल दस्तावेज़लाई आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीको लागि, व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न हुने कुनै पनि गलतफहमी वा गलत व्याख्याको लागि हामी जिम्मेवार हुनेछैनौं।