মূল কনটেন্টে যান
এআই টিউটোরিয়াল

Open MCP Gateway দিয়ে স্থানীয় MCP সার্ভিসের জন্য OpenAPI গেটওয়ে তৈরি করুন

Open MCP Gateway ইনস্টল করা, স্থানীয় MCP সার্ভিস কনফিগার করা, OpenAPI-সামঞ্জস্যপূর্ণ রুট তৈরি করা, Open WebUI-এর সঙ্গে ইন্টিগ্রেট করা, বাহ্যিক প্লাগইন পরিচালনা করা, লগ পর্যবেক্ষণ করা এবং গেটওয়েটিকে স্বতন্ত্র নেটিভ এক্সিকিউটেবলে কম্পাইল করা শিখুন।

পড়তে প্রায় 20 মিনিট লাগবে
Open MCP Gateway দিয়ে স্থানীয় MCP সার্ভিসের জন্য OpenAPI গেটওয়ে তৈরি করুন

Open MCP Gateway কী?

Open MCP Gateway, সংক্ষেপে OMG, একটি উচ্চ-ক্ষমতাসম্পন্ন গেটওয়ে যা OpenAPI 3.1.0-সম্মত HTTP REST রুটের মাধ্যমে স্থানীয়ভাবে ডিপ্লয় করা Model Context Protocol পরিষেবাগুলো উন্মুক্ত করে। এটি 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>

ইনস্টলেশনের পর, স্ক্রিপ্টের stdio উদাহরণে দেখানো অনুযায়ী ${APP_DATA_DIR} ব্যবহার করে config.json5-এ প্যাকেজের entry point উল্লেখ করুন। এতে gateway-এর নির্ভরতা MCP extension-এর নির্ভরতা থেকে আলাদা থাকে.

মৌলিক ব্যবহার

  1. Gateway-এর নির্ভরতাগুলো ইনস্টল করুন অথবা native executable তৈরি করুন.

  2. $XDG_CONFIG_HOME/mcp-gateway/config.json5 তৈরি করুন.

  3. mcpServers-এর অধীনে এক বা একাধিক service যোগ করুন.

  4. bun run dev দিয়ে gateway চালু করুন অথবা compiled executable চালান.

  5. কনফিগার করা service-এর OpenAPI document সংগ্রহ করে আপনার external client-এ নিবন্ধন করুন.

codebase_memory নামের একটি service-এর জন্য নথিভুক্ত OpenAPI URL-এর ধরন হলো:

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

এই উদাহরণে 8444 হলো বাইরে থেকে অ্যাক্সেসযোগ্য port। এটি gateway-এর অভ্যন্তরীণ port-এর পরিবর্তে reverse-proxy port হতে পারে, যেমন configuration উদাহরণের 9090.

Open WebUI-এর সঙ্গে একীভূতকরণ

Caddy বা Nginx-এর মতো একটি reverse proxy gateway-কে নির্ধারিত external host, port এবং protocol-এর মাধ্যমে প্রকাশ করতে পারে। উপযুক্ত X-Forwarded-* header পাঠানোর জন্য proxy কনফিগার করুন। Open MCP Gateway OpenAPI document তৈরি করার সময় এই header পড়ে, ফলে এর servers.url internal listener-এর পরিবর্তে public address নির্দেশ করে.

  1. Reverse proxy-এর পেছনে Open MCP Gateway চালু করুন.

  2. Open WebUI-এর administration panel খুলুন.

  3. Functions, Tools অথবা OpenAPI এলাকায় যান.

  4. প্রতিটি কনফিগার করা MCP service-এর OpenAPI document URL নিবন্ধন করুন:

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

  5. Open WebUI-কে specification লোড করার অনুমতি দিন। এরপর তৈরি করা OpenAPI operation-এর মাধ্যমে MCP service-এর tools native tools হিসেবে ব্যবহার করা যাবে.

Operation ID-গুলো মূল MCP tool-এর নাম অপরিবর্তিত রাখায়, gateway-তৈরি suffix বা prefix ছাড়াই client-এ পরিষ্কার tool identifier দেখা যায়.

পরীক্ষা ও লগ পর্যবেক্ষণ

Gateway বা এর configuration পরিবর্তন করার পর প্রকল্পের test command চালান:

bun run test

Windows-এ repository একটি PowerShell test script-ও সরবরাহ করে:

.\ps1_scripts\test-gateway.ps1

End-to-end assertion-গুলো health check, MCP handshake এবং proxy origin alignment যাচাই করে.

Unix-এর মতো system-এ persistent gateway log অনুসরণ করুন:

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

Process startup সমস্যা, ভুল executable path, MCP handshake ব্যর্থতা অথবা reverse-proxy configuration সমস্যা নির্ণয়ের সময় এটি উপযোগী.

উন্নত পরামর্শ

Portable path ব্যবহার করুন

Machine-specific absolute path-এর পরিবর্তে ${HOME} এবং ${APP_DATA_DIR}-এর মতো interpolated path ব্যবহার করুন। Windows-এ প্রয়োজনে %USERPROFILE% ব্যবহার করা যায়। এতে বিভিন্ন system-এ configuration শেয়ার করা সহজ হয়.

Plugin-গুলো source checkout-এর বাইরে রাখুন

External MCP package-গুলো $XDG_DATA_HOME/mcp-gateway-এ ইনস্টল করুন। এতে source tree পরিষ্কার থাকে এবং gateway ও এর business extension স্বাধীনভাবে upgrade করা যায়.

Internal ও external address আলাদা রাখুন

Gateway-কে 127.0.0.1-এ bind করলে internal listener local থাকে। এরপর একটি reverse proxy external TLS endpoint সরবরাহ করতে পারে। Forwarded header-গুলোতে public scheme, host এবং port সঠিকভাবে উল্লেখ আছে কিনা নিশ্চিত করুন, যাতে তৈরি হওয়া OpenAPI document সঠিক URL প্রকাশ করে.

Hot update কাজে লাগান

Blue-green session pool service session অদলবদল করে এবং AsyncMutex দিয়ে transition সুরক্ষিত রাখে। এই নকশার ফলে ইতিমধ্যে চলমান request বন্ধ না করেই configuration update করা যায়। Hot reloading এবং lifecycle self-healing manual process management-এর প্রয়োজন আরও কমায়.

Deployment-এর জন্য compile করুন

Target server-এ Bun বা project dependency ইনস্টল করা প্রয়োজন না হলে bun run build ব্যবহার করুন। প্রয়োজনীয় XDG configuration এবং আলাদাভাবে পরিচালিত MCP binary বা package-সহ তৈরি executable deploy করুন.

উপসংহার

Open MCP Gateway local MCP service থেকে কঠোর OpenAPI 3.1.0 route-এ একটি একীভূত bridge সরবরাহ করে। Multi-transport support, portable XDG-based configuration, external plugin management, reverse-proxy awareness এবং standalone build একত্র করার মাধ্যমে এটি Open WebUI ও অন্যান্য OpenAPI-capable client-এ local MCP tool উপলভ্য করার একটি কার্যকর উপায় দেয়.