Apache Doris

आधिकारिक

Apache Doris के लिए MCP सर्वर, जो MPP-आधारित रीयल-टाइम डेटा वेयरहाउस है।

GitHub

320

Apache Doris MCP के साथ आप क्या कर सकते हैं?

Apache Doris के विरुद्ध SQL क्वेरी चलाएँ — AI से ad-hoc SQL निष्पादित करने और doris_query.execute_query का उपयोग करके परिणाम लौटाने के लिए कहें।
डेटाबेस स्कीमा और मेटाडेटा का अन्वेषण करें — स्कीमा निष्कर्षण टूल के माध्यम से आंतरिक और बाहरी कैटलॉग में तालिकाओं, कॉलम और डेटा प्रकारों की खोज करें।
प्राकृतिक भाषा को SQL में बदलें (NL2SQL) — बताएं कि आपको कौन सा डेटा चाहिए और AI को संबंधित Doris SQL उत्पन्न करने और चलाने दें।
क्वेरी प्रदर्शन का विश्लेषण करें — क्वेरी निष्पादन को समझने और अनुकूलित करने के लिए SQL explain योजनाएँ और प्रोफाइलिंग जानकारी का अनुरोध करें।
क्लस्टर स्वास्थ्य और मेट्रिक्स की निगरानी करें — मॉनिटरिंग टूल मॉड्यूल के माध्यम से Doris FE और BE इंस्टेंस से मेमोरी, कनेक्शन और नोड-स्तरीय मेट्रिक्स प्राप्त करें।

दस्तावेज़

Doris MCP सर्वर

English | 简体中文

Doris MCP (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) सर्वर Python और FastAPI से निर्मित एक बैकएंड सेवा है। यह MCP को कार्यान्वित करता है, जिससे क्लाइंट परिभाषित "टूल्स" के माध्यम से इसके साथ इंटरैक्ट कर सकते हैं। यह मुख्य रूप से Apache Doris डेटाबेस से जुड़ने के लिए डिज़ाइन किया गया है, जो संभावित रूप से प्राकृतिक भाषा प्रश्नों को SQL (NL2SQL) में बदलने, प्रश्नों को निष्पादित करने और मेटाडेटा प्रबंधन और विश्लेषण करने जैसे कार्यों के लिए बड़े भाषा मॉडल (LLM) का लाभ उठाता है।

रिलीज़ स्थिति

वर्तमान पैकेज मेटाडेटा और नवीनतम Git टैग 0.6.1 है। master शाखा में उस टैग के बाद किए गए परिवर्तन भी शामिल हैं; वे परिवर्तन Unreleased के अंतर्गत दर्ज हैं जब तक कि अगला संस्करण चुनकर प्रकाशित नहीं किया जाता।

master पर MCP 2026-07-28 प्रोटोकॉल संगतता स्ट्रीमेबल HTTP और stdio के लिए सामान्यतः उपलब्ध (GA) है। समर्थित प्रोटोकॉल अनुबंध ने चेतावनियों को त्रुटियों के रूप में मानते हुए पूर्ण परीक्षण सूट, आधिकारिक स्टेटलेस अनुरूपता सूट, स्वच्छ व्हील स्थापना और दोनों ट्रांसपोर्ट पर वास्तविक Apache Doris परीक्षण पास कर लिया है।

यह GA कथन समर्थित ट्रांसपोर्ट पर प्रोटोकॉल संगतता तक सीमित है। परियोजना पैकेज मेटाडेटा बीटा बना हुआ है, और यह समर्थित परिनियोजन आकृतियों का विस्तार नहीं करता है या प्रलेखित परिचालन बाधाओं को नहीं हटाता है। नियंत्रित वातावरण के बाहर इसे परिनियोजित करने से पहले चेंजलॉग, प्रोटोकॉल समर्थन मैट्रिक्स, और परिनियोजन बाधाओं की समीक्षा करें।

v0.6.0 की मुख्य विशेषताएं

🔐 एंटरप्राइज़ प्रमाणीकरण प्रणाली: क्रांतिकारी टोकन-बाउंड डेटाबेस कॉन्फ़िगरेशन जिसमें व्यापक टोकन, JWT और OAuth प्रमाणीकरण समर्थन है, जो विस्तृत नियंत्रण स्विच और एंटरप्राइज़-ग्रेड सुरक्षा डिफ़ॉल्ट के साथ सुरक्षित बहु-किरायेदार पहुँच को सक्षम करता है
⚡ तत्काल डेटाबेस सत्यापन: कनेक्शन के समय रीयल-टाइम डेटाबेस कॉन्फ़िगरेशन सत्यापन, क्वेरी-टाइम अवरोधन को कम करता है और अमान्य कॉन्फ़िगरेशन के लिए पहले प्रतिक्रिया प्रदान करता है
🔄 हॉट रीलोड कॉन्फ़िगरेशन प्रबंधन: रनटाइम कॉन्फ़िगरेशन अपडेट tokens.json की बुद्धिमान हॉट रीलोडिंग, स्वचालित टोकन पुनर्सत्यापन और रोलबैक तंत्र के साथ व्यापक त्रुटि प्रबंधन के साथ
🏗️ उन्नत कनेक्शन आर्किटेक्चर: सत्र कैशिंग और कनेक्शन पूल अनुकूलन बुद्धिमान पूल पुनर्निर्माण और स्वचालित संसाधन प्रबंधन के साथ
🌐 बहु-कार्यकर्ता मापनीयता: बहु-कार्यकर्ता समर्थन के साथ स्टेटलेस HTTP अनुरोध प्रबंधन; प्रमाणीकरण-विशिष्ट कार्यकर्ता सीमाएँ अभी भी लागू होती हैं
🔒 उन्नत सुरक्षा ढाँचा: व्यापक अभिगम नियंत्रण और SQL सुरक्षा सत्यापन तत्काल सत्यापन, भूमिका-आधारित अनुमतियाँ और उन्नत इंजेक्शन पहचान पैटर्न के साथ
🛠️ एकीकृत कॉन्फ़िगरेशन प्रणाली: सुव्यवस्थित कॉन्फ़िगरेशन प्रबंधन उचित कमांड-लाइन पूर्वता, Docker संगतता सुधार और क्रॉस-प्लेटफ़ॉर्म परिनियोजन समर्थन के साथ
📊 टोकन प्रबंधन डैशबोर्ड: पूर्ण टोकन जीवनचक्र प्रबंधन निर्माण, निरसन, सांख्यिकी और एंटरप्राइज़ टोकन शासन के लिए व्यापक ऑडिट ट्रेल्स के साथ
🌐 वेब-आधारित प्रबंधन इंटरफ़ेस: सुरक्षित केवल-लोकलहोस्ट टोकन प्रशासन सहज डैशबोर्ड, डेटाबेस बाइंडिंग कॉन्फ़िगरेशन, रीयल-टाइम संचालन और एंटरप्राइज़-ग्रेड अभिगम नियंत्रण के साथ

रिलीज़ नोट: v0.6.0 ने ऊपर संक्षेपित प्रमाणीकरण, टोकन प्रबंधन, कनेक्शन और बहु-कार्यकर्ता सुविधाएँ प्रस्तुत कीं। ये सुविधाएँ वर्तमान कोडबेस के लिए प्रलेखित बीटा स्थिति या परिनियोजन सीमाओं को नहीं हटाती हैं।

v0.5.1 से और क्या शामिल है

🔥 महत्वपूर्ण at_eof कनेक्शन सुधार: बुद्धिमान स्वास्थ्य निगरानी और स्व-उपचार पुनर्प्राप्ति के साथ कनेक्शन पूल त्रुटियों का पूर्ण उन्मूलन
🔧 एंटरप्राइज़ लॉगिंग प्रणाली: स्वचालित सफाई और मिलीसेकंड सटीकता टाइमस्टैम्प के साथ स्तर-आधारित फ़ाइल पृथक्करण
📊 उन्नत डेटा विश्लेषण सूट: गुणवत्ता विश्लेषण, वंश ट्रैकिंग और प्रदर्शन निगरानी सहित 7 एंटरप्राइज़-ग्रेड डेटा शासन उपकरण
🏃‍♂️ उच्च-प्रदर्शन ADBC एकीकरण: बड़े डेटासेट के लिए 3-10x प्रदर्शन सुधार के साथ Apache Arrow Flight SQL समर्थन
⚙️ उन्नत कॉन्फ़िगरेशन प्रबंधन: बुद्धिमान पैरामीटर सत्यापन के साथ पूर्ण ADBC कॉन्फ़िगरेशन प्रणाली

मुख्य विशेषताएं

MCP प्रोटोकॉल कार्यान्वयन: मानक MCP इंटरफ़ेस प्रदान करता है, टूल कॉल, संसाधन प्रबंधन और प्रॉम्प्ट इंटरैक्शन का समर्थन करता है।
स्ट्रीमेबल HTTP संचार: इष्टतम प्रदर्शन और विश्वसनीयता के लिए अनुरोध/प्रतिक्रिया और स्ट्रीमिंग संचार दोनों का समर्थन करने वाला एकीकृत HTTP एंडपॉइंट।
Stdio संचार: Cursor जैसे MCP क्लाइंट के साथ सीधे एकीकरण के लिए मानक इनपुट/आउटपुट मोड।
एंटरप्राइज़-ग्रेड आर्किटेक्चर: व्यापक कार्यक्षमता के साथ मॉड्यूलर डिज़ाइन:
- टूल्स मैनेजर: एकीकृत इंटरफ़ेस के साथ केंद्रीकृत टूल पंजीकरण और रूटिंग (doris_mcp_server/tools/tools_manager.py)
- उन्नत निगरानी टूल्स मॉड्यूल: मॉड्यूलर, एक्स्टेंसिबल डिज़ाइन के साथ उन्नत मेमोरी ट्रैकिंग, मेट्रिक्स संग्रह और लचीली BE नोड खोज
- क्वेरी सूचना टूल्स: कॉन्फ़िगरेबल सामग्री ट्रंकेशन, LLM अटैचमेंट के लिए फ़ाइल निर्यात और उन्नत क्वेरी विश्लेषण के साथ उन्नत SQL व्याख्या और प्रोफाइलिंग
- संसाधन प्रबंधक: संसाधन प्रबंधन और मेटाडेटा एक्सपोज़र (doris_mcp_server/tools/resources_manager.py)
- प्रॉम्प्ट मैनेजर: डेटा विश्लेषण के लिए बुद्धिमान प्रॉम्प्ट टेम्पलेट (doris_mcp_server/tools/prompts_manager.py)
उन्नत डेटाबेस सुविधाएँ:
- क्वेरी निष्पादन: उन्नत कैशिंग और अनुकूलन, उन्नत कनेक्शन स्थिरता और स्वचालित पुनर्प्रयास तंत्र के साथ उच्च-प्रदर्शन SQL निष्पादन (doris_mcp_server/utils/query_executor.py)
- सुरक्षा प्रबंधन: कॉन्फ़िगरेबल अवरुद्ध कीवर्ड, SQL इंजेक्शन सुरक्षा, डेटा मास्किंग और एकीकृत सुरक्षा कॉन्फ़िगरेशन प्रबंधन के साथ व्यापक SQL सुरक्षा सत्यापन (doris_mcp_server/utils/security.py)
- मेटाडेटा निष्कर्षण: कैटलॉग फ़ेडरेशन समर्थन के साथ व्यापक डेटाबेस मेटाडेटा (doris_mcp_server/utils/schema_extractor.py)
- प्रदर्शन विश्लेषण: उन्नत स्तंभ विश्लेषण, प्रदर्शन निगरानी और डेटा विश्लेषण उपकरण (doris_mcp_server/utils/analysis_tools.py)
कैटलॉग फ़ेडरेशन समर्थन: बहु-कैटलॉग वातावरण (आंतरिक Doris तालिकाएँ और Hive, MySQL, आदि जैसे बाहरी डेटा स्रोत) के लिए पूर्ण समर्थन
एंटरप्राइज़ सुरक्षा: पर्यावरण चर कॉन्फ़िगरेशन समर्थन के साथ प्रमाणीकरण, प्राधिकरण, SQL इंजेक्शन सुरक्षा और डेटा मास्किंग क्षमताओं के साथ व्यापक सुरक्षा ढाँचा
वेब-आधारित टोकन प्रबंधन: डेटाबेस बाइंडिंग, रीयल-टाइम सांख्यिकी और एंटरप्राइज़-ग्रेड अभिगम नियंत्रण के साथ पूर्ण टोकन जीवनचक्र प्रबंधन के लिए सुरक्षित केवल-लोकलहोस्ट इंटरफ़ेस (doris_mcp_server/auth/token_handlers.py)
एकीकृत कॉन्फ़िगरेशन ढाँचा: information_schema पर स्वचालित फ़ॉलबैक के साथ व्यापक सत्यापन, मानकीकृत पैरामीटर नामकरण और स्मार्ट डिफ़ॉल्ट डेटाबेस हैंडलिंग के साथ config.py के माध्यम से केंद्रीकृत कॉन्फ़िगरेशन प्रबंधन

सिस्टम आवश्यकताएँ

Python: 3.12+
डेटाबेस: Apache Doris कनेक्शन विवरण (होस्ट, पोर्ट, उपयोगकर्ता, पासवर्ड, डेटाबेस)

🚀 त्वरित शुरुआत

PyPI से स्थापना

# Install the latest version
pip install doris-mcp-server

# Install specific version
pip install doris-mcp-server==0.6.1

💡 पैकेज्ड कमांड: doris-mcp-server MCP सर्वर शुरू करता है। doris-mcp-client स्ट्रीमेबल HTTP या stdio पर सर्वर से कनेक्ट करने के लिए एक अलग क्लाइंट है; दोनों कमांड विनिमेय नहीं हैं।

स्ट्रीमेबल HTTP मोड प्रारंभ करें (वेब सेवा)

इष्टतम प्रदर्शन और विश्वसनीयता प्रदान करने वाला प्राथमिक संचार मोड:

# Full configuration with database connection
doris-mcp-server \
    --transport http \
    --host 127.0.0.1 \
    --port 3000 \
    --db-host 127.0.0.1 \
    --db-port 9030 \
    --db-user root \
    --db-password your_password

Stdio मोड प्रारंभ करें (Cursor और अन्य MCP क्लाइंट के लिए)

MCP क्लाइंट के साथ सीधे एकीकरण के लिए मानक इनपुट/आउटपुट मोड:

# For direct integration with MCP clients like Cursor
doris-mcp-server --transport stdio

🌐 टोकन प्रबंधन इंटरफ़ेस (v0.6.0 में नया)

एंटरप्राइज़-ग्रेड टोकन प्रशासन के लिए वेब-आधारित टोकन प्रबंधन डैशबोर्ड तक पहुँचें:

सुरक्षित पहुँच आवश्यकताएँ

केवल लोकलहोस्ट पहुँच: अधिकतम सुरक्षा के लिए इंटरफ़ेस 127.0.0.1 और ::1 तक सीमित
व्यवस्थापक प्रमाणीकरण: पहुँच के लिए TOKEN_MANAGEMENT_ADMIN_TOKEN की आवश्यकता है

कॉन्फ़िगरेशन पूर्वापेक्षाएँ:

# Generate separate high-entropy credentials; do not commit them.
export TOKEN_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export TOKEN_MANAGEMENT_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

इंटरफ़ेस पहुँच

प्रबंधन अनुरोध केवल HTTP हेडर में व्यवस्थापक टोकन स्वीकार करते हैं। क्वेरी-स्ट्रिंग टोकन अस्वीकार कर दिए जाते हैं और उन्हें URL, ब्राउज़र इतिहास या एक्सेस लॉग में नहीं रखा जाना चाहिए।

curl -H "Authorization: Bearer $TOKEN_MANAGEMENT_ADMIN_TOKEN" \
  http://127.0.0.1:3000/token/stats

वैकल्पिक /token/management पृष्ठ को एक क्लाइंट या स्थानीय प्रॉक्सी के माध्यम से खोला जाना चाहिए जो समान हेडर की आपूर्ति करता है। इसके API अनुरोध इन-पेज पासवर्ड फ़ील्ड का उपयोग करते हैं और URL में टोकन को बनाए नहीं रखते या प्रसारित नहीं करते हैं।

उपलब्ध संचालन

📊 टोकन सांख्यिकी: सक्रिय, समाप्त और कुल टोकन का रीयल-टाइम अवलोकन
➕ टोकन बनाएँ:
- मूल जानकारी (ID, विवरण, समाप्ति)
- डेटाबेस बाइंडिंग (होस्ट, पोर्ट, उपयोगकर्ता, पासवर्ड, डेटाबेस)
- कस्टम टोकन मान या ऑटो-जनरेटेड सुरक्षित टोकन
📋 टोकन प्रबंधन:
- डेटाबेस बाइंडिंग स्थिति के साथ सभी टोकन सूचीबद्ध करें
- एक-क्लिक टोकन निरसन
- स्वचालित समाप्त टोकन सफाई
🔒 एंटरप्राइज़ सुरक्षा:
- सभी संचालनों के लिए व्यवस्थापक प्रमाणीकरण आवश्यक है
- रीयल-टाइम IP सत्यापन
- पूर्ण ऑडिट लॉगिंग
- tokens.json पर केवल-डाइजेस्ट स्थायित्व; टोकन बनाए जाने पर प्लेनटेक्स्ट एक बार लौटाया जाता है
- प्रक्रिया-साझा लॉक, परमाणु रीड-मॉडिफाई-राइट अपडेट और केवल-डाइजेस्ट निरसन रिकॉर्ड के माध्यम से बहु-कार्यकर्ता स्थिरता

🔐 सुरक्षा नोट: इंटरफ़ेस केवल लोकलहोस्ट प्रशासन के लिए डिज़ाइन किया गया है। इसे दूरस्थ रूप से एक्सेस नहीं किया जा सकता, जिससे टोकन प्रबंधन संचालन के लिए अधिकतम सुरक्षा सुनिश्चित होती है।

स्थापना सत्यापित करें

# Check installation
doris-mcp-server --version
doris-mcp-client --version
doris-mcp-server --help
doris-mcp-client --help

# Test HTTP mode (in another terminal)
curl --fail http://localhost:3000/live
curl --fail http://localhost:3000/ready

पर्यावरण चर (वैकल्पिक)

कमांड-लाइन तर्कों के बजाय, आप पर्यावरण चर का उपयोग कर सकते हैं:

# Basic Database Configuration
export DORIS_HOST="127.0.0.1"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

# Keep the isolated legacy HTTP migration adapter disabled unless an
# identified 2025-11-25 client still needs /mcp/legacy.
export ENABLE_LEGACY_HTTP_ADAPTER=false

# Bound each resources/list, tools/list, and prompts/list response.
export MCP_LIST_PAGE_SIZE=100
# Expose eight progressive-disclosure domains by default. Set flat to expose
# the same 47 children under exact collision-free formal names.
export MCP_TOOL_EXPOSURE_MODE=hierarchical
# Load only these installed custom tool providers. Empty disables extensions.
export MCP_TOOL_PROVIDERS="orders_api"
# A launch-local key is generated automatically. Configure one shared
# high-entropy value when independently launched replicas share traffic.
export MCP_STATE_HANDLE_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export MCP_STATE_HANDLE_TTL_SECONDS=300

# Token Management Interface (Security-Critical)
export TOKEN_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export TOKEN_MANAGEMENT_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS="127.0.0.1,::1"

# Then start with simplified command
doris-mcp-server --transport http --host 127.0.0.1 --port 3000

कमांड लाइन तर्क

doris-mcp-server कमांड निम्नलिखित तर्कों का समर्थन करता है:

तर्क	विवरण	डिफ़ॉल्ट	आवश्यक
`--transport`	ट्रांसपोर्ट मोड: `http` या `stdio`	`http`	नहीं
`--host`	HTTP सर्वर होस्ट (केवल HTTP मोड)	`localhost`	नहीं
`--port`	HTTP सर्वर पोर्ट (केवल HTTP मोड)	`3000`	नहीं
`--db-host`	Doris डेटाबेस होस्ट	`localhost`	नहीं
`--db-port`	Doris डेटाबेस पोर्ट	`9030`	नहीं
`--db-user`	Doris डेटाबेस उपयोगकर्ता नाम	`root`	नहीं
`--db-password`	Doris डेटाबेस पासवर्ड	-	हाँ (जब तक env में न हो)

विकास सेटअप

उन डेवलपर्स के लिए जो स्रोत से निर्माण करना चाहते हैं:

1. रिपॉजिटरी क्लोन करें

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. निर्भरताएँ स्थापित करें

dev निर्भरता समूह में CI द्वारा उपयोग किए जाने वाले परीक्षण और गुणवत्ता उपकरण शामिल हैं:

uv sync --frozen --group dev

pip-आधारित वर्कफ़्लो के लिए, requirements.txt में केवल उत्पादन निर्भरताएँ हैं। requirements-dev.txt में वह रनटाइम मेनिफेस्ट शामिल है और समान लीन परीक्षण और गुणवत्ता टूलचेन जोड़ता है:

pip install -r requirements-dev.txt

उत्पादन छवियों और रनटाइम वातावरणों को केवल पैकेज या requirements.txt स्थापित करना चाहिए; pytest, लिंटर, टाइप चेकर और बिल्ड बैकएंड रनटाइम निर्भरताएँ नहीं हैं।

3. पर्यावरण चर कॉन्फ़िगर करें

.env.example फ़ाइल को .env पर कॉपी करें और अपने वातावरण के अनुसार सेटिंग्स संशोधित करें:

cp .env.example .env

मुख्य पर्यावरण चर:

डेटाबेस कनेक्शन:
- DORIS_HOST: डेटाबेस होस्टनाम (डिफ़ॉल्ट: localhost)
- DORIS_HOSTS: एक Doris क्लस्टर के लिए क्रमबद्ध FE MySQL फ़ेलओवर होस्ट (अल्पविराम से अलग; जब दोनों सेट हों तो DORIS_HOST पहले जोड़ा जाता है)
- DORIS_PORT: डेटाबेस पोर्ट (डिफ़ॉल्ट: 9030)
- DORIS_USER: डेटाबेस उपयोगकर्ता नाम (डिफ़ॉल्ट: root)
- DORIS_PASSWORD: डेटाबेस पासवर्ड
- DORIS_DATABASE: डिफ़ॉल्ट डेटाबेस नाम (डिफ़ॉल्ट: information_schema)
- DORIS_MIN_CONNECTIONS: न्यूनतम कनेक्शन पूल आकार (डिफ़ॉल्ट: 5)
- DORIS_MAX_CONNECTIONS: अधिकतम कनेक्शन पूल आकार (डिफ़ॉल्ट: 20)
- DORIS_FE_HTTP_HOST: प्रोफ़ाइल, तालिका-आकार और निगरानी उपकरणों के लिए स्वतंत्र FE HTTP होस्ट (डिफ़ॉल्ट: खाली, DORIS_HOST पर वापस आता है)
- DORIS_FE_HTTP_HOSTS: उसी Doris क्लस्टर के लिए क्रमबद्ध FE HTTP फ़ेलओवर होस्ट (अल्पविराम से अलग)
- DORIS_FE_HTTP_PORT: स्वतंत्र FE HTTP API पोर्ट (डिफ़ॉल्ट: 8030)
- DORIS_BE_HOSTS: निगरानी के लिए स्पष्ट BE HTTP अनुमति सूची (अल्पविराम से अलग; खाली होने पर BE HTTP मेट्रिक्स अक्षम हो जाते हैं)
- DORIS_BE_WEBSERVER_PORT: निगरानी उपकरणों के लिए BE वेबसर्वर पोर्ट (डिफ़ॉल्ट: 8040)
- DORIS_HTTP_CONNECT_TIMEOUT_SECONDS: FE/BE HTTP कनेक्शन टाइमआउट (डिफ़ॉल्ट: 3)
- DORIS_HTTP_READ_TIMEOUT_SECONDS: FE/BE HTTP सॉकेट रीड टाइमआउट (डिफ़ॉल्ट: 15)
- DORIS_HTTP_TOTAL_TIMEOUT_SECONDS: FE/BE HTTP कुल टाइमआउट (डिफ़ॉल्ट: 30; अधिकतम सीमा: 60)
- DORIS_HTTP_MAX_RESPONSE_BYTES: FE/BE HTTP प्रतिक्रिया सीमा (डिफ़ॉल्ट: 4 MiB; अधिकतम सीमा: 16 MiB)
- FE_ARROW_FLIGHT_SQL_PORT: ADBC के लिए फ्रंटएंड Arrow Flight SQL पोर्ट (v0.5.0 में नया)
- BE_ARROW_FLIGHT_SQL_PORT: ADBC के लिए बैकएंड Arrow Flight SQL पोर्ट (v0.5.0 में नया)
MCP HTTP कॉन्फ़िगरेशन:
- ENABLE_LEGACY_HTTP_ADAPTER: /mcp/legacy पर पृथक 2025-11-25 माइग्रेशन एडाप्टर को उजागर करें (डिफ़ॉल्ट: false); आधुनिक ट्रैफ़िक हमेशा POST /mcp का उपयोग करता है
- MCP_LIST_PAGE_SIZE: प्रति प्रोटोकॉल पृष्ठ पर लौटाए गए अधिकतम संसाधन, उपकरण या संकेत (डिफ़ॉल्ट: 100; सीमा: 1-1000)
- MCP_TOOL_EXPOSURE_MODE: उपकरण एक्सपोज़र मोड। hierarchical प्रगतिशील चाइल्ड खोज के साथ आठ डोमेन उपकरण लौटाता है; flat सटीक टकराव-मुक्त औपचारिक नामों के तहत वही 47 चिल्ड्रन लौटाता है (डिफ़ॉल्ट: hierarchical)
- MCP_TOOL_PROVIDERS: स्थापित doris_mcp_server.tool_providers प्रवेश बिंदुओं की अल्पविराम से अलग अनुमति सूची (डिफ़ॉल्ट: खाली)
- MCP_STATE_HANDLE_SECRET: स्पष्ट क्रॉस-कॉल स्थिति हैंडल को प्रमाणित करने के लिए उपयोग की जाने वाली वैकल्पिक साझा उच्च-एन्ट्रापी कुंजी (कम से कम 32 बाइट्स)
- MCP_STATE_HANDLE_TTL_SECONDS: एक स्पष्ट स्थिति हैंडल का जीवनकाल (डिफ़ॉल्ट: 300 सेकंड; सीमा: 1-3600)
प्रमाणीकरण कॉन्फ़िगरेशन (v0.6.0 में बढ़ाया गया):
- ENABLE_TOKEN_AUTH: टोकन-आधारित प्रमाणीकरण सक्षम करें (डिफ़ॉल्ट: false)
- ENABLE_JWT_AUTH: JWT प्रमाणीकरण सक्षम करें (डिफ़ॉल्ट: false)
- ENABLE_OAUTH_AUTH: OAuth प्रमाणीकरण सक्षम करें (डिफ़ॉल्ट: false)
- OAUTH_ISSUER: सटीक बाह्य प्राधिकरण-सर्वर जारीकर्ता
- OAUTH_RESOURCE: कैनोनिकल MCP संरक्षित-संसाधन URI
- OAUTH_AUDIENCE: अपेक्षित एक्सेस-टोकन ऑडियंस (OAUTH_RESOURCE पर डिफ़ॉल्ट)
- OAUTH_INTROSPECTION_URL: विश्वसनीय RFC 7662 टोकन-निरीक्षण समापन बिंदु
- OAUTH_SCOPE / OAUTH_REQUIRED_SCOPE: अनुमत और अनिवार्य बाह्य OAuth स्कोप
- ENABLE_DORIS_OAUTH_AUTH: Doris-समर्थित OAuth प्रमाणीकरण सक्षम करें (डिफ़ॉल्ट: false)
- DORIS_OAUTH_BASE_URL: Doris-समर्थित OAuth खोज और टोकन समापन बिंदुओं द्वारा उपयोग किया जाने वाला सार्वजनिक आधार URL
- DORIS_OAUTH_CIMD_FETCH_TIMEOUT_SECONDS: क्लाइंट ID मेटाडेटा दस्तावेज़ प्राप्ति टाइमआउट (डिफ़ॉल्ट: 5)
- DORIS_OAUTH_CIMD_MAX_DOCUMENT_BYTES: अधिकतम क्लाइंट ID मेटाडेटा दस्तावेज़ आकार (डिफ़ॉल्ट: 5120)
- DORIS_OAUTH_CIMD_DEFAULT_CACHE_SECONDS: जब दस्तावेज़ एक प्रदान नहीं करता है तो कैश जीवनकाल (डिफ़ॉल्ट: 300)
- DORIS_OAUTH_CIMD_MAX_CACHE_SECONDS: अधिकतम स्वीकृत दस्तावेज़ कैश जीवनकाल (डिफ़ॉल्ट: 3600)
- DORIS_OAUTH_CIMD_MAX_CLIENTS: मेमोरी में रखे गए अधिकतम खोजे गए क्लाइंट ID मेटाडेटा क्लाइंट (डिफ़ॉल्ट: 1000)
- TOKEN_FILE_PATH: टोकन प्रबंधन के लिए tokens.json फ़ाइल का पथ (डिफ़ॉल्ट: tokens.json)
- TOKEN_HOT_RELOAD: टोकन कॉन्फ़िगरेशन की हॉट रीलोडिंग सक्षम करें (डिफ़ॉल्ट: true)
- TOKEN_HASH_ALGORITHM: नए बनाए गए स्थैतिक टोकन के लिए डाइजेस्ट एल्गोरिदम (sha256 या sha512; डिफ़ॉल्ट: sha256)
- TOKEN_<ID>: स्पष्ट स्थैतिक बियरर टोकन; प्रत्येक सक्रिय टोकन कम से कम 32 वर्णों का सुरक्षित रूप से उत्पन्न मान होना चाहिए
विरासत सुरक्षा कॉन्फ़िगरेशन:
- AUTH_TYPE: विरासत प्रमाणीकरण प्रकार (token/basic/oauth, पदावनत - अलग-अलग स्विच का उपयोग करें)
- ENABLE_SECURITY_CHECK: SQL सुरक्षा सत्यापन सक्षम/अक्षम करें (डिफ़ॉल्ट: true)
- BLOCKED_KEYWORDS: अवरुद्ध SQL कीवर्ड की अल्पविराम से अलग सूची
- ENABLE_MASKING: डेटा मास्किंग सक्षम करें (डिफ़ॉल्ट: true)
- MAX_RESULT_ROWS: लौटाई गई क्वेरी पंक्तियों के लिए परिनियोजन सीमा (डिफ़ॉल्ट: 10000; पूर्ण कठोर सीमा: 100000)
- DEFAULT_RESULT_ROWS: जब doris_query.execute_query.max_rows छोड़ा जाता है तो डिफ़ॉल्ट पंक्ति बजट (डिफ़ॉल्ट: 100; MAX_RESULT_ROWS से अधिक नहीं हो सकता)
ADBC कॉन्फ़िगरेशन (v0.5.0 में नया):
- ADBC_DEFAULT_MAX_ROWS: ADBC क्वेरी के लिए डिफ़ॉल्ट अधिकतम पंक्तियाँ (डिफ़ॉल्ट: 10000; MAX_RESULT_ROWS से अधिक नहीं हो सकती)
- ADBC_DEFAULT_TIMEOUT: सेकंड में डिफ़ॉल्ट ADBC क्वेरी टाइमआउट (डिफ़ॉल्ट: 60)
- ADBC_DEFAULT_RETURN_FORMAT: डिफ़ॉल्ट रिटर्न प्रारूप - arrow/pandas/dict (डिफ़ॉल्ट: arrow)
- ADBC_CONNECTION_TIMEOUT: सेकंड में ADBC कनेक्शन टाइमआउट (डिफ़ॉल्ट: 30)
- ADBC_ENABLED: ADBC उपकरण सक्षम/अक्षम करें (डिफ़ॉल्ट: true)
प्रदर्शन कॉन्फ़िगरेशन:
- ENABLE_QUERY_CACHE: क्वेरी कैशिंग सक्षम करें (डिफ़ॉल्ट: true)
- CACHE_TTL: सेकंड में कैश टाइम-टू-लिव (डिफ़ॉल्ट: 300)
- MAX_CONCURRENT_QUERIES: अधिकतम समवर्ती क्वेरीज़ (डिफ़ॉल्ट: 50)
- QUERY_TIMEOUT: क्वेरी निष्पादन समय के लिए परिनियोजन सीमा (डिफ़ॉल्ट और पूर्ण कठोर सीमा: 300 सेकंड)
- MAX_RESULT_BYTES: UTF-8 JSON पंक्ति डेटा के लिए परिनियोजन सीमा (डिफ़ॉल्ट: 1048576; अनुमत सीमा: 256-16777216 बाइट्स)
- MAX_RESPONSE_CONTENT_SIZE: LLM संगतता के लिए अधिकतम प्रतिक्रिया सामग्री आकार (डिफ़ॉल्ट: 4096, v0.4.0 में नया)
उन्नत लॉगिंग कॉन्फ़िगरेशन (v0.5.0 में बेहतर):
- LOG_LEVEL: लॉग स्तर (DEBUG/INFO/WARNING/ERROR, डिफ़ॉल्ट: INFO)
- LOG_FILE_PATH: लॉग फ़ाइल पथ (स्वचालित रूप से स्तर द्वारा व्यवस्थित)
- ENABLE_AUDIT: ऑडिट लॉगिंग सक्षम करें (डिफ़ॉल्ट: true)
- ENABLE_LOG_CLEANUP: स्वचालित लॉग सफाई सक्षम करें (डिफ़ॉल्ट: true, v0.5.0 में बढ़ाया गया)
- LOG_MAX_AGE_DAYS: दिनों में लॉग फ़ाइलों की अधिकतम आयु (डिफ़ॉल्ट: 30, v0.5.0 में बढ़ाया गया)
- LOG_CLEANUP_INTERVAL_HOURS: घंटों में लॉग सफाई जांच अंतराल (डिफ़ॉल्ट: 24, v0.5.0 में बढ़ाया गया)
- v0.5.0 में नई सुविधाएँ:
  - स्तर-आधारित फ़ाइल पृथक्करण: debug.log, info.log, warning.log, error.log, critical.log में स्वचालित पृथक्करण
  - टाइमस्टैम्प्ड प्रारूप: मिलीसेकंड सटीकता और उचित संरेखण के साथ उन्नत स्वरूपण
  - पृष्ठभूमि सफाई अनुसूचक: विन्यास योग्य अवधारण नीतियों के साथ स्वचालित सफाई
  - ऑडिट ट्रेल: अलग अवधारण प्रबंधन के साथ समर्पित audit.log
  - प्रदर्शन अनुकूलित: रोटेशन समर्थन के साथ न्यूनतम ओवरहेड एसिंक्रोनस लॉगिंग

उपलब्ध MCP उपकरण

MCP tools/list आठ स्थिर केवल-पढ़ने योग्य डोमेन उपकरणों को उजागर करता है। किसी डोमेन को एक खाली ऑब्जेक्ट के साथ कॉल करें ताकि उसके सटीक अधिकृत चाइल्ड उपकरणों, स्कीमा, संस्करण समर्थन, उपलब्धता, साक्ष्य और जोखिम एनोटेशन की प्रगतिशील खोज की जा सके। docs/tool-registry.md देखें। चेक-इन कैटलॉग रनटाइम पर उपयोग की जाने वाली समान मान्य डोमेन परिभाषाओं से उत्पन्न होता है।

tool:list OAuth सत्रों के लिए डोमेन-मेनिफेस्ट खोज को अधिकृत करता है; यह चाइल्ड निष्पादन को अधिकृत नहीं करता है। खोज अनुमति के बिना चिल्ड्रन को छोड़ दिया जाता है, जबकि अधिकृत लेकिन अनुपलब्ध चिल्ड्रन callable=false के साथ दृश्यमान रहते हैं। Doris RBAC सभी Doris ऑब्जेक्ट एक्सेस के लिए अंतिम डेटा प्राधिकरण बैकएंड बना हुआ है।

4. सेवा चलाएँ

सर्वर प्रारंभ करने के लिए निम्नलिखित कमांड निष्पादित करें:

./start_server.sh

यह कमांड स्ट्रीमेबल HTTP MCP सेवा के साथ FastAPI एप्लिकेशन प्रारंभ करता है।

5. डॉकर पर तैनात करना

यदि आप डॉकर में केवल Doris MCP सर्वर चलाना चाहते हैं:

cd doris-mcp-server
docker build -t doris-mcp-server .
docker run -d -p <host-port>:3000 -v /*your-host*/doris-mcp-server/.env:/app/.env --name <your-mcp-server-name> doris-mcp-server:latest

कंटेनर हमेशा पोर्ट 3000 पर सुनता है। बंडल किया गया कम्पोज़ परिनियोजन इसे डिफ़ॉल्ट रूप से होस्ट पोर्ट 3000 पर प्रकाशित करता है और Grafana को होस्ट पोर्ट 3003 पर प्रकाशित करता है, ताकि दोनों सेवाएँ एक ही पोर्ट के लिए प्रतिस्पर्धा न करें। उन डिफ़ॉल्ट को MCP_HTTP_PORT और GRAFANA_HTTP_PORT के साथ ओवरराइड करें:

MCP_HTTP_PORT=3100 GRAFANA_HTTP_PORT=3103 docker compose up -d

बंडल किए गए स्टैक को शुरू करने से पहले, कम्पोज़ द्वारा उपयोग की जाने वाली पाँच अनदेखी गुप्त फ़ाइलें बनाएँ। कोई भी डेटाबेस, MCP, Redis, या Grafana क्रेडेंशियल docker-compose.yml, .env.example, या रेंडर किए गए सेवा वातावरण में संग्रहीत नहीं है:

mkdir -p .secrets
chmod 700 .secrets
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/doris_password
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/mcp_static_token
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/redis_password
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/grafana_admin_password
python -c 'import hashlib, pathlib; p=pathlib.Path(".secrets/doris_password").read_text().rstrip("\n").encode(); print("initial_root_password = *" + hashlib.sha1(hashlib.sha1(p).digest()).hexdigest().upper())' > .secrets/doris_fe_custom.conf
chmod 0444 .secrets/*
docker compose up -d

doris_fe_custom.conf में Doris का दो-चरणीय SHA-1 पासवर्ड सत्यापनकर्ता होता है, न कि सादा पाठ पासवर्ड, और इसे FE प्रारंभिक-रूट कॉन्फ़िगरेशन के रूप में माउंट किया जाता है। मिलान वाली सादा पाठ फ़ाइल केवल उन सेवाओं में माउंट की जाती है जिन्हें Doris से प्रमाणित करना होता है। दोनों फ़ाइलों को क्रेडेंशियल के रूप में मानें। मूल निर्देशिका मोड 0700 रहती है, जबकि फ़ाइलें गैर-रूट MCP प्रक्रिया के लिए होस्ट-रीड-ओनली और कंटेनर-रीडेबल होती हैं। गुप्त फ़ाइलों को कहीं और रखने के लिए, .env.example को .env में कॉपी करें और केवल COMPOSE_*_FILE होस्ट पथ बदलें।

कम्पोज़ मॉडल में सभी तृतीय-पक्ष छवियाँ एक स्पष्ट अपस्ट्रीम संस्करण और एक अपरिवर्तनीय OCI डाइजेस्ट का उपयोग करती हैं। संस्करण टैग और डाइजेस्ट दोनों को बदलकर उन्हें जानबूझकर अपग्रेड करें, फिर परिनियोजन अनुबंध और परिवहन परीक्षण पुनः चलाएँ; उन्हें latest या किसी अन्य अस्थायी टैग से न बदलें।

छवि-स्तरीय Docker स्वास्थ्य जाँच /live का उपयोग करती है, इसलिए एक अस्थायी Doris आउटेज के कारण MCP प्रक्रिया को मृत नहीं माना जाता है। कम्पोज़ उस जाँच को /ready के साथ ओवरराइड करता है और केवल तभी सेवा को तैयार चिह्नित करता है जब सीमित Doris जाँच सफल होती है। दोनों जाँचें पोर्ट 3000 पर वास्तविक आंतरिक श्रोता का उपयोग करती हैं।

कम्पोज़ डिफ़ॉल्ट रूप से 127.0.0.1:* और localhost:* होस्ट हेडर की अनुमति देता है। किसी अन्य होस्टनाम, IP पते या रिवर्स प्रॉक्सी के माध्यम से पहुँचे गए परिनियोजन को एक स्पष्ट अल्पविराम से अलग अनुमति सूची सेट करनी होगी; एक अनुमति-सभी * मान अस्वीकार कर दिया जाता है:

MCP_ALLOWED_HOSTS='mcp.example.com,mcp.example.com:*' docker compose up -d

सेवा समापन बिंदु:

स्ट्रीमेबल HTTP: http://<host>:<port>/mcp (MCP संदेश POST का उपयोग करते हैं; GET या DELETE संगतता व्यवहार पर निर्भर न रहें)
जीवंतता: http://<host>:<port>/live — प्रक्रिया और प्रोटोकॉल सेवा चल रही है; Doris पर निर्भर नहीं है
तत्परता: http://<host>:<port>/ready — केवल तभी 200 लौटाता है जब एक सीमित Doris SELECT 1 जाँच सफल होती है; अन्यथा 503 लौटाता है
विरासत स्वास्थ्य जाँच: http://<host>:<port>/health — पश्च-संगत जीवंतता उपनाम; डेटाबेस कार्य को रूट करने का निर्णय लेने के लिए इसका उपयोग न करें

तत्परता जाँच का एक निश्चित छोटा टाइमआउट होता है और यह केवल स्थिर स्थिति फ़ील्ड को उजागर करती है, कनेक्शन त्रुटियों या क्रेडेंशियल्स को नहीं। Stdio मोड में कोई HTTP स्वास्थ्य सतह नहीं होती है; प्रक्रिया की निगरानी करें और परिवहन-स्तरीय उपलब्धता के लिए MCP आरंभीकरण/खोज हैंडशेक का उपयोग करें।

नोट: सर्वर वेब-आधारित संचार के लिए स्ट्रीमेबल HTTP का उपयोग करता है, जो एकीकृत अनुरोध/प्रतिक्रिया और स्ट्रीमिंग क्षमताएँ प्रदान करता है।

MCP प्रोटोकॉल समर्थन और माइग्रेशन

Doris MCP सर्वर स्ट्रीमेबल HTTP और stdio दोनों के लिए आधिकारिक Python SDK v2 प्रोटोकॉल कोर का उपयोग करता है। वायर पर उपयोग किया जाने वाला MCP प्रोटोकॉल संशोधन Doris MCP सर्वर पैकेज संस्करण और Python SDK पैकेज संस्करण से स्वतंत्र है।

आधिकारिक प्रोटोकॉल संदर्भ हैं MCP 2026-07-28 विनिर्देश, 2026-07-28 मुख्य परिवर्तन, और स्ट्रीमेबल HTTP परिवहन विनिर्देश।

प्रोटोकॉल और परिवहन मैट्रिक्स

क्लाइंट प्रोटोकॉल	स्ट्रीमेबल HTTP	stdio	कनेक्शन व्यवहार	Doris MCP सर्वर स्थिति
`2026-07-28`	समर्थित और पसंदीदा	समर्थित और पसंदीदा	स्टेटलेस, स्व-निहित अनुरोध; कोई आरंभीकरण हैंडशेक या प्रोटोकॉल सत्र नहीं	आधुनिक HTTP और वास्तविक-प्रक्रिया stdio परीक्षणों द्वारा कवर किया गया
`2025-11-25`	`/mcp/legacy` पर ऑप्ट-इन	माइग्रेशन के लिए समर्थित	लीगेसी `initialize` स्वीकार किया जाता है, लेकिन सर्वर स्टेटलेस रहता है और `Mcp-Session-Id` जारी नहीं करता है	HTTP एडाप्टर डिफ़ॉल्ट रूप से अक्षम है; लीगेसी HTTP और stdio परीक्षणों द्वारा कवर किया गया
`2025-06-18` और पुराने	गारंटी नहीं	गारंटी नहीं	पुराना वार्ता और परिवहन व्यवहार समर्थित संगतता अनुबंध के बाहर है	कनेक्ट करने से पहले क्लाइंट को अपग्रेड करें
HTTP+SSE (`2024-11-05`)	समर्थित नहीं	लागू नहीं	सेवानिवृत्त अलग SSE एंडपॉइंट उजागर नहीं किया गया है	`/mcp` पर स्ट्रीमेबल HTTP पर माइग्रेट करें

2025-11-25 के लिए HTTP संगतता पथ आधुनिक एंडपॉइंट से पृथक है और डिफ़ॉल्ट रूप से अक्षम है। नए एकीकरणों को POST /mcp पर 2026-07-28 को लक्षित करना चाहिए।

MCP 2026-07-28 अनुरोध अनुबंध

आधुनिक क्लाइंट समर्थित प्रोटोकॉल संस्करणों, क्षमताओं और सर्वर पहचान का निरीक्षण करने के लिए किसी भी अन्य विधि से पहले server/discover कॉल कर सकते हैं। खोज वैकल्पिक है; प्रत्येक सामान्य अनुरोध अभी भी स्व-निहित है।

प्रत्येक आधुनिक अनुरोध में params._meta में ये मान होने चाहिए:

io.modelcontextprotocol/protocolVersion: 2026-07-28
io.modelcontextprotocol/clientCapabilities: उस अनुरोध के लिए उपलब्ध क्षमताएं, या एक खाली ऑब्जेक्ट
io.modelcontextprotocol/clientInfo: क्लाइंट का नाम और संस्करण; यह विनिर्देश द्वारा अनुशंसित है

स्ट्रीमेबल HTTP के लिए, प्रति POST /mcp एक JSON-RPC अनुरोध भेजें और शामिल करें:

हेडर	आवश्यक	मान
`Content-Type`	हाँ	`application/json`
`Accept`	हाँ	`application/json` और `text/event-stream` दोनों
`MCP-Protocol-Version`	हाँ	`_meta` में प्रोटोकॉल संस्करण से मेल खाना चाहिए
`Mcp-Method`	हाँ	JSON-RPC `method` से मेल खाना चाहिए
`Mcp-Name`	`tools/call`, `resources/read`, और `prompts/get` के लिए	`params.name` या `params.uri` से मेल खाना चाहिए

हेडर नाम केस-असंवेदनशील हैं, लेकिन विधि और नाम मान नहीं हैं। एक आवश्यक हेडर जो गायब है या अनुरोध निकाय से असहमत है, HTTP 400 और प्रोटोकॉल HeaderMismatch त्रुटि (-32020) के साथ अस्वीकार कर दिया जाता है। असमर्थित प्रोटोकॉल संस्करण UnsupportedProtocolVersion (-32022) के साथ अस्वीकार कर दिए जाते हैं। यदि कोई नाम या URI सादे ASCII हेडर मान के रूप में सुरक्षित नहीं है, तो उसके UTF-8 बाइट्स को Base64 के रूप में एन्कोड करें और परिवहन विनिर्देश द्वारा परिभाषित Mcp-Name: =?base64?{value}?= भेजें।

उदाहरण खोज अनुरोध:

curl --request POST http://127.0.0.1:3000/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: server/discover' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {
          "name": "example-client",
          "version": "1.0.0"
        }
      }
    }
  }'

Stdio संदेश निकाय में समान JSON-RPC अनुरोध मेटाडेटा रखता है, लेकिन यह HTTP हेडर का उपयोग नहीं करता है। stdio मोड में stdout पर लॉग या अन्य निदान न लिखें; stdout MCP प्रोटोकॉल संदेशों के लिए आरक्षित है।

OpenTelemetry ट्रेस संदर्भ

क्लाइंट params._meta में W3C traceparent, tracestate, और baggage वाहक फ़ील्ड का प्रचार कर सकते हैं, जैसा कि MCP SEP-414, W3C ट्रेस संदर्भ, और W3C बैगेज द्वारा परिभाषित किया गया है। वही संदेश-स्तरीय वाहक स्ट्रीमेबल HTTP और stdio पर काम करता है; ये मान अलग MCP HTTP हेडर नहीं हैं।

जब एक OpenTelemetry प्रदाता और निर्यातक कॉन्फ़िगर किया जाता है, तो प्रत्येक MCP ऑपरेशन स्पैन मान्य आने वाले ट्रेस संदर्भ का जनक होता है। सक्रिय संदर्भ उस ऑपरेशन के जीवनकाल के लिए इंस्ट्रूमेंटेड डाउनस्ट्रीम कार्य के लिए उपलब्ध है और अगले अनुरोध से पहले रीसेट हो जाता है। ट्रेस वाहक फ़ील्ड कभी भी Doris टूल, संसाधन, या प्रॉम्प्ट प्रबंधकों को पास नहीं किए जाते हैं और कभी भी मॉडल सामग्री या संरचित परिणामों में कॉपी नहीं किए जाते हैं।

सर्वर SDK प्रचारक द्वारा देखे जाने से पहले ट्रेस वाहक मानों को मान्य करता है। विकृत, अतिविशाल, डुप्लिकेट, या अनाथ फ़ील्ड को स्वतंत्र रूप से अनदेखा कर दिया जाता है, और चेतावनी लॉग केवल फ़ील्ड नाम की पहचान करते हैं—कभी भी इसके आपूर्ति किए गए मान की नहीं। token, secret, या authorization जैसी क्रेडेंशियल-जैसी बैगेज कुंजियों के अंतर्गत मानों को प्रचार से पहले [REDACTED] से बदल दिया जाता है। baggage में अभी भी अन्य परिनियोजन-संवेदनशील सहसंबंध डेटा हो सकता है, इसलिए क्लाइंट को केवल अपनी टेलीमेट्री डेटा-हैंडलिंग नीति द्वारा अनुमोदित मान ही भेजने चाहिए।

सूची पृष्ठांकन

resources/list, tools/list, और prompts/list स्ट्रीमेबल HTTP और stdio दोनों पर प्रति प्रतिक्रिया अधिकतम MCP_LIST_PAGE_SIZE प्रविष्टियाँ लौटाते हैं। परिणाम उनके स्थिर संसाधन URI, टूल नाम, या प्रॉम्प्ट नाम के अनुसार क्रमबद्ध होते हैं। जब nextCursor मौजूद हो, तो उस अपारदर्शी मान को अगले अनुरोध के cursor के रूप में पास करें; कर्सर को पार्स या निर्मित न करें।

एक कर्सर एक HMAC-प्रमाणीकृत स्पष्ट स्थिति हैंडल है जो इसके सूची प्रकार, दायरे, संसाधन, वर्तमान दृश्य-सूची स्नैपशॉट, प्राधिकरण संदर्भ और समाप्ति से बंधा होता है। यह MCP प्रोटोकॉल सत्र, परिवहन कनेक्शन, या कार्यकर्ता-स्थानीय मेमोरी पर निर्भर नहीं करता है। इसे किसी अन्य सूची के लिए, दृश्यता परिवर्तनों के बाद, समाप्ति के बाद, संशोधन के बाद, या किसी अन्य प्रिंसिपल के तहत पुन: उपयोग करने पर Invalid Params लौटाता है। उस स्थिति में बिना कर्सर के सूचीकरण पुनः आरंभ करें। यह एक बहु-पृष्ठ ट्रैवर्सल को चुपचाप डुप्लिकेट करने, छोड़ने, या अनुमति-स्कोप्ड प्रविष्टियों को पार करने से रोकता है।

सर्वर डिफ़ॉल्ट रूप से एक लॉन्च-स्थानीय हैंडल रहस्य उत्पन्न करता है और इसे उसी CLI प्रक्रिया द्वारा बनाए गए सभी कार्यकर्ताओं को पास करता है। स्वतंत्र रूप से लॉन्च की गई प्रतिकृतियों पर एक साझा MCP_STATE_HANDLE_SECRET सेट करें जब एक लोड बैलेंसर लगातार पृष्ठों को विभिन्न उदाहरणों में रूट कर सकता है। हैंडल पेलोड में सीमित निरंतरता मेटाडेटा होता है और एन्क्रिप्टेड के बजाय हस्ताक्षरित होते हैं; क्रेडेंशियल, SQL टेक्स्ट और क्वेरी परिणाम कभी भी उनमें नहीं रखे जाने चाहिए। देखें ADR 0002।

सूची विफलताओं को कभी भी सफल खाली संग्रह के रूप में प्रस्तुत नहीं किया जाता है। एक Doris मेटाडेटा आउटेज List backend unavailable लौटाता है; एक Doris मेटाडेटा अनुमति विफलता List operation permission denied लौटाती है; और एक अप्रत्याशित टूल/संसाधन/प्रॉम्प्ट रजिस्ट्री विफलता Internal server error लौटाती है। ये प्रतिक्रियाएं JSON-RPC कोड -32603 का उपयोग करती हैं और इसमें केवल सूची संचालन और एक सीमित त्रुटि श्रेणी/कोड शामिल होता है, कभी भी बैकएंड अपवाद टेक्स्ट नहीं। एक खाली resources, tools, या prompts सरणी के साथ एक सफल प्रतिक्रिया का अर्थ है कि कॉलर का दृश्य संग्रह वास्तव में खाली है। वही अनुबंध स्ट्रीमेबल HTTP और stdio पर लागू होता है, और एक विफल अनुरोध अगले सूची अनुरोध को सफल होने से नहीं रोकता है।

सदस्यता और परिवर्तन सूचनाएं

सर्वर वर्तमान में subscriptions/listen का विज्ञापन या सेवा नहीं करता है। टूल और प्रॉम्प्ट में कोई रनटाइम उत्परिवर्तन चैनल नहीं है, और Doris कैटलॉग मेटाडेटा इस प्रक्रिया को एक विश्वसनीय क्रॉस-वर्कर परिवर्तन-घटना स्रोत प्रदान नहीं करता है। कैश समाप्ति और आवधिक कैटलॉग पोलिंग को परिवर्तन घटनाओं के रूप में नहीं माना जाता है।

नतीजतन, MCP 2026-07-28 खोज टूल, प्रॉम्प्ट और संसाधनों के लिए listChanged: false और संसाधनों के लिए subscribe: false रिपोर्ट करती है। एक subscriptions/listen अनुरोध Method not found लौटाता है; क्लाइंट को स्पष्ट रूप से सूचियों को ताज़ा करना चाहिए। स्ट्रीमेबल HTTP और सच्चे उपप्रक्रिया stdio परीक्षण इस सीमा को लागू करते हैं। देखें सदस्यता निर्णय रिकॉर्ड उन शर्तों के लिए जो क्षमता को सक्षम करने से पहले आवश्यक हैं।

टूल JSON स्कीमा सत्यापन

टूल inputSchema और outputSchema JSON स्कीमा 2020-12 का उपयोग करते हैं। सर्वर प्रत्येक दृश्य टूल परिभाषा को विज्ञापित करने या निष्पादित करने से पहले मान्य करता है, फिर Doris को आमंत्रित करने से पहले प्रत्येक कॉल के तर्कों को मान्य करता है। अमान्य तर्क अस्वीकृत मानों को प्रतिध्वनित किए बिना Invalid Params लौटाते हैं। सफल संरचित परिणामों की भी जाँच की जाती है जब भी कोई टूल outputSchema घोषित करता है; एक सर्वर-साइड स्कीमा बेमेल Internal error के पीछे छिपा होता है।

स्कीमा स्व-निहित हैं। केवल समान-दस्तावेज़ $ref और $dynamicRef अंश स्वीकार किए जाते हैं; सर्वर कभी भी HTTP, फ़ाइल URI, या सापेक्ष URI से स्कीमा प्राप्त नहीं करता है। पुनरावर्ती संदर्भ सीमित सत्यापन नीति द्वारा अस्वीकार कर दिए जाते हैं। प्रति स्कीमा डिफ़ॉल्ट कठोर सीमाएं 64 KiB, 2,048 नोड्स, गहराई 32, 64 संरचना शाखाएं, और 64 संदर्भ हैं। प्रत्येक इनपुट या संरचित आउटपुट 1 MiB, 10,000 नोड्स, गहराई 32, और प्रति स्ट्रिंग 262,144 वर्णों तक सीमित है। अधिकतम 16 सत्यापन उल्लंघन रिपोर्ट किए जाते हैं, और रिपोर्ट में केवल उदाहरण पथ और विफल कीवर्ड होते हैं।

ये जाँच साझा प्रोटोकॉल हैंडलर में चलती हैं, इसलिए स्ट्रीमेबल HTTP, आधुनिक stdio और लीगेसी stdio समान प्रवर्तन का उपयोग करते हैं। MCP 2026-07-28 क्लाइंट एक मिलान outputSchema घोषित होने पर सरणी, स्ट्रिंग, संख्या या बूलियन structuredContent भी प्राप्त कर सकते हैं।

MCP 2025-11-25 से माइग्रेट करना

क्लाइंट को 2026-07-28-सक्षम MCP SDK में अपग्रेड करें।
स्ट्रीमेबल HTTP के लिए /mcp एंडपॉइंट का उपयोग जारी रखें, लेकिन प्रत्येक JSON-RPC संदेश को अपने स्वयं के POST अनुरोध के रूप में भेजें।
initialize, notifications/initialized, Mcp-Session-Id, और किसी भी स्टिकी-सत्र निर्भरता को हटा दें।
प्रत्येक अनुरोध के _meta में प्रोटोकॉल संस्करण और क्लाइंट क्षमताएं जोड़ें। जहाँ संभव हो प्रत्येक अनुरोध पर क्लाइंट पहचान जोड़ें।
प्रत्येक HTTP अनुरोध में MCP-Protocol-Version और Mcp-Method जोड़ें, साथ ही नामित टूल, संसाधन और प्रॉम्प्ट अनुरोधों के लिए Mcp-Name जोड़ें।
हटाए गए HTTP GET स्ट्रीम, Last-Event-ID, और पुनः आरंभ करने योग्य SSE व्यवहार का उपयोग बंद करें। एक नए JSON-RPC अनुरोध ID के साथ बाधित अनुरोध को पुनः जारी करें।
आधुनिक परिणामों में आवश्यक resultType फ़ील्ड स्वीकार करें और प्रोटोकॉल-परिभाषित त्रुटियों जैसे -32020, -32021, और -32022 को संभालें।
यदि एकीकरण दोनों परिवहनों का समर्थन करता है तो माइग्रेटेड क्लाइंट को स्ट्रीमेबल HTTP और stdio दोनों के विरुद्ध मान्य करें।

जो क्लाइंट तुरंत माइग्रेट नहीं कर सकते, वे stdio पर 2025-11-25 initialize प्रवाह रख सकते हैं। स्ट्रीमेबल HTTP के लिए, एक ऑपरेटर को स्पष्ट रूप से ENABLE_LEGACY_HTTP_ADAPTER=true सेट करना होगा और उस क्लाइंट को /mcp/legacy पर इंगित करना होगा; /mcp कभी भी लीगेसी परिवहन पर वापस नहीं आता है। एडाप्टर स्टेटलेस रहता है और HTTP प्रोटोकॉल सत्र नहीं बनाता है।

परिनियोजन बाधाएं

स्थानीय परिनियोजनों को 127.0.0.1, localhost, या ::1 से बांधें। परिवहन DNS रीबाइंडिंग से बचाने के लिए Host और Origin दोनों को मान्य करता है।
एक बाइंड पता एक सार्वजनिक सेवा पहचान नहीं है। विशेष रूप से, 0.0.0.0 मनमाने Host या Origin मानों को अधिकृत नहीं करता है।
वर्तमान Host/Origin नीति एक ऑपरेटर-कॉन्फ़िगर सार्वजनिक अनुमति सूची प्रदान नहीं करती है। सार्वजनिक होस्टनाम और रिवर्स प्रॉक्सी जो Host या Origin को फिर से लिखते हैं, इसलिए अभी तक एक समर्थित परिनियोजन आकार नहीं हैं।
HTTP स्टार्टअप विफल हो जाता है जब बाइंड होस्ट लूपबैक नहीं है और कोई प्रमाणीकरण विधि सक्षम नहीं है। ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true केवल पृथक परीक्षण के लिए एक स्पष्ट खतरनाक ओवरराइड है; इसे परिनियोजन शॉर्टकट के रूप में उपयोग न करें।
स्टेटलेस MCP अनुरोधों को स्टिकी HTTP सत्रों की आवश्यकता नहीं होती है और वे कई कार्यकर्ताओं का उपयोग कर सकते हैं। प्रमाणीकरण मोड की सख्त सीमाएं हो सकती हैं: Doris-समर्थित OAuth प्रक्रिया मेमोरी में टोकन और प्रति-उपयोगकर्ता पूल संग्रहीत करता है और इसे WORKERS=1 के साथ चलना चाहिए।
जब भी ट्रैफ़िक स्थानीय मशीन छोड़ता है तो HTTPS का उपयोग करें, और URL के बजाय हेडर या प्रक्रिया वातावरण में क्रेडेंशियल रखें।

उपयोग

Doris MCP सर्वर के साथ सहभागिता के लिए एक MCP क्लाइंट की आवश्यकता होती है। क्लाइंट सर्वर के स्ट्रीमेबल HTTP एंडपॉइंट से जुड़ता है और सर्वर के टूल्स को आमंत्रित करने के लिए MCP विनिर्देश के अनुसार अनुरोध भेजता है।

मुख्य सहभागिता प्रवाह:

(वैकल्पिक) सर्वर खोजें: एक आधुनिक क्लाइंट समर्थित प्रोटोकॉल संस्करणों, क्षमताओं और पहचान का निरीक्षण करने के लिए server/discover को कॉल कर सकता है।
डोमेन खोजें: डिफ़ॉल्ट hierarchical मोड में, tools/list आठ सीमाबद्ध केवल-पढ़ने योग्य डोमेन लौटाता है। किसी डोमेन को बिना तर्कों के कॉल करें ताकि उसके सटीक चाइल्ड नाम, स्कीमा और उपलब्धता का पता लगाया जा सके।
एक सटीक चाइल्ड को कॉल करें: उसी डोमेन को child_tool, arguments, और खोजे गए manifest_version के साथ कॉल करें।
- उदाहरण: तालिका स्कीमा अनुभाग प्राप्त करें
  - name: doris_catalog
  - child_tool: get_table_context
  - arguments: database, table, वैकल्पिक catalog, और sections: ["schema"] शामिल करें।
- flat मोड में, टकराव-मुक्त औपचारिक नाम doris_catalog_get_table_context को सीधे चाइल्ड तर्कों के साथ कॉल करें।
प्रतिक्रिया संभालें:
- नॉन-स्ट्रीमिंग: क्लाइंट को content या isError वाली प्रतिक्रिया प्राप्त होती है।
- स्ट्रीमिंग: क्लाइंट को प्रगति सूचनाओं की एक श्रृंखला प्राप्त होती है, जिसके बाद एक अंतिम प्रतिक्रिया आती है।

लीगेसी 2025-11-25 stdio क्लाइंट पहले की तरह आरंभ होते हैं। HTTP क्लाइंट को स्पष्ट रूप से सक्षम /mcp/legacy एडाप्टर की आवश्यकता होती है और वे ऊपर वर्णित स्टेटलेस संगतता सीमाओं के अधीन रहते हैं।

कैटलॉग फेडरेशन समर्थन

Doris MCP सर्वर कैटलॉग फेडरेशन का समर्थन करता है, जो एक एकीकृत इंटरफ़ेस के भीतर कई डेटा कैटलॉग (आंतरिक Doris तालिकाएँ और Hive, MySQL, आदि जैसे बाहरी डेटा स्रोत) के साथ सहभागिता को सक्षम करता है।

मुख्य विशेषताएँ:

मल्टी-कैटलॉग मेटाडेटा एक्सेस: doris_catalog चाइल्ड जहाँ लागू हो, एक वैकल्पिक catalog तर्क स्वीकार करते हैं।
क्रॉस-कैटलॉग SQL क्वेरीज़: तीन-भाग तालिका नामकरण के साथ doris_query.execute_query का उपयोग करें।
कैटलॉग खोज: doris_catalog.list_catalogs का उपयोग करें।

तीन-भाग नामकरण आवश्यकता:

सभी SQL क्वेरीज़ को तालिका संदर्भों के लिए तीन-भाग नामकरण का उपयोग करना चाहिए:

आंतरिक तालिकाएँ: internal.database_name.table_name
बाहरी तालिकाएँ: catalog_name.database_name.table_name

उदाहरण:

उपलब्ध कैटलॉग प्राप्त करें:

{
  "tool_name": "doris_catalog",
  "arguments": {
    "child_tool": "list_catalogs",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {}
  }
}

विशिष्ट कैटलॉग में डेटाबेस प्राप्त करें:

{
  "tool_name": "doris_catalog",
  "arguments": {
    "child_tool": "list_databases",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {"catalog": "mysql"}
  }
}

आंतरिक कैटलॉग क्वेरी करें:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "execute_query",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "sql": "SELECT COUNT(*) FROM internal.ssb.customer"
    }
  }
}

बाहरी कैटलॉग क्वेरी करें:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "execute_query",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "sql": "SELECT COUNT(*) FROM mysql.ssb.customer"
    }
  }
}

क्रॉस-कैटलॉग क्वेरी:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "execute_query",
    "arguments": {
      "sql": "SELECT i.c_name, m.external_data FROM internal.ssb.customer i JOIN mysql.test.user_info m ON i.c_custkey = m.customer_id"
    }
  }
}

सुरक्षा कॉन्फ़िगरेशन

Doris MCP सर्वर में उन्नत प्रमाणीकरण, प्राधिकरण, SQL सुरक्षा सत्यापन और v0.6.0 में बढ़ाई गई डेटा मास्किंग क्षमताओं के साथ एक व्यापक एंटरप्राइज़-ग्रेड सुरक्षा ढाँचा शामिल है।

सुरक्षा सुविधाएँ (v0.6.0 में बढ़ाई गई)

🔐 मल्टी-प्रमाणीकरण प्रणाली: स्वतंत्र नियंत्रण स्विच के साथ पूर्ण टोकन, JWT और OAuth प्रमाणीकरण
🔗 टोकन-बाउंड डेटाबेस कॉन्फ़िगरेशन: क्रांतिकारी दृष्टिकोण जो टोकन को अपने स्वयं के डेटाबेस कनेक्शन पैरामीटर ले जाने की अनुमति देता है
🔄 हॉट रीलोड सुरक्षा: बुद्धिमान टोकन पुनर्सत्यापन के साथ शून्य-डाउनटाइम सुरक्षा कॉन्फ़िगरेशन अपडेट
⚡ रूट-सुरक्षित सत्यापन: टोकन-बाउंड Doris रूट को उनके समर्पित पूल के माध्यम से मान्य किया जाता है, एक छोटी सफलता कैश के साथ ताकि पिंग हर अनुरोध पर पुनः कनेक्ट न हों
🛡️ भूमिका-आधारित प्राधिकरण: चार-स्तरीय सुरक्षा वर्गीकरण के साथ उन्नत RBAC
🚫 उन्नत SQL सुरक्षा: बेहतर पैटर्न डिटेक्शन के साथ उन्नत SQL इंजेक्शन सुरक्षा
🎭 बुद्धिमान डेटा मास्किंग: उपयोगकर्ता-आधारित अनुमतियों के साथ स्वचालित संवेदनशील डेटा मास्किंग
📊 सुरक्षा विश्लेषिकी: व्यापक ऑडिट ट्रेल्स और सुरक्षा निगरानी

प्रमाणीकरण कॉन्फ़िगरेशन (v0.6.0)

विस्तृत नियंत्रण के साथ नई प्रमाणीकरण प्रणाली कॉन्फ़िगर करें:

# Generate a deployment-specific token before enabling static authentication.
export TOKEN_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

# Individual Authentication Control (New in v0.6.0)
ENABLE_TOKEN_AUTH=true          # Enable token-based authentication
ENABLE_JWT_AUTH=false           # Enable JWT authentication  
ENABLE_OAUTH_AUTH=false         # Enable OAuth authentication

# Token Management (New in v0.6.0)
TOKEN_FILE_PATH=tokens.json     # Token configuration file
TOKEN_HOT_RELOAD=true          # Enable hot reloading
TOKEN_DB_VALIDATION_TTL_SECONDS=30  # Cache successful Doris route checks

# Legacy Configuration (Deprecated)
# AUTH_TYPE=token               # Use individual switches instead

रिपॉजिटरी कोई प्रयोग करने योग्य स्थैतिक टोकन या लीगेसी सीक्रेट शिप नहीं करता है। स्टार्टअप विफल हो जाता है जब स्थैतिक टोकन प्रमाणीकरण कम से कम एक सक्रिय, उच्च-एन्ट्रॉपी TOKEN_<ID> मान या TOKEN_FILE_PATH में समतुल्य प्रविष्टि के बिना सक्षम होता है।

बाहरी OAuth/OIDC एक्सेस टोकन सत्यापन

बाहरी OAuth विफल-बंद है। सर्वर द्वारा उपयोगकर्ता जानकारी का अनुरोध करने से पहले, यह एक विश्वसनीय RFC 7662 इंट्रॉस्पेक्शन एंडपॉइंट का उपयोग करता है और सटीक कॉन्फ़िगर किए गए जारीकर्ता, अपेक्षित ऑडियंस, MCP संसाधन बाइंडिंग, आवश्यक स्कोप और एक विषय के साथ एक सक्रिय, असमाप्त टोकन की आवश्यकता होती है। एक सफल userinfo अनुरोध को इस बात के प्रमाण के रूप में स्वीकार नहीं किया जाता है कि टोकन इस MCP सर्वर के लिए जारी किया गया था। userinfo विषय को इंट्रॉस्पेक्टेड टोकन विषय से भी मेल खाना चाहिए।

OAUTH_RESOURCE प्राधिकरण-कोड और रिफ्रेश-टोकन अनुरोधों पर भेजा जाता है। OAUTH_AUDIENCE उस संसाधन URI पर डिफ़ॉल्ट होता है। OAUTH_REQUIRED_SCOPE OAUTH_SCOPE में सभी स्कोप पर डिफ़ॉल्ट होता है; प्राधिकरण सर्वर द्वारा लौटाए गए लेकिन OAUTH_SCOPE में मौजूद नहीं स्कोप प्रमाणीकरण संदर्भ से बाहर रखे जाते हैं।

ENABLE_OAUTH_AUTH=true
OAUTH_CLIENT_ID=your_oauth_client_id
OAUTH_CLIENT_SECRET=your_oauth_client_secret
OAUTH_REDIRECT_URI=https://mcp.example.com/auth/callback

OAUTH_ISSUER=https://issuer.example.com
OAUTH_RESOURCE=https://mcp.example.com/mcp
OAUTH_AUDIENCE=https://mcp.example.com/mcp
OAUTH_INTROSPECTION_URL=https://issuer.example.com/introspect
OAUTH_USERINFO_URL=https://issuer.example.com/userinfo

OAUTH_SCOPE="tool:list tool:call:exec_query resource:list resource:read"
OAUTH_REQUIRED_SCOPE="tool:list resource:read"

एक प्राधिकरण-सर्वर खोज दस्तावेज़ इंट्रॉस्पेक्शन और userinfo एंडपॉइंट प्रदान कर सकता है, लेकिन इसका issuer बिल्कुल OAUTH_ISSUER से मेल खाना चाहिए। समर्पित OAUTH_INTROSPECTION_CLIENT_ID और OAUTH_INTROSPECTION_CLIENT_SECRET मान कॉन्फ़िगर किए जा सकते हैं; अन्यथा नियमित OAuth क्लाइंट क्रेडेंशियल्स का उपयोग किया जाता है। दूरस्थ जारीकर्ता, खोज, इंट्रॉस्पेक्शन और userinfo URL को HTTPS का उपयोग करना चाहिए।

HTTP परिनियोजन के लिए, सर्वर /.well-known/oauth-protected-resource पर RFC 9728 मेटाडेटा प्रकाशित करता है। अनुपलब्ध या अमान्य क्रेडेंशियल्स को resource_metadata और न्यूनतम कॉन्फ़िगर किए गए स्कोप वाली HTTP 401 Bearer चुनौती प्राप्त होती है। एक वैध टोकन जिसमें ऑपरेशन स्कोप की कमी है, उसे स्टेप-अप प्राधिकरण के लिए आवश्यक सटीक स्कोप के साथ error="insufficient_scope" और HTTP 403 प्राप्त होता है। एक्सेस टोकन और प्रदाता-आंतरिक त्रुटि विवरण इन प्रतिक्रियाओं में कॉपी नहीं किए जाते हैं। ये HTTP OAuth चुनौतियाँ stdio ट्रांसपोर्ट पर लागू नहीं होती हैं, जहाँ क्रेडेंशियल्स स्थानीय प्रक्रिया वातावरण के माध्यम से आपूर्ति की जाती हैं।

बाहरी OAuth ऑपरेशन स्कोप सटीक हैं: उपकरणों को सूचीबद्ध करने के लिए tool:list की आवश्यकता होती है, किसी उपकरण को कॉल करने के लिए tool:call:<tool-name> की आवश्यकता होती है, संसाधनों को सूचीबद्ध करने और पढ़ने के लिए resource:list और resource:read की आवश्यकता होती है, और Prompt संचालन के लिए prompt:list और prompt:get की आवश्यकता होती है। प्रत्येक कॉल करने योग्य उपकरण स्कोप को OAUTH_SCOPE में जोड़ें; * और असंबंधित स्कोप कभी भी ऑपरेशन जाँच को संतुष्ट नहीं करते हैं। स्थैतिक टोकन, JWT, अनाम लूपबैक और स्थानीय stdio प्राधिकरण अपने मौजूदा गैर-OAuth अनुमति व्यवहार को बनाए रखते हैं।

Doris-समर्थित OAuth प्रमाणीकरण

Doris-समर्थित OAuth एक अलग OAuth मोड है जहाँ Doris स्वयं प्राधिकरण बैकएंड है। MCP क्लाइंट इस सर्वर के OAuth मेटाडेटा की खोज करता है, उपयोगकर्ता Doris उपयोगकर्ता नाम और पासवर्ड के साथ साइन इन करता है, सर्वर प्रति-उपयोगकर्ता Doris कनेक्शन पूल बनाकर उन क्रेडेंशियल्स को मान्य करता है, और जारी किए गए doa_ एक्सेस टोकन उस Doris उपयोगकर्ता के पूल के माध्यम से उपकरण कॉल को रूट करते हैं। MCP स्कोप नियंत्रित करते हैं कि कौन से MCP संचालन कॉल किए जा सकते हैं; Doris RBAC नियंत्रित करता है कि उपयोगकर्ता कौन से कैटलॉग, डेटाबेस, तालिकाएँ और मेटाडेटा देख सकता है।

यह मोड बाहरी OAuth/OIDC के समान नहीं है। ENABLE_DORIS_OAUTH_AUTH=true ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true, और लीगेसी AUTH_TYPE=oauth के साथ विरोध करता है; यदि दोनों मोड कॉन्फ़िगर किए गए हैं तो स्टार्टअप तेजी से विफल हो जाता है। एक मानक MCP एजेंट एक MCP URL दर्ज करता है और उसे उस URL के लिए बिल्कुल एक OAuth व्यवहार खोजना चाहिए, इसलिए मौजूदा /auth/* बाहरी OAuth लॉगिन प्रवाह Doris-समर्थित OAuth मोड में उपयोग नहीं किया जाता है।

प्रत्येक Doris OAuth टोकन रिकॉर्ड प्राधिकरण के दौरान चयनित संसाधन से बंधा होता है। संरक्षित MCP एंडपॉइंट केवल सटीक कैनोनिकल संसाधन ${DORIS_OAUTH_BASE_URL}/mcp को स्वीकार करता है; प्राधिकरण सर्वर या किसी अन्य संसाधन के लिए जारी टोकन को प्रति-उपयोगकर्ता Doris पूल का उपयोग करने से पहले invalid_token चुनौती के साथ अस्वीकार कर दिया जाता है। क्लाइंट को उस कैनोनिकल resource को प्राधिकरण अनुरोध और प्राधिकरण-कोड टोकन अनुरोध दोनों में भेजना होगा। टोकन एंडपॉइंट RFC 8707 invalid_target लौटाता है यदि मान गायब है या प्राधिकरण कोड से बंधे संसाधन से बिल्कुल मेल नहीं खाता है।

न्यूनतम स्थानीय कॉन्फ़िगरेशन

निम्नलिखित उदाहरण एकल वर्कर पर स्थानीय विकास के लिए है:

TRANSPORT=http
WORKERS=1

DORIS_HOST=localhost
DORIS_PORT=9030
DORIS_USER=root
DORIS_PASSWORD=<service-account-password>
DORIS_DATABASE=information_schema

ENABLE_DORIS_OAUTH_AUTH=true
DORIS_OAUTH_BASE_URL=http://localhost:3000
ENABLE_OAUTH_AUTH=false

DORIS_OAUTH_DB_TOOLS_ENABLED=true
DORIS_OAUTH_DB_TOOL_ALLOWLIST=get_db_list,get_db_table_list,get_table_schema,get_table_comment,get_table_column_comments,get_table_indexes,get_catalog_list
DORIS_OAUTH_QUERY_TOOLS_ENABLED=true
DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true

# Optional: let Doris RBAC, not the legacy MCP SQL guard, decide DDL/DML.
ENABLE_SECURITY_CHECK=false

कॉन्फ़िगर किया गया सेवा Doris खाता अभी भी स्टार्टअप सत्यापन और गैर-Doris-OAuth संगतता पथों द्वारा आवश्यक है। Doris-समर्थित OAuth अनुरोध विफल-बंद हैं यदि प्रति-उपयोगकर्ता पूल गायब है और उन्हें सेवा/वैश्विक खाते पर वापस नहीं आना चाहिए।

Doris OAuth उपकरण पहुँच

DORIS_OAUTH_DB_TOOLS_ENABLED=true समीक्षित मेटाडेटा बकेट खोलता है। समीक्षित उपकरण हैं:

get_db_list
get_db_table_list
get_table_schema
get_table_comment
get_table_column_comments
get_table_indexes
get_catalog_list

सामान्य MCP OAuth प्रवाह के लिए, क्लाइंट को एक लंबी --scopes सूची पास करने की आवश्यकता नहीं है। यदि OAuth अनुरोध स्कोप छोड़ देता है, तो सर्वर कॉन्फ़िगर किया गया Doris OAuth क्षमता लिफाफा प्रदान करता है। MySQL-चैनल संचालन के लिए, Doris RBAC तय करता है कि लॉग-इन Doris उपयोगकर्ता वास्तव में मेटाडेटा पढ़ सकता है, SQL चला सकता है, या SQL की व्याख्या कर सकता है या नहीं।

DORIS_OAUTH_QUERY_TOOLS_ENABLED=true exec_query खोलता है। DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true get_sql_explain खोलता है। यदि ENABLE_SECURITY_CHECK=true, तो लीगेसी MCP SQL सुरक्षा परत Doris द्वारा देखे जाने से पहले भी कुछ SQL को अस्वीकार कर सकती है। ENABLE_SECURITY_CHECK=false सेट करें जब इच्छित नीति Doris RBAC को SQL/DDL/DML तय करने देना है।

Doris-समर्थित OAuth अभी भी इस चरण में prompts, ADBC, FE HTTP प्रोफ़ाइल/निगरानी, ऑडिट/गवर्नेंस, या प्रदर्शन विश्लेषिकी नहीं खोलता है जब तक कि उन पथों को प्रति-उपयोगकर्ता क्रेडेंशियल्स के माध्यम से अलग से रूट नहीं किया जाता है या एक स्पष्ट सेवा-खाता/व्यवस्थापक पदनाम नहीं दिया जाता है।

OAuth क्लाइंट पंजीकरण

पसंदीदा क्लाइंट-पंजीकरण क्रम है:

उपलब्ध होने पर ऑपरेटर द्वारा कॉन्फ़िगर किए गए क्लाइंट का उपयोग करें।
क्लाइंट आईडी मेटाडेटा दस्तावेज़ (CIMD) का उपयोग उसके HTTPS URL को client_id के रूप में भेजकर करें।
केवल संगतता फ़ॉलबैक के रूप में डायनेमिक क्लाइंट पंजीकरण (DCR) का उपयोग करें।

प्राधिकरण-सर्वर मेटाडेटा client_id_metadata_document_supported=true का विज्ञापन करता है। एक CIMD एक JSON ऑब्जेक्ट होना चाहिए जिसका client_id बिल्कुल अनुरोधित URL के बराबर हो और जिसके client_name और redirect_uris मान्य हों। यह सर्वर वर्तमान में token_endpoint_auth_method=none, प्राधिकरण-कोड प्लस वैकल्पिक रिफ्रेश-टोकन अनुदान, code प्रतिक्रिया प्रकार और सटीक रीडायरेक्ट URI मिलान के साथ सार्वजनिक CIMD क्लाइंट स्वीकार करता है। नेटिव क्लाइंट रिवर्स-डोमेन कस्टम स्कीम या लूपबैक HTTP URI का उपयोग कर सकते हैं; वेब क्लाइंट को गैर-लूपबैक HTTPS का उपयोग करना चाहिए।

CIMD पुनर्प्राप्ति विफल-बंद है। URL को HTTPS का उपयोग करना चाहिए, एक पथ होना चाहिए, और कोई userinfo, फ़्रैगमेंट, बैकस्लैश या डॉट पथ खंड नहीं होना चाहिए। रिज़ॉल्वर विशेष-उपयोग गंतव्य पतों को अस्वीकार करता है, अनुरोध के लिए मान्य DNS परिणामों को पिन करता है, रीडायरेक्ट का पालन नहीं करता है, JSON की आवश्यकता होती है, प्रतिक्रिया को डिफ़ॉल्ट रूप से 5 KiB तक सीमित करता है, एम्बेडेड साझा रहस्यों या निजी कुंजी सामग्री को अस्वीकार करता है, और HTTP कैश नियंत्रणों के अनुसार केवल मान्य दस्तावेज़ों को कैश करता है। लूपबैक मेटाडेटा होस्ट केवल तभी स्वीकार किए जाते हैं जब Doris OAuth जारीकर्ता स्वयं एक लूपबैक विकास जारीकर्ता हो। लॉगिन पृष्ठ क्लाइंट और रीडायरेक्ट होस्टनाम प्रदर्शित करता है और लोकलहोस्ट रीडायरेक्ट से पहले चेतावनी देता है।

CIMD नियंत्रणों को DORIS_OAUTH_CIMD_FETCH_TIMEOUT_SECONDS, DORIS_OAUTH_CIMD_MAX_DOCUMENT_BYTES, DORIS_OAUTH_CIMD_DEFAULT_CACHE_SECONDS, DORIS_OAUTH_CIMD_MAX_CACHE_SECONDS, और DORIS_OAUTH_CIMD_MAX_CLIENTS के साथ समायोजित किया जा सकता है।

DCR पुराने क्लाइंट के लिए उपलब्ध रहता है जब DORIS_OAUTH_DYNAMIC_CLIENT_REGISTRATION_MODE इसकी अनुमति देता है। DCR अनुरोधों में application_type को native या web के रूप में शामिल करना होगा; समान प्रकार-विशिष्ट और सटीक रीडायरेक्ट URI नियम लागू होते हैं। उत्पादन DCR को अभी भी ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true की आवश्यकता होती है।

प्राधिकरण सफलता और रीडायरेक्ट करने योग्य त्रुटि प्रतिक्रियाओं में RFC 9207 iss पैरामीटर में सटीक प्राधिकरण-सर्वर जारीकर्ता शामिल होता है। खोज authorization_response_iss_parameter_supported=true का विज्ञापन करती है; क्लाइंट को प्रतिक्रिया स्वीकार करने से पहले लौटाए गए मान की तुलना बिना URI सामान्यीकरण के खोजे गए जारीकर्ता से करनी चाहिए।

वर्तमान परिचालन सीमाएँ

Doris-समर्थित OAuth वर्तमान में एकल-प्रक्रिया और एकल-कार्यकर्ता है:

WORKERS=1 आवश्यक है। WORKERS=0 CPU गणना तक विस्तारित होता है और जब Doris-समर्थित OAuth सक्षम होता है तो विफल हो जाता है।
OAuth क्लाइंट, प्राधिकरण लेन-देन, प्राधिकरण कोड, एक्सेस टोकन, रिफ्रेश टोकन और DCR क्लाइंट केवल मेमोरी और प्रक्रिया-स्थानीय होते हैं।
प्रति-उपयोगकर्ता Doris कनेक्शन पूल प्रक्रिया-स्थानीय होते हैं।
प्रक्रिया पुनरारंभ होने पर उपयोगकर्ताओं को फिर से साइन इन करना होगा।
टोकन और पूल कार्यकर्ताओं, प्रक्रियाओं या नोड्स में साझा नहीं किए जाते हैं।
Doris-समर्थित OAuth के लिए स्टेटलेस क्षैतिज स्केलिंग और बहु-नोड परिनियोजन अभी तक समर्थित नहीं है।

यदि कोई एक्सेस टोकन अन्यथा मान्य है लेकिन उसका Doris उपयोगकर्ता पूल समाप्त हो गया है, तो अनुरोध लॉगिन आवश्यक / DORIS_OAUTH_POOL_MISSING के साथ विफल हो जाता है। सर्वर स्वचालित पूल पुनर्निर्माण के लिए कच्चे Doris पासवर्ड संग्रहीत नहीं करता है।

उत्पादन सख्तीकरण

उत्पादन परिनियोजन के लिए:

किसी भी गैर-लूपबैक पते के लिए HTTPS DORIS_OAUTH_BASE_URL का उपयोग करें।
DORIS_OAUTH_ALLOW_INSECURE_HTTP=false रखें; गैर-लूपबैक http:// अस्वीकार कर दिया जाता है जब तक कि विकास के लिए स्पष्ट रूप से ओवरराइड न किया गया हो।
DORIS_OAUTH_TRUST_PROXY_HEADERS को केवल एक नियंत्रित रिवर्स प्रॉक्सी के पीछे सक्षम करें और DORIS_OAUTH_TRUSTED_PROXY_CIDRS सेट करें।
लॉगिन, प्राधिकृत करें, टोकन, रिफ्रेश, निरस्त करें और DCR दर सीमाएं सक्षम रखें।
Doris RBAC का उपयोग अंतिम डेटा प्राधिकरण सीमा के रूप में करें और Doris उपयोगकर्ताओं को केवल वही डेटा प्रदान करें जिसका उन्हें निरीक्षण करना चाहिए।
Doris पासवर्ड, प्राधिकरण हेडर, एक्सेस टोकन, रिफ्रेश टोकन, प्राधिकरण कोड, PKCE सत्यापनकर्ता, या क्लाइंट सीक्रेट लॉग न करें।
doa_ उपसर्ग को Doris-समर्थित OAuth एक्सेस टोकन के लिए आरक्षित मानें; स्थिर टोकन और JWT बियरर मानों को इसका उपयोग नहीं करना चाहिए।
पूर्व-कॉन्फ़िगर किए गए क्लाइंट या क्लाइंट ID मेटाडेटा दस्तावेज़ों को प्राथमिकता दें। DCR को एक संगतता फ़ॉलबैक के रूप में रखें; उत्पादन DCR के लिए ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true आवश्यक है।

टोकन-बाउंड डेटाबेस कॉन्फ़िगरेशन (v0.6.0 में नया)

प्रबंधित टोकन निर्माण बियरर मान एक बार लौटाता है और केवल उसका डाइजेस्ट tokens.json में लिखता है। मैन्युअल प्रावधान के लिए, रिपॉजिटरी के बाहर बियरर मान और डाइजेस्ट उत्पन्न करें, बियरर मान को क्लाइंट सीक्रेट स्टोर में संग्रहीत करें, और केवल डाइजेस्ट को सर्वर फ़ाइल में रखें:

python - <<'PY'
import hashlib
import secrets

token = secrets.token_urlsafe(32)
print(f"Bearer token (store once): {token}")
print(f"token_digest: sha256:{hashlib.sha256(token.encode()).hexdigest()}")
PY

v2 फ़ाइल प्रारूप उत्पन्न डाइजेस्ट का उपयोग करता है:

{
  "version": "2.0",
  "tokens": [
    {
      "token_id": "customer-a-token",
      "token_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "created_at": "2026-07-29T00:00:00Z",
      "expires_at": null,
      "last_used": null,
      "description": "Customer A dedicated database access",
      "is_active": true,
      "database_config": {
        "host": "customer-a-db.example.com",
        "port": 9030,
        "user": "customer_a_user",
        "password": "secure_password",
        "database": "customer_a_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    }
  ]
}

सभी-शून्य उदाहरण को उत्पन्न डाइजेस्ट से बदलें; यह जानबूझकर एक प्रयोग करने योग्य क्रेडेंशियल नहीं है। प्रबंधित लेखन परमाणु होते हैं और फ़ाइल मोड को 0600 पर सेट करते हैं। token प्लेनटेक्स्ट वाली संस्करण 1 फ़ाइलें माइग्रेशन के लिए एक बार स्वीकार की जाती हैं, फिर तुरंत संस्करण 2 डाइजेस्ट-केवल रिकॉर्ड से बदल दी जाती हैं। सर्वर token_digest से मूल बियरर मान पुनर्प्राप्त या प्रदर्शित नहीं कर सकता है।

हॉट रीलोड कॉन्फ़िगरेशन अपडेट (v0.6.0 में नया)

सिस्टम स्वचालित रूप से कॉन्फ़िगरेशन परिवर्तनों का पता लगाता है और उन्हें लागू करता है:

स्वचालित पहचान: हर 10 सेकंड में फ़ाइल संशोधन निगरानी
तत्काल सत्यापन: नए टोकन के लिए तत्काल डेटाबेस कॉन्फ़िगरेशन सत्यापन
शून्य डाउनटाइम: सेवा रुकावट के बिना कॉन्फ़िगरेशन अपडेट
रोलबैक सुरक्षा: कॉन्फ़िगरेशन त्रुटियों पर स्वचालित रोलबैक
ऑडिट ट्रेल: कॉन्फ़िगरेशन परिवर्तनों की पूर्ण लॉगिंग

टोकन प्रमाणीकरण उदाहरण

# Client authentication with token
auth_info = {
    "type": "token",
    "token": "your_jwt_token",
    "session_id": "unique_session_id"
}

मूल प्रमाणीकरण उदाहरण

# Client authentication with username/password
auth_info = {
    "type": "basic",
    "username": "analyst",
    "password": "secure_password",
    "session_id": "unique_session_id"
}

प्राधिकरण और सुरक्षा स्तर

सिस्टम पदानुक्रमित अभिगम नियंत्रण के साथ चार सुरक्षा स्तरों का समर्थन करता है:

सुरक्षा स्तर	पहुंच का दायरा	विशिष्ट उपयोग के मामले
सार्वजनिक	अप्रतिबंधित पहुंच	सार्वजनिक रिपोर्ट, सामान्य आंकड़े
आंतरिक	कंपनी के कर्मचारी	आंतरिक डैशबोर्ड, व्यावसायिक मीट्रिक
गोपनीय	अधिकृत कार्मिक	ग्राहक डेटा, वित्तीय रिपोर्ट
गुप्त	वरिष्ठ प्रबंधन	रणनीतिक डेटा, संवेदनशील विश्लेषण

भूमिका विन्यास

बाहरी OAuth भूमिका मैपिंग पर्यावरण चर के माध्यम से कॉन्फ़िगर की जाती है:

# Roles supplied when the provider returns no role claim
OAUTH_DEFAULT_ROLES=oauth_user

# Fallbacks for users whose roles do not occur in the JSON mappings
OAUTH_DEFAULT_SECURITY_LEVEL=internal
OAUTH_DEFAULT_PERMISSIONS=read_data

# Exact domains only. Domain elevation is applied only when the provider
# returns email_verified=true.
OAUTH_TRUSTED_DOMAINS=example.com,internal.example.com
OAUTH_TRUSTED_DOMAIN_SECURITY_LEVEL=confidential

# Each JSON value replaces the complete built-in mapping.
OAUTH_ROLE_SECURITY_LEVELS_JSON={"analyst":"internal","executive":"secret"}
OAUTH_ROLE_PERMISSIONS_JSON={"analyst":["read_data","query_database"],"executive":["read_data","query_database","admin"]}

भूमिका नाम और विश्वसनीय डोमेन केस-असंवेदनशील रूप से मिलान किए जाते हैं। समर्थित सुरक्षा स्तर public, internal, confidential, और secret हैं। एक स्पष्ट खाली अनुमति सरणी उस भूमिका के लिए एप्लिकेशन अनुमतियों से इनकार करती है; एक खाली OAUTH_DEFAULT_PERMISSIONS मान अज्ञात भूमिकाओं को बंद कर देता है।

अंतर्निहित भूमिका डिफ़ॉल्ट admin, administrator, data_admin, super_admin, data_analyst, developer, manager, viewer, user, और oauth_user के लिए पिछले व्यवहार को संरक्षित करते हैं। डिफ़ॉल्ट रूप से कोई ईमेल डोमेन विश्वसनीय नहीं है।

ये सेटिंग्स MCP एप्लिकेशन अनुमतियों और सुरक्षा वर्गीकरण को नियंत्रित करती हैं। डेटाबेस, तालिका, स्तंभ और पंक्ति पहुंच अभी भी Doris उपयोगकर्ताओं, भूमिकाओं, अनुदानों, दृश्यों और पंक्ति नीतियों के साथ लागू की जानी चाहिए; OAuth मैपिंग Doris प्राधिकरण को बायपास नहीं करती है। एंड-टू-एंड कॉलम और पंक्ति नीति उदाहरण, MCP पहचान-रूटिंग विकल्पों और सत्यापन चेकलिस्ट के लिए Doris सूक्ष्म-अभिगम नियंत्रण गाइड देखें।

SQL सुरक्षा सत्यापन

सिस्टम सुरक्षा जोखिमों के लिए SQL क्वेरीज़ को स्वचालित रूप से मान्य करता है:

अवरुद्ध संचालन

पर्यावरण चर का उपयोग करके अवरुद्ध SQL संचालन कॉन्फ़िगर करें (v0.4.2 में नया):

# Enable/disable SQL security check (New in v0.4.2)
ENABLE_SECURITY_CHECK=true

# Customize blocked keywords via environment variable (New in v0.4.2)
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

# Maximum query complexity score
MAX_QUERY_COMPLEXITY=100

डिफ़ॉल्ट अवरुद्ध कीवर्ड (v0.4.2 में एकीकृत):

DDL संचालन: DROP, CREATE, ALTER, TRUNCATE
DML संचालन: DELETE, INSERT, UPDATE
DCL संचालन: GRANT, REVOKE
सिस्टम संचालन: EXEC, EXECUTE, SHUTDOWN, KILL

SQL इंजेक्शन सुरक्षा

सिस्टम स्वचालित रूप से पता लगाता है और ब्लॉक करता है:

यूनियन-आधारित इंजेक्शन: UNION SELECT हमले
बूलियन-आधारित इंजेक्शन: OR 1=1 पैटर्न
समय-आधारित इंजेक्शन: SLEEP(), WAITFOR फ़ंक्शन
टिप्पणी इंजेक्शन: --, /**/ पैटर्न
स्टैक्ड क्वेरीज़: ; द्वारा अलग किए गए कई कथन

उदाहरण सुरक्षा सत्यापन

# This query would be blocked
dangerous_sql = "SELECT * FROM users WHERE id = 1; DROP TABLE users;"

# This query would be allowed
safe_sql = "SELECT name, email FROM users WHERE department = 'sales'"

डेटा मास्किंग कॉन्फ़िगरेशन

संवेदनशील जानकारी के लिए स्वचालित डेटा मास्किंग कॉन्फ़िगर करें:

अंतर्निहित मास्किंग नियम

# Default masking rules
masking_rules = [
    {
        "column_pattern": r".*phone.*|.*mobile.*",
        "algorithm": "phone_mask",
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 3,
            "keep_suffix": 4
        },
        "security_level": "internal"
    },
    {
        "column_pattern": r".*email.*", 
        "algorithm": "email_mask",
        "parameters": {"mask_char": "*"},
        "security_level": "internal"
    },
    {
        "column_pattern": r".*id_card.*|.*identity.*",
        "algorithm": "id_mask", 
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 6,
            "keep_suffix": 4
        },
        "security_level": "confidential"
    }
]

मास्किंग एल्गोरिदम

एल्गोरिदम	विवरण	उदाहरण
`phone_mask`	फ़ोन नंबर मास्क करता है	`138****5678`
`email_mask`	ईमेल पते मास्क करता है	`j***n@example.com`
`id_mask`	आईडी कार्ड नंबर मास्क करता है	`110101****1234`
`name_mask`	व्यक्तिगत नाम मास्क करता है	`张*明`
`partial_mask`	अनुपात के साथ आंशिक मास्किंग	`abc***xyz`

कस्टम मास्किंग नियम

अपने कॉन्फ़िगरेशन में कस्टम मास्किंग नियम जोड़ें:

# Custom masking rule
custom_rule = {
    "column_pattern": r".*salary.*|.*income.*",
    "algorithm": "partial_mask",
    "parameters": {
        "mask_char": "*",
        "mask_ratio": 0.6
    },
    "security_level": "confidential"
}

सुरक्षा कॉन्फ़िगरेशन उदाहरण

पर्यावरण चर

# Generate this outside source control, then inject it into the process.
export TOKEN_SECURITY_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_TOKEN_AUTH=true
ENABLE_MASKING=true
MAX_RESULT_ROWS=10000
BLOCKED_SQL_OPERATIONS=DROP,DELETE,TRUNCATE,ALTER
MAX_QUERY_COMPLEXITY=100
ENABLE_AUDIT=true

संवेदनशील तालिकाएँ कॉन्फ़िगरेशन

# Configure sensitive tables with security levels
sensitive_tables = {
    "user_profiles": "confidential",
    "payment_records": "secret", 
    "employee_salaries": "secret",
    "customer_data": "confidential",
    "public_reports": "public"
}

सुरक्षा सर्वोत्तम अभ्यास

🔑 मजबूत प्रमाणीकरण: उचित समाप्ति के साथ JWT टोकन का उपयोग करें
🎯 न्यूनतम विशेषाधिकार का सिद्धांत: न्यूनतम आवश्यक अनुमतियाँ प्रदान करें
🔍 नियमित ऑडिटिंग: सुरक्षा निगरानी के लिए ऑडिट लॉगिंग सक्षम करें
🛡️ इनपुट सत्यापन: सभी SQL क्वेरीज़ स्वचालित रूप से मान्य की जाती हैं
🎭 डेटा वर्गीकरण: सुरक्षा स्तरों के साथ डेटा को उचित रूप से वर्गीकृत करें
🔄 नियमित अपडेट: सुरक्षा नियमों और कॉन्फ़िगरेशन को अपडेट रखें
Doris-समर्थित OAuth सख्तीकरण: HTTPS का उपयोग करें, इस मोड में बाहरी OAuth अक्षम रखें, WORKERS=1 रखें, MySQL-चैनल डेटा एक्सेस के लिए Doris RBAC पर भरोसा करें, और केवल उन्हीं संचालनों को उजागर करें जो लॉग-इन Doris उपयोगकर्ता के क्रेडेंशियल्स का उपयोग करने के लिए कॉन्फ़िगर और सत्यापित हैं।

सुरक्षा निगरानी

सिस्टम व्यापक सुरक्षा निगरानी प्रदान करता है:

# Security audit log example
{
    "timestamp": "2024-01-15T10:30:00Z",
    "user_id": "analyst_user",
    "action": "query_execution", 
    "resource": "customer_data",
    "result": "blocked",
    "reason": "insufficient_permissions",
    "risk_level": "medium"
}

⚠️ महत्वपूर्ण: उत्पादन में तैनात करने से पहले हमेशा विकास परिवेश में सुरक्षा कॉन्फ़िगरेशन का परीक्षण करें। अपने संगठन की आवश्यकताओं के आधार पर नियमित रूप से सुरक्षा नीतियों की समीक्षा करें और उन्हें अपडेट करें।

Cursor के साथ कनेक्ट करना

आप Stdio मोड (अनुशंसित) या स्ट्रीमेबल HTTP मोड का उपयोग करके Cursor को इस MCP सर्वर से कनेक्ट कर सकते हैं।

Stdio मोड

Stdio मोड Cursor को सर्वर प्रक्रिया को सीधे प्रबंधित करने की अनुमति देता है। कॉन्फ़िगरेशन Cursor की MCP सर्वर सेटिंग्स फ़ाइल (आमतौर पर ~/.cursor/mcp.json या समान) के भीतर किया जाता है।

विधि 1: PyPI इंस्टॉलेशन का उपयोग करना (अनुशंसित)

PyPI से पैकेज इंस्टॉल करें और Cursor को इसका उपयोग करने के लिए कॉन्फ़िगर करें:

pip install doris-mcp-server

Cursor कॉन्फ़िगर करें: अपने Cursor MCP कॉन्फ़िगरेशन में निम्नलिखित जैसी प्रविष्टि जोड़ें:

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

विधि 2: uv का उपयोग करना (विकास)

यदि आपके पास uv स्थापित है और आप स्रोत से चलाना चाहते हैं:

uv run --project /path/to/doris-mcp-server doris-mcp-server

नोट: /path/to/doris-mcp-server को अपनी परियोजना निर्देशिका के वास्तविक निरपेक्ष पथ से बदलें।

{
  "mcpServers": {
    "doris-stdio": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/your/doris-mcp-server", "doris-mcp-server"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

स्ट्रीमेबल HTTP मोड

स्ट्रीमेबल HTTP मोड के लिए आपको पहले MCP सर्वर को स्वतंत्र रूप से चलाना होगा, और फिर Cursor को इससे कनेक्ट करने के लिए कॉन्फ़िगर करना होगा।

.env कॉन्फ़िगर करें: सुनिश्चित करें कि आपके डेटाबेस क्रेडेंशियल और कोई अन्य आवश्यक सेटिंग्स परियोजना निर्देशिका के भीतर .env फ़ाइल में सही ढंग से कॉन्फ़िगर की गई हैं।
सर्वर प्रारंभ करें: परियोजना की रूट निर्देशिका में अपने टर्मिनल से सर्वर चलाएँ:
```
./start_server.sh
```
यह स्क्रिप्ट .env फ़ाइल पढ़ती है और डिफ़ॉल्ट रूप से 127.0.0.1 पर स्ट्रीमेबल HTTP सर्वर प्रारंभ करती है। एक गैर-लूपबैक श्रोता के लिए कम से कम एक प्रमाणीकरण विधि की आवश्यकता होती है।
Cursor कॉन्फ़िगर करें: चल रहे सर्वर के स्ट्रीमेबल HTTP समापन बिंदु की ओर इशारा करते हुए, अपने Cursor MCP कॉन्फ़िगरेशन में निम्नलिखित जैसी प्रविष्टि जोड़ें:
```
{
  "mcpServers": {
    "doris-http": {
       "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```
नोट: यदि आपका सर्वर किसी भिन्न पते पर चलता है तो होस्ट/पोर्ट समायोजित करें। /mcp समापन बिंदु एकीकृत स्ट्रीमेबल HTTP इंटरफ़ेस है।

Cursor में किसी भी मोड को कॉन्फ़िगर करने के बाद, आपको सर्वर (जैसे, doris-stdio या doris-http) का चयन करने और इसके टूल का उपयोग करने में सक्षम होना चाहिए।

Kiro के साथ कनेक्ट करना

या अपनी Kiro MCP कॉन्फ़िग फ़ाइल में निम्नलिखित जोड़ें (वैश्विक के लिए ~/.kiro/settings/mcp.json, या परियोजना-स्कोप्ड के लिए .kiro/settings/mcp.json)। अधिक विवरण के लिए Kiro MCP दस्तावेज़ीकरण देखें।

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

निर्देशिका संरचना

doris-mcp-server/
├── doris_mcp_server/           # Main server package
│   ├── main.py                 # Main entry point and FastAPI app
│   ├── multiworker_app.py      # Multi-worker application module (New in v0.6.0)
│   ├── auth/                   # Authentication modules (New in v0.6.0)
│   │   ├── token_manager.py    # Enterprise token management with hot reload
│   │   ├── jwt_manager.py      # JWT authentication provider
│   │   ├── oauth_provider.py   # OAuth authentication provider  
│   │   ├── oauth_handlers.py   # OAuth HTTP endpoint handlers
│   │   ├── token_handlers.py   # Token management HTTP endpoints
│   │   ├── auth_middleware.py  # Authentication middleware
│   │   └── __init__.py
│   ├── tools/                  # MCP tools implementation
│   │   ├── tools_manager.py    # Centralized tools management and registration
│   │   ├── resources_manager.py # Resource management and metadata exposure
│   │   ├── prompts_manager.py  # Intelligent prompt templates for data analysis
│   │   └── __init__.py
│   ├── utils/                  # Core utility modules
│   │   ├── config.py           # Configuration management with validation
│   │   ├── db.py               # Enhanced database connection management with token binding (Enhanced in v0.6.0)
│   │   ├── query_executor.py   # High-performance SQL execution with caching
│   │   ├── security.py         # Advanced security management and authentication (Enhanced in v0.6.0)
│   │   ├── schema_extractor.py # Metadata extraction with catalog federation
│   │   ├── analysis_tools.py   # Data analysis and performance monitoring
│   │   ├── data_governance_tools.py  # Data lineage and freshness monitoring (v0.5.0)
│   │   ├── data_quality_tools.py     # Comprehensive data quality analysis (v0.5.0)
│   │   ├── data_exploration_tools.py # Advanced statistical analysis (v0.5.0)
│   │   ├── security_analytics_tools.py # Access pattern analysis (v0.5.0)
│   │   ├── dependency_analysis_tools.py # Impact analysis and dependency mapping (v0.5.0)
│   │   ├── performance_analytics_tools.py # Query optimization and capacity planning (v0.5.0)
│   │   ├── adbc_query_tools.py       # High-performance Arrow Flight SQL operations (v0.5.0)
│   │   ├── logger.py           # Logging configuration
│   │   └── __init__.py
│   └── __init__.py
├── doris_mcp_client/           # MCP client implementation
│   ├── client.py               # Unified MCP client for testing and integration
│   ├── README.md               # Client documentation
│   └── __init__.py
├── logs/                       # Log files directory
├── tokens.json                 # Token configuration file (New in v0.6.0)
├── README.md                   # This documentation
├── CHANGELOG.md                 # Tagged release history and unreleased changes
├── .env.example                # Environment variables template
├── requirements.txt            # Runtime-only Python dependencies
├── requirements-dev.txt        # Runtime plus test and quality dependencies
├── pyproject.toml              # Project configuration and entry points
├── uv.lock                     # UV package manager lock file
├── generate_requirements.py    # Requirements generation script
├── start_server.sh             # Server startup script
└── restart_server.sh           # Server restart script

नए टूल विकसित करना

यह खंड केंद्रीकृत टूल प्रबंधन के साथ एकीकृत मॉड्यूलर आर्किटेक्चर पर आधारित, Doris MCP सर्वर में नए MCP टूल जोड़ने की प्रक्रिया की रूपरेखा तैयार करता है।

मौजूदा व्यावसायिक API को इस रिपॉजिटरी में बनाने की आवश्यकता नहीं है। इसके बजाय उन्हें स्पष्ट रूप से स्थापित, अनुमत-सूचीबद्ध कस्टम टूल प्रदाताओं के रूप में पैकेज करें। कस्टम टूल प्रदाता गाइड प्रवेश बिंदु अनुबंध, जीवनचक्र, प्रक्रिया-स्थानीय QPS सीमाएं, प्रमाणीकरण सीमा, FastGPT एकीकरण और उत्पादन सुरक्षा चेकलिस्ट को परिभाषित करता है।

1. मौजूदा उपयोगिता मॉड्यूल का लाभ उठाएं

सर्वर सामान्य डेटाबेस संचालन के लिए व्यापक उपयोगिता मॉड्यूल प्रदान करता है:

doris_mcp_server/utils/db.py: कनेक्शन पूलिंग और स्वास्थ्य निगरानी के साथ डेटाबेस कनेक्शन प्रबंधन।
doris_mcp_server/utils/query_executor.py: उन्नत कैशिंग, अनुकूलन और प्रदर्शन निगरानी के साथ उच्च-प्रदर्शन SQL निष्पादन।
doris_mcp_server/utils/schema_extractor.py: पूर्ण कैटलॉग फेडरेशन समर्थन के साथ मेटाडेटा निष्कर्षण।
doris_mcp_server/utils/security.py: व्यापक सुरक्षा प्रबंधन, SQL सत्यापन और डेटा मास्किंग।
doris_mcp_server/utils/analysis_tools.py: उन्नत डेटा विश्लेषण और सांख्यिकीय उपकरण।
doris_mcp_server/utils/config.py: सत्यापन के साथ कॉन्फ़िगरेशन प्रबंधन।
doris_mcp_server/utils/data_governance_tools.py: डेटा वंशावली ट्रैकिंग और ताज़गी निगरानी (v0.5.0 में नया)।
doris_mcp_server/utils/data_quality_tools.py: व्यापक डेटा गुणवत्ता विश्लेषण ढांचा (v0.5.0 में नया)।
doris_mcp_server/utils/adbc_query_tools.py: उच्च-प्रदर्शन एरो फ्लाइट SQL संचालन (v0.5.0 में नया)।

2. टूल लॉजिक लागू करें

doris_mcp_server/tools/tools_manager.py में DorisToolsManager में एक निजी हैंडलर जोड़ें। हैंडलर नाम _<tool_name>_tool का पालन करते हैं; रजिस्ट्री इस नाम को हल करती है और मान्य करती है कि प्रबंधक निर्माण के दौरान हैंडलर मौजूद है।

उदाहरण: एक नया विश्लेषण टूल जोड़ना:

# In doris_mcp_server/tools/tools_manager.py

async def _your_new_analysis_tool(
    self,
    arguments: dict[str, Any],
) -> dict[str, Any]:
    """
    Your new analysis tool implementation
    
    Args:
        arguments: Tool arguments from MCP client
        
    Returns:
        JSON-serializable tool result
    """
    try:
        # Use existing utilities
        result = await self.query_executor.execute_sql_for_mcp(
            sql="SELECT COUNT(*) FROM your_table",
            max_rows=arguments.get("max_rows", 100)
        )
        
        return result
        
    except Exception as e:
        logger.error(f"Tool execution failed: {str(e)}", exc_info=True)
        return {"success": False, "error": "Analysis failed"}

3. रजिस्ट्री परिभाषा जोड़ें

doris_mcp_server/tools/tool_catalog.py::build_tool_registry में एक Tool स्कीमा जोड़ें, फिर इसकी नीति को एक बार doris_mcp_server/tools/tool_registry.py में वर्गीकृत करें। डेकोरेटर रैपर या if/elif डिस्पैच शाखा न जोड़ें:

# In doris_mcp_server/tools/tool_catalog.py

Tool(
    name="your_new_analysis_tool",
    description="Description of your new analysis tool",
    input_schema={
        "type": "object",
        "properties": {
            "parameter1": {
                "type": "string",
                "description": "Description of parameter1"
            },
            "parameter2": {
                "type": "integer", 
                "description": "Description of parameter2",
                "default": 100
            }
        },
        "required": ["parameter1"],
    },
)

कस्टम प्रदाता आंतरिक क्षमता स्रोत हैं और अतिरिक्त शीर्ष-स्तरीय MCP उपकरण नहीं बनाते हैं। प्रत्येक प्रदाता क्षमता को एक समर्थन अनुबंध, प्राधिकरण नीति, इनपुट/आउटपुट स्कीमा और एक नियतात्मक हैंडलर बाइंडिंग के साथ एक औपचारिक डोमेन चाइल्ड में एकीकृत करें। परीक्षण सूट सार्वजनिक कैटलॉग विचलन को अस्वीकार करता है।

4. उन्नत सुविधाएँ

अधिक जटिल उपकरणों के लिए, आप व्यापक ढाँचे का लाभ उठा सकते हैं:

उन्नत कैशिंग: बेहतर प्रदर्शन के लिए क्वेरी निष्पादक की अंतर्निहित कैशिंग का उपयोग करें
एंटरप्राइज़ सुरक्षा: सुरक्षा प्रबंधक के माध्यम से व्यापक SQL सत्यापन और डेटा मास्किंग लागू करें
बुद्धिमान प्रॉम्प्ट: उन्नत क्वेरी निर्माण के लिए प्रॉम्प्ट प्रबंधक का उपयोग करें
संसाधन प्रबंधन: संसाधन प्रबंधक के माध्यम से मेटाडेटा उजागर करें
प्रदर्शन निगरानी: निगरानी क्षमताओं के लिए विश्लेषण उपकरणों के साथ एकीकृत करें

5. परीक्षण

शामिल MCP क्लाइंट का उपयोग करके अपने नए उपकरण का परीक्षण करें:

# Using doris_mcp_client/client.py
from doris_mcp_client.client import DorisUnifiedMCPClient

async def test_new_tool():
    client = DorisUnifiedMCPClient()
    result = await client.call_tool("your_new_analysis_tool", {
        "parameter1": "test_value",
        "parameter2": 50
    })
    print(result)

रिलीज़ परीक्षण गेट को इसके साथ चलाएँ:

uv run pytest -q -W error
uv run coverage json -o coverage.json
uv run python test/deployment/check_coverage_domains.py coverage.json

परीक्षण सूट रिपॉजिटरी में कम से कम 55% कवरेज लागू करता है। उत्पन्न कवरेज रिपोर्ट को प्रोटोकॉल, प्रमाणीकरण और कोर मैनेजर डोमेन के लिए 80% की न्यूनतम सीमा पर भी जाँचा जाता है, ताकि उच्च-जोखिम वाला रनटाइम कोड असंबंधित कवरेज से छिप न सके।

MCP क्लाइंट

परियोजना में परीक्षण और एकीकरण उद्देश्यों के लिए एक एकीकृत MCP क्लाइंट (doris_mcp_client/) शामिल है। क्लाइंट कई कनेक्शन मोड का समर्थन करता है और MCP सर्वर के साथ इंटरैक्ट करने के लिए एक सुविधाजनक इंटरफ़ेस प्रदान करता है।

विस्तृत क्लाइंट दस्तावेज़ीकरण के लिए, doris_mcp_client/README.md देखें।

योगदान

मुद्दों या पुल अनुरोधों के माध्यम से योगदान का स्वागत है।

लाइसेंस

यह परियोजना Apache 2.0 लाइसेंस के तहत लाइसेंस प्राप्त है। विवरण के लिए LICENSE फ़ाइल देखें।

सामान्य प्रश्न

प्रश्न: Qwen3-32b और अन्य छोटे पैरामीटर मॉडल उपकरणों को कॉल करते समय हमेशा विफल क्यों होते हैं?

उत्तर: यह एक सामान्य समस्या है। मुख्य कारण यह है कि इन मॉडलों को MCP उपकरणों का सही ढंग से उपयोग करने के लिए अधिक स्पष्ट मार्गदर्शन की आवश्यकता होती है। मॉडल के लिए निम्नलिखित निर्देश प्रॉम्प्ट जोड़ने की अनुशंसा की जाती है:

चीनी संस्करण：

<instruction>
尽可能使用MCP工具完成任务，仔细阅读每个工具的注解、方法名、参数说明等内容。请按照以下步骤操作：

1. 仔细分析用户的问题，从已有的Tools列表中匹配最合适的工具。
2. 确保工具名称、方法名和参数完全按照工具注释中的定义使用，不要自行创造工具名称或参数。
3. 传入参数时，严格遵循工具注释中规定的参数格式和要求。
4. 调用工具时，根据需要直接调用工具，但参数请求参考以下请求格式：{"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. 输出结果时，不要包含任何XML标签，仅返回纯文本内容。

<input>
用户问题：user_query
</input>

<output>
返回工具调用结果或最终答案，以及对结果的分析。
</output>
</instruction>

अंग्रेजी संस्करण：

<instruction>
Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps:

1. Carefully analyze the user's question and match the most appropriate tool from the existing Tools list.
2. Ensure tool names, method names, and parameters are used exactly as defined in the tool annotations. Do not create tool names or parameters on your own.
3. When passing parameters, strictly follow the parameter format and requirements specified in the tool annotations.
4. When calling tools, call them directly as needed, but refer to the following request format for parameters: {"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. When outputting results, do not include any XML tags, return plain text content only.

<input>
User question: user_query
</input>

<output>
Return tool call results or final answer, along with analysis of the results.
</output>
</instruction>

यदि आपके पास लौटाए गए परिणामों के लिए और आवश्यकताएँ हैं, तो आप <output> टैग में विशिष्ट आवश्यकताओं का वर्णन कर सकते हैं।

प्रश्न: विभिन्न डेटाबेस कनेक्शन कैसे कॉन्फ़िगर करें?

उत्तर: आप डेटाबेस कनेक्शन को कई तरीकों से कॉन्फ़िगर कर सकते हैं:

पर्यावरण चर (अनुशंसित):

export DORIS_HOST="your_doris_host"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

कमांड लाइन तर्क:

doris-mcp-server --db-host your_host --db-port 9030 --db-user root --db-password your_password

कॉन्फ़िगरेशन फ़ाइल: .env फ़ाइल में संबंधित कॉन्फ़िगरेशन आइटम संशोधित करें।

प्रश्न: निगरानी उपकरणों के लिए BE नोड्स कैसे कॉन्फ़िगर करें?

उत्तर: जब कोई प्रॉक्सी, टनल या विभाजित नेटवर्क उन्हें विभिन्न पतों पर उजागर करता है, तो SQL, FE HTTP और BE HTTP एंडपॉइंट्स को स्वतंत्र रूप से कॉन्फ़िगर करें:

# SQL/MySQL protocol endpoint
DORIS_HOST=sql-gateway.internal
DORIS_HOSTS=sql-gateway.internal,fe-2.internal,fe-3.internal
DORIS_PORT=9030

# FE HTTP endpoint; omit DORIS_FE_HTTP_HOST to reuse DORIS_HOST
DORIS_FE_HTTP_HOST=fe-http-proxy.internal
DORIS_FE_HTTP_HOSTS=fe-http-proxy.internal,fe-2.internal,fe-3.internal
DORIS_FE_HTTP_PORT=8030

# Explicit BE HTTP allowlist
DORIS_BE_HOSTS=10.1.1.100,10.1.1.101,10.1.1.102
DORIS_BE_WEBSERVER_PORT=8040

BE HTTP एंडपॉइंट्स को कभी भी SHOW BACKENDS से अनुमानित नहीं किया जाता है: SQL मेटाडेटा एक आउटबाउंड HTTP अनुमति सूची नहीं है। यदि DORIS_BE_HOSTS खाली है, तो BE HTTP मेट्रिक्स अक्षम हैं। DORIS_FE_HTTP_HOST केवल पश्चगामी संगतता के लिए DORIS_HOST पर वापस आता है; प्रत्येक FE निगरानी, प्रोफ़ाइल, ट्रेस और तालिका-आकार HTTP अनुरोध के लिए एक स्पष्ट मान का उपयोग किया जाता है। FE और BE अनुरोध केवल कॉन्फ़िगर किए गए होस्ट और पोर्ट का उपयोग करते हैं, प्रत्येक अनुरोध के लिए मान्य DNS परिणामों को पिन करते हैं, मेटाडेटा/लिंक-लोकल गंतव्यों को अस्वीकार करते हैं, रीडायरेक्ट अक्षम करते हैं, और कनेक्शन/रीड/कुल टाइमआउट और एक प्रतिक्रिया बाइट सीमा लागू करते हैं। निजी और लूपबैक पते सामान्य आंतरिक Doris परिनियोजन और SSH टनल के लिए उपलब्ध रहते हैं।

DORIS_HOSTS और DORIS_FE_HTTP_HOSTS क्रमबद्ध फेलओवर सूचियाँ हैं, लोड-संतुलन या क्लस्टर-खोज सेटिंग्स नहीं। एक सूची में प्रत्येक होस्ट को एक ही Doris क्लस्टर से संबंधित होना चाहिए और कॉन्फ़िगर किए गए साझा पोर्ट और क्रेडेंशियल्स का उपयोग करना चाहिए। सर्वर वैश्विक/स्थैतिक-टोकन पूल निर्माण और पुनर्प्राप्ति के दौरान क्रम में उम्मीदवारों की जाँच करता है; FE HTTP अनुरोध केवल ट्रांसपोर्ट त्रुटि या 502/503/504 पर अगले कॉन्फ़िगर किए गए एंडपॉइंट पर जाते हैं। Doris-समर्थित OAuth साइन-इन के दौरान उम्मीदवारों को आज़माता है, लेकिन एक स्थापित प्रति-उपयोगकर्ता पूल को विफलता के बाद पुनर्निर्मित नहीं किया जा सकता क्योंकि सर्वर जानबूझकर उपयोगकर्ता का कच्चा पासवर्ड बरकरार नहीं रखता है; उपयोगकर्ता को फिर से साइन इन करना होगा। बड़े उत्पादन परिनियोजन के लिए अभी भी एक स्थिर लोड बैलेंसर या SQL गेटवे की सिफारिश की जाती है।

प्रश्न: अनुकूलन के लिए LLM के साथ SQL Explain/Profile फ़ाइलों का उपयोग कैसे करें?

उत्तर: उपकरण LLM विश्लेषण के लिए संक्षिप्त सामग्री और पूर्ण फ़ाइलें दोनों प्रदान करते हैं:

विश्लेषण परिणाम प्राप्त करें:

{
  "content": "Truncated plan for immediate review",
  "file_path": "/tmp/explain_12345.txt",
  "is_content_truncated": true
}

LLM विश्लेषण कार्यप्रवाह:
- त्वरित अंतर्दृष्टि के लिए संक्षिप्त सामग्री की समीक्षा करें
- पूर्ण फ़ाइल को अनुलग्नक के रूप में अपने LLM पर अपलोड करें
- अनुकूलन सुझाव या प्रदर्शन विश्लेषण का अनुरोध करें
- अनुशंसित सुधार लागू करें
सामग्री का आकार कॉन्फ़िगर करें:
```
MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed
```

प्रश्न: डेटा सुरक्षा और मास्किंग सुविधाएँ कैसे सक्षम करें?

उत्तर: अपनी .env फ़ाइल में निम्नलिखित कॉन्फ़िगरेशन सेट करें:

# Enable data masking
ENABLE_MASKING=true
# Set maximum result rows
MAX_RESULT_ROWS=10000

प्रश्न: Stdio मोड और HTTP मोड में क्या अंतर है?

उत्तर:

Stdio मोड: MCP क्लाइंट (जैसे Cursor) के साथ सीधे एकीकरण के लिए उपयुक्त, जहाँ क्लाइंट सर्वर प्रक्रिया का प्रबंधन करता है
HTTP मोड: स्वतंत्र वेब सेवा जो कई क्लाइंट कनेक्शन का समर्थन करती है, उत्पादन वातावरण के लिए उपयुक्त

सिफारिशें:

विकास और व्यक्तिगत उपयोग: Stdio मोड
उत्पादन और बहु-उपयोगकर्ता वातावरण: HTTP मोड

प्रश्न: कनेक्शन टाइमआउट समस्याओं का समाधान कैसे करें?

उत्तर: निम्नलिखित समाधान आज़माएँ:

टाइमआउट सेटिंग्स बढ़ाएँ:
```
# Set in .env file
QUERY_TIMEOUT=60
CONNECTION_TIMEOUT=30
```

नेटवर्क कनेक्टिविटी की जाँच करें:

# /live verifies the process; /ready also verifies Doris
curl --fail http://localhost:3000/live
curl --fail http://localhost:3000/ready

कनेक्शन पूल कॉन्फ़िगरेशन अनुकूलित करें:
```
DORIS_MAX_CONNECTIONS=20
```

प्रश्न: `at_eof` कनेक्शन त्रुटियों का समाधान कैसे करें? (v0.5.0 में पूरी तरह से ठीक)

उत्तर: संस्करण 0.5.0 ने व्यापक कनेक्शन पूल रीडिज़ाइन के माध्यम से महत्वपूर्ण at_eof कनेक्शन त्रुटियों को पूरी तरह से हल कर दिया है:

समस्या:

कनेक्शन पूल पूर्व-निर्माण और अनुचित कनेक्शन स्थिति प्रबंधन के कारण at_eof त्रुटियाँ हुईं
MySQL aiomysql रीडर स्थिति कनेक्शन जीवनचक्र के दौरान असंगत हो रही थी
समवर्ती भार के तहत कनेक्शन पूल अस्थिरता

समाधान (v0.5.0):

कनेक्शन पूल रणनीति ओवरहाल:
- शून्य न्यूनतम कनेक्शन: पूर्व-निर्माण समस्याओं को रोकने के लिए min_connections को डिफ़ॉल्ट से 0 में बदल दिया
- ऑन-डिमांड कनेक्शन निर्माण: कनेक्शन केवल जरूरत पड़ने पर बनाए जाते हैं, बासी कनेक्शन समस्याओं को समाप्त करते हैं
- ताज़ा कनेक्शन रणनीति: हमेशा पूल से ताज़ा कनेक्शन प्राप्त करें, कोई सत्र-स्तरीय कैशिंग नहीं
उन्नत स्वास्थ्य निगरानी:
- टाइमआउट-आधारित स्वास्थ्य जाँच: कनेक्शन सत्यापन प्रश्नों के लिए 3-सेकंड का टाइमआउट
- पृष्ठभूमि स्वास्थ्य मॉनिटर: हर 30 सेकंड में निरंतर पूल स्वास्थ्य निगरानी
- सक्रिय बासी पहचान: समस्याग्रस्त कनेक्शनों की स्वचालित पहचान और सफाई
बुद्धिमान पुनर्प्राप्ति प्रणाली:
- स्वचालित पूल पुनर्प्राप्ति: व्यापक त्रुटि प्रबंधन के साथ स्व-उपचार पूल
- एक्सपोनेंशियल बैकऑफ़ रिट्री: 3 प्रयासों तक स्मार्ट रिट्री तंत्र
- कनेक्शन-विशिष्ट त्रुटि पहचान: कनेक्शन-संबंधी त्रुटियों की सटीक पहचान
प्रदर्शन अनुकूलन:
- पूल वार्मअप: इष्टतम प्रदर्शन के लिए बुद्धिमान कनेक्शन पूल वार्मिंग
- पृष्ठभूमि सफाई: सक्रिय संचालन को प्रभावित किए बिना बासी कनेक्शनों की आवधिक सफाई
- कनेक्शन निदान: वास्तविक समय कनेक्शन स्वास्थ्य निगरानी और रिपोर्टिंग

कनेक्शन स्वास्थ्य की निगरानी:

# Monitor connection pool health in real-time
tail -f logs/doris_mcp_server_info.log | grep -E "(pool|connection|at_eof)"

# Check detailed connection diagnostics
tail -f logs/doris_mcp_server_debug.log | grep "connection health"

# Check process liveness and Doris readiness
curl --fail http://localhost:8000/live
curl --fail http://localhost:8000/ready

इष्टतम कनेक्शन प्रदर्शन के लिए कॉन्फ़िगरेशन:

# Recommended connection pool settings in .env
DORIS_MAX_CONNECTIONS=20          # Adjust based on workload
CONNECTION_TIMEOUT=30             # Connection establishment timeout
QUERY_TIMEOUT=60                  # Query execution timeout

# Health monitoring settings
HEALTH_CHECK_INTERVAL=60          # Pool health check frequency

परिणाम: पुनः डिज़ाइन किया गया जीवनचक्र बासी-कनेक्शन विफलताओं को कम करता है और पुनर्प्राप्ति व्यवहार में सुधार करता है। उत्पादन उपयोग से पहले लक्ष्य कार्यभार के तहत कॉन्फ़िगर किए गए पूल को मान्य करें।

प्रश्न: कौन से MCP प्रोटोकॉल संशोधन समर्थित हैं?

उत्तर: नए एकीकरणों को MCP 2026-07-28 का उपयोग करना चाहिए। Doris MCP सर्वर stdio पर 2025-11-25 आरंभीकरण प्रवाह स्वीकार करता है और, जब ENABLE_LEGACY_HTTP_ADAPTER=true, पृथक /mcp/legacy HTTP एंडपॉइंट पर। आधुनिक /mcp एंडपॉइंट केवल POST है और कभी भी विरासत ट्रांसपोर्ट पर वापस नहीं आता है। पुराने संशोधन और सेवानिवृत्त HTTP+SSE ट्रांसपोर्ट समर्थित संगतता अनुबंध का हिस्सा नहीं हैं।

Doris MCP सर्वर पैकेज संस्करण या Python mcp निर्भरता संस्करण से वायर-प्रोटोकॉल समर्थन का अनुमान न लगाएं। अनुरोध मेटाडेटा, HTTP हेडर, माइग्रेशन चरणों और परिनियोजन सीमाओं के लिए MCP प्रोटोकॉल समर्थन और माइग्रेशन देखें।

प्रश्न: ADBC उच्च-प्रदर्शन सुविधाएँ कैसे सक्षम करें? (v0.5.0 में नया)

उत्तर: ADBC (Arrow Flight SQL) बड़े डेटासेट के लिए 3-10x प्रदर्शन सुधार प्रदान करता है:

ADBC निर्भरताएँ (v0.5.0+ में स्वचालित रूप से शामिल):
```
# ADBC dependencies are now included by default in doris-mcp-server>=0.5.0
# No separate installation required
```

Arrow Flight SQL पोर्ट कॉन्फ़िगर करें:

# Add to your .env file
FE_ARROW_FLIGHT_SQL_PORT=8096
BE_ARROW_FLIGHT_SQL_PORT=8097

वैकल्पिक ADBC अनुकूलन:

# Customize ADBC behavior (optional)
ADBC_DEFAULT_MAX_ROWS=10000
ADBC_DEFAULT_TIMEOUT=120
ADBC_DEFAULT_RETURN_FORMAT=pandas  # arrow/pandas/dict

ADBC कनेक्शन का परीक्षण करें:

# Discover doris_query, then call its get_adbc_connection_info child
# Should show "status": "ready" and port connectivity

प्रश्न: डेटा गवर्नेंस और पाइपलाइन उपकरणों का उपयोग कैसे करें?

उत्तर: पहले प्रासंगिक डोमेन खोजें, उसका manifest_version बनाए रखें, और फिर स्कीमा-मान्य तर्कों के साथ एक सटीक चाइल्ड को कॉल करें:

स्तंभ विश्लेषण:

{
  "tool_name": "doris_governance",
  "arguments": {
    "child_tool": "analyze_columns",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "database": "analytics",
      "table": "customer_data",
      "sample_ratio": 0.1
    }
  }
}

स्तंभ वंशावली ट्रैकिंग:

{
  "tool_name": "doris_governance",
  "arguments": {
    "child_tool": "trace_column_lineage",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "object": "internal.analytics.orders",
      "column": "customer_id",
      "direction": "both",
      "depth": 3
    }
  }
}

डेटा ताज़गी निगरानी:

{
  "tool_name": "doris_pipeline",
  "arguments": {
    "child_tool": "monitor_data_freshness",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "database": "analytics",
      "table": "orders",
      "threshold_seconds": 86400
    }
  }
}

प्रदर्शन विश्लेषिकी:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "list_slow_queries",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "window_minutes": 10080,
      "limit": 20
    }
  }
}

प्रश्न: उन्नत लॉगिंग प्रणाली का उपयोग कैसे करें? (v0.5.0 में बेहतर)

उत्तर: संस्करण 0.5.0 स्वचालित प्रबंधन और स्तर-आधारित संगठन के साथ एक व्यापक लॉगिंग प्रणाली प्रस्तुत करता है:

लॉग फ़ाइल संरचना (v0.5.0 में नया):

logs/
├── doris_mcp_server_debug.log      # DEBUG level messages
├── doris_mcp_server_info.log       # INFO level messages  
├── doris_mcp_server_warning.log    # WARNING level messages
├── doris_mcp_server_error.log      # ERROR level messages
├── doris_mcp_server_critical.log   # CRITICAL level messages
├── doris_mcp_server_all.log        # Combined log (all levels)
└── doris_mcp_server_audit.log      # Audit trail (separate)

उन्नत लॉगिंग सुविधाएँ:

स्तर-आधारित फ़ाइल पृथक्करण: आसान समस्या निवारण के लिए लॉग स्तर द्वारा स्वचालित संगठन
टाइमस्टैम्प्ड फ़ॉर्मेटिंग: पेशेवर लॉगिंग के लिए उचित संरेखण के साथ मिलीसेकंड सटीकता
स्वचालित लॉग रोटेशन: कॉन्फ़िगर करने योग्य फ़ाइल आकार सीमाओं के साथ डिस्क स्थान की समस्याओं को रोकता है
पृष्ठभूमि सफाई: कॉन्फ़िगर करने योग्य अवधारण नीतियों के साथ बुद्धिमान सफाई अनुसूचक
ऑडिट ट्रेल: अनुपालन और सुरक्षा निगरानी के लिए अलग ऑडिट लॉगिंग

लॉग देखना:

# View real-time logs by level
tail -f logs/doris_mcp_server_info.log     # General operational info
tail -f logs/doris_mcp_server_error.log    # Error tracking
tail -f logs/doris_mcp_server_debug.log    # Detailed debugging

# View all activity in combined log
tail -f logs/doris_mcp_server_all.log

# Monitor specific operations
tail -f logs/doris_mcp_server_info.log | grep -E "(query|connection|tool)"

# View audit trail
tail -f logs/doris_mcp_server_audit.log

कॉन्फ़िगरेशन:

# Enhanced logging configuration in .env
LOG_LEVEL=INFO                         # Base log level
ENABLE_AUDIT=true                      # Enable audit logging
ENABLE_LOG_CLEANUP=true                # Enable automatic cleanup
LOG_MAX_AGE_DAYS=30                    # Keep logs for 30 days
LOG_CLEANUP_INTERVAL_HOURS=24          # Check for cleanup daily

# Advanced settings
LOG_FILE_PATH=logs                     # Log directory (auto-organized)

उन्नत लॉग के साथ समस्या निवारण:

# Debug connection issues
grep -E "(connection|pool|at_eof)" logs/doris_mcp_server_error.log

# Monitor tool performance
grep "execution_time" logs/doris_mcp_server_info.log

# Check system health
tail -20 logs/doris_mcp_server_warning.log

# View recent critical issues
cat logs/doris_mcp_server_critical.log

लॉग सफाई प्रबंधन:

स्वचालित: पृष्ठभूमि अनुसूचक LOG_MAX_AGE_DAYS से पुरानी फ़ाइलों को हटाता है
मैनुअल: लॉग स्वचालित रूप से तब घुमाए जाते हैं जब वे 10MB तक पहुँच जाते हैं
बैकअप: प्रत्येक लॉग स्तर के लिए 5 बैकअप फ़ाइलें रखता है
प्रदर्शन: सर्वर प्रदर्शन पर न्यूनतम प्रभाव

प्रश्न: नए टोकन-बाउंड डेटाबेस कॉन्फ़िगरेशन का उपयोग कैसे करें? (v0.6.0 में नया)

उत्तर: क्रांतिकारी टोकन-बाउंड डेटाबेस कॉन्फ़िगरेशन प्रत्येक टोकन को सुरक्षित बहु-किरायेदार पहुँच के लिए अपने स्वयं के डेटाबेस कनेक्शन पैरामीटर ले जाने की अनुमति देता है:

टोकन प्रमाणीकरण सक्षम करें:

# In your .env file
ENABLE_TOKEN_AUTH=true
TOKEN_HOT_RELOAD=true
TOKEN_FILE_PATH=tokens.json

बियरर टोकन एक बार बनाएँ और केवल उसका डाइजेस्ट tokens.json में संग्रहीत करें:

{
  "version": "2.0",
  "tokens": [
    {
      "token_id": "tenant-alpha",
      "token_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "created_at": "2026-07-29T00:00:00Z",
      "expires_at": null,
      "last_used": null,
      "description": "Tenant Alpha database access",
      "is_active": true,
      "database_config": {
        "host": "tenant-alpha-db.company.com",
        "hosts": [
          "tenant-alpha-fe-1.company.com",
          "tenant-alpha-fe-2.company.com"
        ],
        "port": 9030,
        "user": "alpha_user",
        "password": "secure_password",
        "database": "alpha_analytics",
        "charset": "UTF8",
        "fe_http_hosts": [
          "tenant-alpha-fe-1.company.com",
          "tenant-alpha-fe-2.company.com"
        ],
        "fe_http_port": 8030
      }
    }
  ]
}

टोकन-बाउंड डेटाबेस कॉन्फ़िगरेशन में दिए गए कमांड से वास्तविक बियरर टोकन और डाइजेस्ट जनरेट करें। उपरोक्त सभी-शून्य मान जानबूझकर अनुपयोगी है। क्लाइंट को एक बार बियरर मान दें; इसे फ़ाइल में न रखें।

कॉन्फ़िगरेशन प्राथमिकता (v0.6.0 में नया):
- टोकन-बाउंड DB कॉन्फ़िग (उच्चतम प्राथमिकता)
- पर्यावरण चर (.env)
- यदि दोनों में से कोई उपलब्ध नहीं है तो त्रुटि
हॉट रीलोड लाभ:
- सेवा पुनरारंभ के बिना नए किरायेदार जोड़ें
- वास्तविक समय में डेटाबेस क्रेडेंशियल अपडेट करें
- त्रुटियों पर स्वचालित सत्यापन और रोलबैक
- परिवर्तनों का पूर्ण ऑडिट ट्रेल

बहु-किरायेदार उपयोग:

# Different tokens access different databases automatically
curl -H "Authorization: Bearer $TOKEN_TENANT_ALPHA" http://localhost:3000/mcp
curl -H "Authorization: Bearer $TOKEN_TENANT_BETA" http://localhost:3000/mcp

प्रत्येक टोकन एक भिन्न Doris क्लस्टर से बंध सकता है। एक टोकन बाइंडिंग के भीतर, hosts और fe_http_hosts उसी क्लस्टर के लिए क्रमबद्ध FE उम्मीदवार हैं। प्रमाणित टोकन मार्ग को निश्चित करता है; MCP उपकरण तर्क किसी अन्य क्लस्टर का चयन या अधिरोहण नहीं कर सकते। इस बहु-आवृत्ति मोड के लिए स्थैतिक-टोकन प्रमाणीकरण के साथ HTTP परिवहन की आवश्यकता होती है। एक stdio प्रक्रिया में एक वैश्विक डेटाबेस मार्ग होता है, इसलिए जब क्लाइंट को अलग-अलग क्लस्टर की आवश्यकता हो तो अलग-अलग stdio प्रक्रियाएँ चलाएँ। exec_adbc_query टोकन-बद्ध मार्गों पर जानबूझकर विफल-बंद है क्योंकि वर्तमान Arrow Flight क्लाइंट प्रक्रिया-वैश्विक है; उस क्लस्टर के लिए doris_query.execute_query या एक अलग MCP प्रक्रिया का उपयोग करें।

प्रश्न: Doris-समर्थित OAuth बाहरी OAuth/OIDC से किस प्रकार भिन्न है?

उत्तर: बाहरी OAuth/OIDC पहचान को किसी बाहरी प्रदाता जैसे Google, Azure AD, GitHub, GitLab, या Keycloak को सौंपता है। Doris-समर्थित OAuth इस MCP सर्वर द्वारा तब जारी किया जाता है जब उपयोगकर्ता Doris क्रेडेंशियल्स के साथ साइन इन करता है। सर्वर Doris उपयोगकर्ता नाम/पासवर्ड को मान्य करता है, प्रति-उपयोगकर्ता Doris कनेक्शन पूल बनाता है, doa_ एक्सेस और रिफ्रेश टोकन जारी करता है, और Doris RBAC को यह तय करने देता है कि वह उपयोगकर्ता किस डेटा और मेटाडेटा तक पहुँच सकता है।

ये मोड एक MCP URL पर परस्पर अनन्य हैं। ENABLE_DORIS_OAUTH_AUTH=true को ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true, या AUTH_TYPE=oauth के साथ सक्षम न करें; यदि दोनों OAuth मोड कॉन्फ़िगर किए गए हैं तो स्टार्टअप तेजी से विफल हो जाता है।

Doris-समर्थित OAuth वर्तमान में अक्षम संसाधन मेटाडेटा कैश के साथ MCP संसाधनों को उजागर करता है। यह समीक्षित मेटाडेटा उपकरणों को तब उजागर करता है जब DORIS_OAUTH_DB_TOOLS_ENABLED=true, exec_query जब DORIS_OAUTH_QUERY_TOOLS_ENABLED=true, और SQL व्याख्या जब DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true। सामान्य क्लाइंट को एक लंबी स्कोप सूची पास करने की आवश्यकता नहीं है; छोड़ा गया OAuth स्कोप कॉन्फ़िगर किए गए Doris OAuth क्षमता लिफाफे को प्रदान करता है। Doris RBAC इन MySQL-चैनल संचालनों के लिए अंतिम डेटा प्राधिकरण बैकएंड बना रहता है।

प्रश्न: क्या Doris-समर्थित OAuth एकाधिक वर्कर्स या एकाधिक नोड्स के साथ चल सकता है?

उत्तर: वर्तमान कार्यान्वयन में नहीं। Doris-समर्थित OAuth केवल-मेमोरी OAuth स्टोर और प्रक्रिया-स्थानीय प्रति-उपयोगकर्ता Doris पूल का उपयोग करता है। एक्सेस टोकन, रिफ्रेश टोकन, प्राधिकरण कोड, DCR क्लाइंट और पूल वर्कर्स, प्रक्रियाओं या नोड्स के बीच साझा नहीं किए जाते हैं।

Doris-समर्थित OAuth के साथ WORKERS=1 का उपयोग करें। WORKERS=0 CPU गणना तक विस्तारित होता है और विफल हो जाता है क्योंकि यह कई प्रभावी वर्कर्स बनाएगा। स्टेटलेस क्षैतिज स्केलिंग, साझा टोकन भंडारण, साझा एन्क्रिप्टेड Doris क्रेडेंशियल्स, स्टिकी-सेशन रिकवरी, और पूल पुनर्निर्माण भविष्य के डिज़ाइन हैं, वर्तमान क्षमताएँ नहीं।

प्रश्न: हॉट रीलोड कैसे काम करता है और क्या यह सुरक्षित है? (v0.6.0 में नया)

उत्तर: हॉट रीलोड प्रणाली व्यापक सुरक्षा उपायों के साथ एंटरप्राइज़ उत्पादन वातावरण के लिए डिज़ाइन की गई है:

यह कैसे काम करता है:

अनुरोध-समय तुल्यकालन: प्रत्येक टोकन लुकअप साझा फ़ाइल हस्ताक्षर की तुलना करता है, इसलिए किसी अन्य स्थानीय वर्कर का निर्माण या निरसन पोलिंग अंतराल की प्रतीक्षा करने के बजाय अगले प्रमाणित अनुरोध पर देखा जाता है
पृष्ठभूमि निगरानी: एक 10-सेकंड का मॉनिटर अभी भी निष्क्रिय वर्कर्स को ताज़ा करता है
क्रमबद्ध अद्यतन: tokens.json.lock स्थानीय वर्कर प्रक्रियाओं में प्रत्येक प्रबंधित पढ़ने-संशोधित-लिखने के संचालन की रक्षा करता है
परमाणु अद्यतन: एक समान-निर्देशिका अस्थायी फ़ाइल को फ्लश किया जाता है और केवल-स्वामी अनुमतियों के साथ परमाणु रूप से बदला जाता है
रोलबैक सुरक्षा: अमान्य बाह्य रूप से संपादित स्थिति किसी वर्कर के वर्तमान इन-मेमोरी दृश्य को आंशिक रूप से प्रतिस्थापित नहीं करती है
साझा निरसन: revoked_tokens केवल टोकन डाइजेस्ट संग्रहीत करता है और प्रत्येक वर्कर में मिलान TOKEN_<ID> पर्यावरण क्रेडेंशियल्स को भी अक्षम करता है

सुरक्षा विशेषताएँ:

कोई खोया हुआ अद्यतन नहीं: समवर्ती निर्माण/निरसन संचालन प्रक्रिया-साझा लॉक को धारण करते हुए नवीनतम दस्तावेज़ को पुनः लोड करते हैं
कोई बियरर-टोकन सादा पाठ स्थायित्व नहीं: लाइव और निरस्त बियरर मान केवल स्व-वर्णनात्मक डाइजेस्ट द्वारा दर्शाए जाते हैं
केवल-स्वामी स्थिति फ़ाइलें: प्रबंधित स्थिति और लॉक फ़ाइलें मोड 0600 का उपयोग करती हैं
त्रुटि पृथक्करण: अमान्य स्थिति को पूर्ण स्थानीय टोकन मानचित्र को बदलने से पहले अस्वीकार कर दिया जाता है

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

# Monitor hot reload activity
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

# Test configuration before applying
cp tokens.json tokens.json.backup
# Make changes to tokens.json
# System will automatically validate and apply or rollback

प्रश्न: टोकन जीवनचक्र और सुरक्षा का प्रबंधन कैसे करें? (v0.6.0 में नया)

उत्तर: टोकन प्रबंधन वैकल्पिक प्रशासनिक अंतिम बिंदुओं के साथ एक सुरक्षित, फ़ाइल-आधारित दृष्टिकोण का उपयोग करता है जिनमें व्यापक सुरक्षा नियंत्रण होते हैं।

प्राथमिक टोकन प्रबंधन विधि (अनुशंसित):

# 1. Keep the management endpoint disabled unless local administration is needed.
# 2. When enabled, create a token through the protected localhost endpoint.
curl -X POST \
  -H "Authorization: Bearer $TOKEN_MANAGEMENT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"token_id":"service-a","expires_hours":720}' \
  http://127.0.0.1:3000/token/create

# 3. Capture the returned bearer token once and place it in the client secret store.
# 4. The server writes only token_digest to tokens.json.
# 5. Monitor hot reload in logs.
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

HTTP टोकन प्रबंधन के बिना तैनाती के लिए, एक उच्च-एन्ट्रॉपी TOKEN_<ID> पर्यावरण रहस्य का उपयोग करें या जैसा ऊपर दिखाया गया है ऑफ़लाइन एक बियरर/डाइजेस्ट जोड़ी उत्पन्न करें। मैन्युअल tokens.json प्रविष्टियों को token_digest का उपयोग करना चाहिए; सादा पाठ token प्रविष्टियाँ केवल संस्करण 1 से एक-तरफ़ा माइग्रेशन के लिए मौजूद हैं।

फ़ाइल बैकएंड एक होस्ट पर कई वर्कर प्रक्रियाओं का समन्वय करता है। प्रत्येक वर्कर को समान TOKEN_FILE_PATH का उपयोग करना चाहिए, और अंतर्निहित फ़ाइल सिस्टम को विश्वसनीय फ़ाइल लॉकिंग और परमाणु नाम बदलने के शब्दार्थ प्रदान करने चाहिए। साझा लॉकिंग फ़ाइल सिस्टम के बिना एकाधिक होस्ट या कंटेनरों को एक बाहरी लेन-देन स्थिति बैकएंड की आवश्यकता होती है; अलग-अलग tokens.json फ़ाइलों की प्रतिलिपि बनाना क्लस्टर-व्यापी निरसन प्रदान नहीं करता है।

प्रशासनिक अंतिम बिंदु (सुरक्षित, केवल स्थानीय पहुँच):

🛡️ सुरक्षा: ये अंतिम बिंदु व्यापक सुरक्षा नियंत्रणों द्वारा संरक्षित हैं और डिफ़ॉल्ट रूप से अक्षम हैं।

# Security Requirements (ALL must be met):
# ✓ HTTP token management explicitly enabled in configuration
# ✓ Access only from localhost (127.0.0.1/::1) - IP restrictions enforced
# ✓ Valid admin authentication token required
# ✓ Admin authentication enabled in configuration

# Enable HTTP token management (disabled by default)
export TOKEN_MANAGEMENT_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export REQUIRE_ADMIN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

# Access with proper authentication
curl -H "Authorization: Bearer $TOKEN_MANAGEMENT_ADMIN_TOKEN" http://127.0.0.1:3000/token/stats

# Demo page (local access only, with authentication)
# Access: http://127.0.0.1:3000/token/demo

अनुशंसित टोकन प्रबंधन कार्यप्रवाह:

विकास/परीक्षण:

// tokens.json
{
  "version": "2.0",
  "tokens": [
    {
      "token_id": "dev-token",
      "token_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "created_at": "2026-07-29T00:00:00Z",
      "expires_at": "2026-07-30T00:00:00Z",
      "last_used": null,
      "description": "Development environment access",
      "is_active": true
    }
  ]
}

सभी-शून्य डाइजेस्ट को सुरक्षित रूप से उत्पन्न बियरर टोकन से व्युत्पन्न एक से बदलें, और उस बियरर टोकन को सर्वर फ़ाइल के बाहर रखें।

उत्पादन तैनाती:

# Use secure token generation
openssl rand -hex 32  # Generate secure token

# Store in secure configuration management
# Never commit tokens to version control
# Use environment variables for sensitive tokens

सुरक्षा विशेषताएँ:

केवल-डाइजेस्ट स्थायित्व: बियरर सादा पाठ केवल तभी लौटाया जाता है जब बनाया जाता है; संस्करण 2 फ़ाइलों में स्व-वर्णनात्मक SHA-256/SHA-512 डाइजेस्ट होते हैं
परमाणु फ़ाइल प्रबंधन: प्रबंधित लेखन समान-निर्देशिका प्रतिस्थापन का उपयोग करते हैं और केवल-स्वामी 0600 अनुमतियों को बाध्य करते हैं
हॉट रीलोड: सेवा रुकावट के बिना स्वचालित कॉन्फ़िगरेशन अद्यतन
विरासत माइग्रेशन: संस्करण 1 सादा पाठ प्रविष्टियाँ पहले सफल लोड पर केवल-डाइजेस्ट रिकॉर्ड द्वारा प्रतिस्थापित कर दी जाती हैं
ऑडिट ट्रेल: सभी टोकन संचालनों और परिवर्तनों की पूर्ण लॉगिंग
समाप्ति प्रबंधन: समाप्त टोकनों की स्वचालित सफाई
केवल स्थानीय व्यवस्थापक: प्रबंधन अंतिम बिंदु लोकलहोस्ट पहुँच तक सीमित
कॉन्फ़िगरेशन सत्यापन: टोकन और डेटाबेस कॉन्फ़िगरेशन का तत्काल सत्यापन

सुरक्षा सर्वोत्तम अभ्यास:

बियरर मानों को क्लाइंट-साइड गुप्त प्रबंधन में संग्रहीत करें; सर्वर पर केवल डाइजेस्ट रखें
टोकन प्रबंधन अंतिम बिंदुओं को कभी भी बाहरी नेटवर्क के संपर्क में न लाएँ
उत्पादन के लिए मजबूत, यादृच्छिक रूप से उत्पन्न टोकन का उपयोग करें
मैन्युअल रूप से प्रबंधित tokens.json फ़ाइलों को केवल-स्वामी पठनीय रखें; प्रबंधित लेखन 0600 लागू करते हैं
सक्रिय टोकनों और उनके उपयोग पैटर्न का नियमित ऑडिट
अनधिकृत कॉन्फ़िगरेशन परिवर्तनों के लिए हॉट रीलोड लॉग की निगरानी करें

अन्य समस्याओं के लिए, कृपया GitHub Issues की जाँच करें या एक नया मुद्दा सबमिट करें।