Open MCP Gateway کے ساتھ مقامی MCP سروسز کے لیے OpenAPI گیٹ وے بنائیں

Open MCP Gateway کیا ہے؟

Open MCP Gateway، جسے مختصراً OMG کہا جاتا ہے، ایک اعلیٰ کارکردگی والا گیٹ وے ہے جو مقامی طور پر تعینات Model Context Protocol سروسز کو OpenAPI 3.1.0 کے مطابق HTTP REST روٹس کے ذریعے فراہم کرتا ہے۔ یہ Open WebUI ایکو سسٹم کے لیے Bun 1.4 اور TypeScript کے ساتھ بنایا گیا ہے، تاہم یہ ایک کمیونٹی پروجیکٹ ہے اور Open WebUI ٹیم سے وابستہ نہیں ہے۔

یہ گیٹ وے ایک بیرونی کلائنٹ اور ایک یا زیادہ MCP سروسز کے درمیان کام کرتا ہے۔ Open WebUI جیسا کلائنٹ گیٹ وے سے HTTP یا HTTPS کے ذریعے رابطہ کرتا ہے، جبکہ گیٹ وے بنیادی MCP ٹرانسپورٹس کا انتظام کرتا ہے اور ان کے ٹولز کو OpenAPI سے مطابقت رکھنے والے انٹرفیس میں تبدیل کرتا ہے۔

OMG مقامی بائنری stdio سروسز، Node یا Bun اسکرپٹ پر مبنی stdio پائپ لائنز، اور SSE یا HTTP نیٹ ورک ٹرانسپورٹس کو سپورٹ کرتا ہے۔ اس طرح مختلف اجرا اور مواصلاتی ماڈلز استعمال کرنے والی MCP سروسز کے لیے ایک مستقل HTTP انٹرفیس فراہم کیا جا سکتا ہے۔

اہم خصوصیات

• سخت OpenAPI 3.1.0 آؤٹ پٹ: ٹول کے ان پٹ اسکیما کو requestBody.content['application/json'].schema کے تحت رکھا جاتا ہے۔ تیار کردہ operationId اقدار اصل MCP ٹول نام برقرار رکھتی ہیں اور tool_*_post جیسے نام شامل نہیں کرتیں۔
• متعدد MCP ٹرانسپورٹس: مقامی بائنری stdio، اسکرپٹ stdio، SSE، اور HTTP سروسز کا انتظام ایک ہی گیٹ وے کے ذریعے کیا جا سکتا ہے۔
• بلیو گرین سیشن پول: سروس سیشنز کو AsyncMutex کے پیچھے ہاٹ سوئپ کیا جاتا ہے، جس سے جاری درخواستوں میں خلل ڈالے بغیر کنفیگریشن اپ ڈیٹ کی جا سکتی ہے۔
• لائف سائیکل مینجمنٹ: گیٹ وے پروٹوکول ریپنگ، لائف سائیکل کی خودکار بحالی، اور زیر انتظام سروسز کے لیے ہاٹ ری لوڈنگ فراہم کرتا ہے۔
• کراس پلیٹ فارم XDG لے آؤٹ: کنفیگریشن، ایپلیکیشن ڈیٹا، رن ٹائم اسٹیٹ، اور کیش فائلیں سورس ریپوزٹری سے باہر رکھی جاتی ہیں۔
• اسٹینڈ الون بلڈز: Bun گیٹ وے کو ایک ایسی مقامی ایگزیکیوٹیبل میں کمپائل کر سکتا ہے جس کے لیے رن ٹائم انحصارات درکار نہیں ہوتے۔
• ریورس پراکسی سپورٹ: گیٹ وے X-Forwarded-* ہیڈرز پڑھتا ہے، تاکہ تیار کردہ OpenAPI servers.url کلائنٹس کو نظر آنے والے بیرونی پتے کی عکاسی کرے۔

ضروریات

سورس سے پروجیکٹ چلانے کے لیے Bun 1.4 یا اس کے بعد کا ورژن درکار ہے۔ رجسٹر کرنے کے لیے کم از کم ایک MCP سروس بھی ضروری ہے۔ یہ سروس مقامی مقامی ایگزیکیوٹیبل، Bun کے ذریعے چلایا جانے والا JavaScript یا TypeScript پیکیج، یا SSE یا HTTP کے ذریعے دستیاب MCP سروس ہو سکتی ہے۔

گیٹ وے انسٹال اور چلائیں

سورس سے چلائیں

ریپوزٹری کو کلون یا ڈاؤن لوڈ کریں، اس کی ڈائریکٹری میں جائیں، انحصارات انسٹال کریں، اور ڈیولپمنٹ کمانڈ شروع کریں:

bun install
bun run dev

ڈیولپمنٹ پراسیس گیٹ وے کی کنفیگریشن ریپوزٹری کے بجائے پلیٹ فارم کی XDG کنفیگریشن ڈائریکٹری سے پڑھتا ہے۔

اسٹینڈ الون ایگزیکیوٹیبل بنائیں

مقامی ایگزیکیوٹیبل بنانے کے لیے چلائیں:

bun run build

آؤٹ پٹ Unix جیسے سسٹمز پر build/mcp-gateway یا Windows پر build/mcp-gateway.exe میں لکھا جاتا ہے۔ تعینات کیے جانے پر کمپائل شدہ بائنری کے لیے علیحدہ Bun رن ٹائم درکار نہیں ہوتا۔

XDG ڈائریکٹری لے آؤٹ سمجھیں

Open MCP Gateway فائلوں کو ان کے مقصد کے مطابق الگ کرتا ہے۔ اس سے تیار کردہ ڈیٹا، انسٹال شدہ پلگ اِنز، لاگز، اور کیشز کو سورس ٹری میں غیر ضروری طور پر شامل ہونے سے روکا جاتا ہے۔

• کنفیگریشن: XDG_CONFIG_HOME میں مرکزی mcp-gateway/config.json5 فائل ہوتی ہے۔
• ڈیٹا: XDG_DATA_HOME میں بیرونی MCP پلگ اِن ریپوزٹری اور اس کی اپنی package.json فائل ہوتی ہے۔
• اسٹیٹ: XDG_STATE_HOME رن ٹائم اسٹیٹ اور مستقل لاگز محفوظ کرتا ہے۔
• کیش: XDG_CACHE_HOME کیش شدہ اسپیسیفیکیشن دستاویزات اور عارضی رن ٹائم ڈیٹا محفوظ کرتا ہے۔

مرکزی کنفیگریشن پاتھ یہ ہے:

$XDG_CONFIG_HOME/mcp-gateway/config.json5

یہ فائل JSON5 استعمال کرتی ہے، اس لیے تبصرے اور اختتامی کامے سپورٹ کیے جاتے ہیں۔

MCP سروسز کنفیگر کریں

ضرورت ہو تو کنفیگریشن ڈائریکٹری بنائیں، پھر config.json5 شامل کریں۔ درج ذیل مثال ایک مقامی MCP ایگزیکیوٹیبل اور ایک پیکیج پر مبنی MCP سروس رجسٹر کرتی ہے:

{
    mcpServers: {
        // Native Binary Stdio
        codebase_memory: {
            command: "${HOME}/.local/bin/codebase-memory-mcp",
            args: [],
            env: {},
        },

        // Script Stdio
        another_mcp: {
            command: "bun",
            args: [
                "run",
                "${APP_DATA_DIR}/node_modules/<pkg>/dist/index.js",
            ],
            env: {},
        },
    },

    host: "127.0.0.1",
    port: 9090,
}

mcpServers کے اندر ہر کلید ایک MCP سروس کی شناخت کرتی ہے۔ مقامی بائنری کے لیے command کو ایگزیکیوٹیبل پاتھ پر سیٹ کریں۔ پیکیج پر مبنی سروس کے لیے Bun کو کمانڈ کے طور پر استعمال کریں اور انسٹال شدہ اسکرپٹ پاتھ کو args کے ذریعے فراہم کریں۔ سروس سے متعلق ماحول کے متغیرات env میں شامل کیے جا سکتے ہیں۔

گیٹ وے پاتھز میں ماحول کے متغیرات کی انٹرپولیشن کو سپورٹ کرتا ہے۔ متغیرات میں ${APP_DATA_DIR}، ${XDG_DATA_HOME}، ${HOME}، اور %USERPROFILE% شامل ہیں۔ انٹرپولیشن ہر مطلق پاتھ کو ہارڈ کوڈ کیے بغیر مختلف کمپیوٹرز پر کنفیگریشن کو دوبارہ استعمال کرنا آسان بناتی ہے۔

سروس کے شناخت کنندہ کو مستقل رکھیں۔ مثال کے طور پر، codebase_memory نام کی سروس کو اس OpenAPI دستاویز کی بازیافت کے وقت استعمال ہونے والے متعلقہ URL پاتھ کے تحت فراہم کیا جاتا ہے۔

بیرونی MCP پلگ اِنز کا انتظام کریں

کاروباری ضرورت سے متعلق MCP پیکیجز گیٹ وے ریپوزٹری میں انسٹال نہیں کیے جانے چاہییں۔ اس کے بجائے انہیں گیٹ وے کی XDG ڈیٹا ڈائریکٹری میں انسٹال اور برقرار رکھیں:

cd \"$XDG_DATA_HOME/mcp-gateway\"
bun add <mcp-package-name>

انسٹال شدہ پیکیج کو اپ گریڈ کرنے کے لیے چلائیں:

cd "$XDG_DATA_HOME/mcp-gateway"
bun update <pkg>

تنصیب کے بعد، ${APP_DATA_DIR} استعمال کرتے ہوئے config.json5 میں پیکیج کے انٹری پوائنٹ کا حوالہ دیں، جیسا کہ اسکرپٹ کے stdio کی مثال میں دکھایا گیا ہے۔ اس طرح گیٹ وے کی انحصاریاں MCP ایکسٹینشن کی انحصاریوں سے الگ رہتی ہیں۔

بنیادی استعمال

1. گیٹ وے کی انحصاریاں انسٹال کریں یا مقامی executable بنائیں۔

2. $XDG_CONFIG_HOME/mcp-gateway/config.json5 بنائیں۔

3. mcpServers کے تحت ایک یا زیادہ سروسز شامل کریں۔

4. bun run dev کے ذریعے گیٹ وے شروع کریں یا compiled executable چلائیں۔

5. ترتیب دی گئی سروس کے لیے OpenAPI دستاویز حاصل کریں اور اسے اپنے بیرونی کلائنٹ کے ساتھ رجسٹر کریں۔

codebase_memory نامی سروس کے لیے دستاویزی OpenAPI URL کا نمونہ یہ ہے:

http://<gateway-host>:8444/codebase_memory/openapi.json

اس مثال میں 8444 بیرونی طور پر قابل رسائی پورٹ ہے۔ یہ گیٹ وے کے اندرونی پورٹ کے بجائے reverse-proxy پورٹ بھی ہو سکتا ہے، جیسے configuration کی مثال میں 9090۔

Open WebUI کے ساتھ انضمام

Caddy یا Nginx جیسا reverse proxy گیٹ وے کو مطلوبہ بیرونی host، port اور protocol پر ظاہر کر سکتا ہے۔ پراکسی کو مناسب X-Forwarded-* headers بھیجنے کے لیے ترتیب دیں۔ Open MCP Gateway OpenAPI دستاویز بناتے وقت ان headers کو پڑھتا ہے، جس سے اس کا servers.url اندرونی listener کے بجائے عوامی پتے کی طرف اشارہ کرتا ہے۔

1. Open MCP Gateway کو reverse proxy کے پیچھے شروع کریں۔

2. Open WebUI کا انتظامی پینل کھولیں۔

3. Functions، Tools یا OpenAPI حصے میں جائیں۔

4. ترتیب دی گئی ہر MCP سروس کے لیے OpenAPI دستاویز کا URL رجسٹر کریں:

   http://<gateway-host>:8444/codebase_memory/openapi.json

5. Open WebUI کو specification لوڈ کرنے کی اجازت دیں۔ اس کے بعد MCP سروس کے ٹولز کو تیار کردہ OpenAPI operations کے ذریعے native tools کے طور پر استعمال کیا جا سکتا ہے۔

چونکہ operation IDs اصل MCP tool names کو برقرار رکھتے ہیں، اس لیے کلائنٹس کو گیٹ وے کے بنائے ہوئے suffixes یا prefixes کے بغیر صاف tool identifiers نظر آتے ہیں۔

ٹیسٹنگ اور لاگ مانیٹرنگ

گیٹ وے یا اس کی configuration میں تبدیلی کے بعد پروجیکٹ کی test command چلائیں:

bun run test

Windows پر repository PowerShell test script بھی فراہم کرتی ہے:

.\ps1_scripts\test-gateway.ps1

End-to-end assertions health check، MCP handshake اور proxy origin alignment کا احاطہ کرتی ہیں۔

Unix جیسے systems پر مستقل گیٹ وے لاگ کو یوں دیکھیں:

tail -f "$XDG_STATE_HOME/mcp-gateway/logs/gateway.log"

یہ process startup مسائل، غلط executable paths، MCP handshake failures یا reverse-proxy configuration کے مسائل کی تشخیص میں مفید ہے۔

اعلیٰ درجے کی تجاویز

قابل نقل paths استعمال کریں

مشین کے لیے مخصوص absolute paths کے بجائے ${HOME} اور ${APP_DATA_DIR} جیسے interpolated paths کو ترجیح دیں۔ Windows پر ضرورت کے مطابق %USERPROFILE% استعمال کیا جا سکتا ہے۔ اس سے مختلف systems کے درمیان configuration شیئر کرنا آسان ہو جاتا ہے۔

Plugins کو source checkout سے باہر رکھیں

بیرونی MCP packages کو $XDG_DATA_HOME/mcp-gateway میں انسٹال کریں۔ اس سے source tree صاف رہتا ہے اور گیٹ وے اور اس کی business extensions کو آزادانہ طور پر upgrade کیا جا سکتا ہے۔

اندرونی اور بیرونی addresses الگ رکھیں

گیٹ وے کو 127.0.0.1 پر bind کرنے سے اندرونی listener مقامی رہتا ہے۔ اس کے بعد reverse proxy بیرونی TLS endpoint فراہم کر سکتا ہے۔ یقینی بنائیں کہ forwarded headers عوامی scheme، host اور port کی درست عکاسی کریں تاکہ تیار کردہ OpenAPI دستاویزات درست URL ظاہر کریں۔

Hot updates سے فائدہ اٹھائیں

Blue-green session pool سروس sessions کو تبدیل کرتا ہے اور اس منتقلی کو AsyncMutex کے ذریعے محفوظ رکھتا ہے۔ یہ ڈیزائن پہلے سے جاری requests کو ختم کیے بغیر configuration updates کی اجازت دیتا ہے۔ Hot reloading اور lifecycle self-healing دستی process management کی ضرورت مزید کم کرتے ہیں۔

Deployment کے لیے compile کریں

جب target server پر Bun یا project dependencies انسٹال کرنا مطلوب نہ ہو تو bun run build استعمال کریں۔ تیار کردہ executable کو مطلوبہ XDG configuration اور الگ سے manage کیے جانے والے MCP binaries یا packages کے ساتھ deploy کریں۔

نتیجہ

Open MCP Gateway مقامی MCP services سے strict OpenAPI 3.1.0 routes تک ایک متحد bridge فراہم کرتا ہے۔ Multi-transport support، portable XDG-based configuration، external plugin management، reverse-proxy awareness اور standalone builds کو یکجا کر کے یہ مقامی MCP tools کو Open WebUI اور دیگر OpenAPI-capable clients کے لیے دستیاب بنانے کا عملی طریقہ فراہم کرتا ہے۔