الشرح: استخدم MCP مع الجلسات الديناميكية (shell)

مهم

خادم MCP المدار على المنصة للجلسات الديناميكية في مرحلة المعاينة. نسخة 2025-02-02-preview API وخصائصها mcpServerSettings قابلة للتغيير.

يوضح هذا الدرس كيفية إنشاء تجمع جلسات shell مع تفعيل خادم MCP المدار من المنصة، والاتصال به، وتنفيذ أوامر الشل عن بعد - سواء من CLI أو من GitHub Copilot Chat في VS Code.

على عكس دروس خوادم MCP المستقلة، لا تكتب أو تنشر كود خادم MCP. توفر المنصة أدوات مدمجة لتجمع جلسات الشل:

أداة وصف
launchShell ينشئ بيئة صدفة جديدة ويعيد environmentId
runShellCommandInRemoteEnvironment ينفذ أمر shell في بيئة موجودة

في هذا البرنامج التعليمي، سوف تتعلّم:

  • إنشاء تجمع جلسات shell مع تفعيل خادم MCP
  • استرجاع نقطة نهاية MCP ومفتاح API
  • قم بتهيئة اتصال MCP وتشغيل أوامر shell عبر JSON-RPC
  • توصيل خادم MCP ب GitHub Copilot في كود VS

Prerequisites

Requirement وصف
حساب Azure حساب Azure مع اشتراك نشط. أنشئ واحدا مجانا.
Azure CLI قم بتثبيت Azure CLI.
حليقه Curl (مثبت مسبقا على معظم أنظمة لينكس وmacOS).
jq جي كيو معالج JSON، يستخدم لتحليل استجابات واجهة برمجة التطبيقات (API).
كود VS كود Visual Studio مع امتداد GitHub Copilot (لقسم تكامل Copilot).

الإعداد

  1. قم بتحديث واجهة برمجة Azure وتثبيت إضافة تطبيقات الحاويات:

    az upgrade
az provider register --namespace Microsoft.App
az extension add --name containerapp --allow-preview true --upgrade

  2. سجل الدخول وحدد اشتراكك:

    az login
SUBSCRIPTION_ID=$(az account show --query id --output tsv)
az account set -s $SUBSCRIPTION_ID

  3. حدد المتغيرات لهذا الدرس. استبدل البدلاء بقيمك:

    RESOURCE_GROUP=<RESOURCE_GROUP_NAME>
SESSION_POOL_NAME=<SESSION_POOL_NAME>
LOCATION=<LOCATION>
    Placeholder وصف
    <RESOURCE_GROUP_NAME> اسم مجموعة موارد Azure.
    <SESSION_POOL_NAME> اسم مجموعة الجلسات الخاصة بك (على سبيل المثال، my-shell-sessions).
    <LOCATION> منطقة Azure تدعم الجلسات الديناميكية (على سبيل المثال، westus2).

  4. أنشئ مجموعة موارد:

    az group create --name $RESOURCE_GROUP --location $LOCATION

إنشاء تجمع جلسات shell باستخدام خادم MCP

نشر مجموعة جلسات باستخدام قالب ARM مع تفعيل خادم MCP.

  1. أنشئ ملفا باسم deploy.json:

    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "name": { "type": "String" },
        "location": { "type": "String" }
    },
    "resources": [
        {
            "type": "Microsoft.App/sessionPools",
            "apiVersion": "2025-02-02-preview",
            "name": "[parameters('name')]",
            "location": "[parameters('location')]",
            "properties": {
                "poolManagementType": "Dynamic",
                "containerType": "Shell",
                "scaleConfiguration": {
                    "maxConcurrentSessions": 5
                },
                "sessionNetworkConfiguration": {
                    "status": "EgressEnabled"
                },
                "dynamicPoolConfiguration": {
                    "lifecycleConfiguration": {
                        "lifecycleType": "Timed",
                        "coolDownPeriodInSeconds": 300
                    }
                },
                "mcpServerSettings": {
                    "isMCPServerEnabled": true
                }
            }
        }
    ]
}

    ‏‫ملاحظة‬

    الخصائص الرئيسية في هذا القالب:

    • containerType: "Shell" — ينشئ جلسات مع بيئة shell على لينكس.
    • mcpServerSettings.isMCPServerEnabled: true — تمكن نقطة نهاية MCP المدارة على المنصة.
    • coolDownPeriodInSeconds: 300 — يتم تدمير الجلسات بعد 5 دقائق من عدم النشاط.

  2. نشر القالب:

    az deployment group create \
  --resource-group $RESOURCE_GROUP \
  --template-file deploy.json \
  --parameters name=$SESSION_POOL_NAME location=$LOCATION

احصل على نقطة نهاية خادم MCP

بعد النشر، استرجع رابط نقطة نهاية MCP لمجموعة الجلسات الخاصة بك.

MCP_ENDPOINT=$(az rest --method GET --uri "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionPools/$SESSION_POOL_NAME?api-version=2025-10-02-preview" --query "properties.mcpServerSettings.mcpServerEndpoint" -o tsv)

احصل على بيانات اعتماد خادم MCP

يستخدم خادم MCP المدار من قبل المنصة مصادقة مفاتيح API عبر الرأس x-ms-apikey . يختلف هذا النهج عن مصادقة حامل الرموز التي تستخدمها واجهات برمجة تطبيقات إدارة تجمع الجلسات القياسية.

API_KEY=$(az rest --method POST --uri "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionPools/$SESSION_POOL_NAME/fetchMCPServerCredentials?api-version=2025-10-02-preview" --query "apiKey" -o tsv)

تحذير

عامل مفتاح واجهة برمجة التطبيقات كسر. لا تلتزم به للتحكم في المصدر أو تشاركه علنا. يقوم المفتاح بالتحقق من جميع استدعاءات أدوات MCP مقابل مجموعة الجلسات الخاصة بك.

تهيئة خادم MCP

أرسل initialize طلب JSON-RPC لتأسيس اتصال MCP:

curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{ "jsonrpc": "2.0", "id": "1", "method": "initialize" }'

يجب أن ترى ردا يشمل:

  • protocolVersion 2025-03-26
  • serverInfo.name Microsoft Container Apps MCP Server
  • capabilities.tools { "call": true, "list": true }

إطلاق بيئة shell

أنشئ بيئة shell جديدة لتشغيل الأوامر.

ENVIRONMENT_RESPONSE=$(curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{ "jsonrpc": "2.0", "id": "2", "method": "tools/call", "params": { "name": "launchShell", "arguments": {} } }')

echo $ENVIRONMENT_RESPONSE

استخرج من environmentId الاستجابة لاستخدامها في الأوامر اللاحقة.

ENVIRONMENT_ID=$(echo $ENVIRONMENT_RESPONSE | jq -r '.result.structuredContent.environmentId')
echo $ENVIRONMENT_ID

تنفيذ أوامر الshell

استخدم الخطوة $ENVIRONMENT_ID السابقة لتشغيل الأوامر في بيئة الشل البعيد.

curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{
        "jsonrpc": "2.0",
        "id": "3",
        "method": "tools/call",
        "params": {
            "name": "runShellCommandInRemoteEnvironment",
            "arguments": {
                "environmentId": "'"$ENVIRONMENT_ID"'",
                "shellCommand": "echo Hello from Azure Container Apps Shell Session!"
            }
        }
    }'

يشمل الرد نتائج stdout أوامر في الميدان.

جرب أوامر إضافية:

# Check the operating system
curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{
        "jsonrpc": "2.0",
        "id": "4",
        "method": "tools/call",
        "params": {
            "name": "runShellCommandInRemoteEnvironment",
            "arguments": {
                "environmentId": "'"$ENVIRONMENT_ID"'",
                "shellCommand": "cat /etc/os-release && uname -a"
            }
        }
    }'

‏‫ملاحظة‬

تقبل الأداة runShellCommandInRemoteEnvironment إما سلسلة shellCommand أو execCommandAndArgs مصفوفة للأوامر التي تحتوي على وسيطجات. استخدمها shellCommand للأوامر البسيطة وعندما execCommandAndArgs تحتاج إلى تحكم دقيق في هروب الحجة.

الاتصال ب GitHub Copilot في كود VS

يمكنك توصيل خادم MCP الخاص بمجموعة الجلسات ب GitHub Copilot لواجهة لغة طبيعية إلى بيئة تنفيذ الshell.

  1. أنشئ .vscode/mcp.json في مشروعك:

    {
    "servers": {
        "aca-shell-sessions": {
            "type": "http",
            "url": "<MCP_ENDPOINT>",
            "headers": {
                "x-ms-apikey": "<API_KEY>"
            }
        }
    }
}

    استبدل <MCP_ENDPOINT> و <API_KEY> بالقيم من الخطوات السابقة.

    تحذير

    لا تلتزم مفاتيح واجهة برمجة التطبيقات MCP بالتحكم في المصدر. استخدم متغيرات البيئة أو مدير الأسرار في الإنتاج. أضف .vscode/mcp.json إلى ..gitignore

  2. افتح VS Code، ثم افتح دردشة Copilot في وضع الوكيل .

  3. يظهر التحقق aca-shell-sessions في قائمة الأدوات.

  4. اختبر مع محفزات مثل:

    • "شغل قشرة وأظهر لي استخدام القرص"
    • "تشغيل أمر shell لسرد جميع متغيرات البيئة"
    • "تحقق من الحزم المثبتة في بيئة الهيكل"

تنظيف الموارد

عندما تنتهي من هذا الدرس، قم بإزالة الموارد التي أنشأتها لتجنب تحمل الرسوم.

az group delete --resource-group $RESOURCE_GROUP

المحتوى ذو الصلة

  • Last updated on