MCP ইন্টিগ্রেশন নির্দেশিকা

অনুমোদিত লগইনের ফলাফল ফেরত দেওয়া

SDK ইনস্টল করুন:

pnpm add mcp-auth-web

API পরিবেশ (engineUrl হলো পাথ ছাড়া মূল ঠিকানা):

পরীক্ষা: https://aim-api-test.proton-system.com
প্রোডাকশন: https://aim-api.proton-system.com

অনুমোদন ফেরত দেওয়ার সম্পূর্ণ URL: https://xxx.com/openapi/v1/mcp/authorization/callback

SDK স্বয়ংক্রিয়ভাবে পাথ যোগ করে।

লগইন সফল হলে ক্রেডেনশিয়াল ফেরত দিন:

import { createMcpAuthClient } from 'mcp-auth-web'

const mcpAuth = createMcpAuthClient({
  engineUrl: 'https://aim-api-test.proton-system.com',
})

mcpAuth.complete({
  Authorization: `Bearer ${token}`,
})

লগইন ব্যর্থ হলে বা ব্যবহারকারী বাতিল করলে:

mcpAuth.fail({ code, message })
mcpAuth.cancel()

mcp-auth-web@0.3.1 থেকে getMcpAuthErrorMessage(error) SDK-পরিচালিত নিরাপদ ডিফল্ট চীনা বার্তা দেয়। UI বার্তা দেখায়; অনুবাদ বা কাস্টমাইজেশনের জন্য ত্রুটি কোড ব্যবহার করুন। complete(), fail() ও cancel()-এর ত্রুটি ধরুন। complete()-এর catch থেকে নিঃশর্তভাবে fail() কল করবেন না এবং মূল ত্রুটির ক্রেডেনশিয়াল বা অনুমোদনের URL প্রকাশ করবেন না।

import { getMcpAuthErrorMessage } from 'mcp-auth-web'

try {
  mcpAuth.complete({ Authorization: `Bearer ${token}` })
} catch (error) {
  message.error(getMcpAuthErrorMessage(error))
}

engineUrl হলো প্ল্যাটফর্মের দেওয়া Engine ঠিকানা। complete সরাসরি MCP-এর ব্যবহৃত ক্রেডেনশিয়াল Header গ্রহণ করে। SDK Authorization-এর Bearer JWT থেকে exp পড়ে স্বয়ংক্রিয়ভাবে expiresAt তৈরি করে, তাই মেয়াদ আলাদাভাবে দিতে হয় না।

SDK স্বয়ংক্রিয়ভাবে HTTPS callback বা বিদ্যমান App অনুমোদন উইন্ডো বেছে নেয়। mcp-auth-web@0.3.0-এ complete-এর ইনপুট ফরম্যাট বদলেছে; আপগ্রেডের সময় headers wrapper এবং হাতে দেওয়া expiresAt সরিয়ে দিন। engineUrl না দিলে বিদ্যমান App অনুমোদন উইন্ডো ব্যবহার করা চলতে থাকবে।

মেথড false দিলে বর্তমান পেজে অনুমোদন ফেরানোর কোনো উপায় নেই:

if (!mcpAuth.isAvailable()) {
  message.error('বর্তমান পরিবেশ অনুমোদনের ফলাফল ফেরত দেওয়া সমর্থন করে না')
}

যাচাই করতে App থেকে অনুমোদন শুরু করে লগইন শেষ করুন। App-এ ফিরে “অনুমোদিত” দেখালে ইন্টিগ্রেশন সফল। প্রোডাকশনে লগইন পেজ ও Engine-এ ডিভাইস থেকে ব্যবহারযোগ্য HTTPS এবং বৈধ সার্টিফিকেট প্রয়োজন। ক্রেডেনশিয়াল বা অনুমোদন URL লগ করবেন না।

Tool-এর সাধারণ ঝুঁকি অ্যানোটেশন

পঠন Tool:

annotations: {
  readOnlyHint: true
}

লেখার Tool:

annotations: {
  destructiveHint: true
}

Tool-এর ধরন

1. তালিকা Tool

কোনো Tool যদি প্রার্থীর তালিকা ফেরত দেয় এবং ব্যবহারকারীর নির্বাচিত মান অন্য Tool-এর প্যারামিটারে বসে, তাহলে outputSchema-এর রুটে নিচের অবজেক্টটি যোগ করুন:

outputSchema: {
  type: "object",
  properties: {...}, // ঐচ্ছিক
  "x-prerequisiteCandidate": {
    itemsPath: "data",
    valuePath: "id",
    labelPath: "name"
  }
}

তিনটি ফিল্ডের অর্থ:

itemsPath: Tool-এর ফলাফলে প্রার্থীর অ্যারে কোথায় আছে।
valuePath: প্রতিটি প্রার্থীর কোন ফিল্ডটি চূড়ান্ত মান হবে।
labelPath: প্রতিটি প্রার্থীর কোন ফিল্ডটি ব্যবহারকারীকে দেখানো হবে।

উদাহরণ হিসেবে Tool ফেরত দেয়:

{
  "data": [
    { "id": "1", "name": "স্টোর A" },
    { "id": "2", "name": "স্টোর B" }
  ]
}

তাহলে:

itemsPath: "data" বোঝায় প্রার্থীর তালিকাটি ফলাফলের data অ্যারে।
valuePath: "id" বোঝায় নির্বাচিত আইটেমের id লক্ষ্য Tool-এ বসবে।
labelPath: "name" বোঝায় নির্বাচন কার্ডে আইটেমের name দেখাবে।

যাচাই তালিকা