مشاركة عبر

دمج تطبيق App Service كخادم MCP ل GitHub Copilot Chat (Spring Boot)

في هذا البرنامج التعليمي، ستتعلم كيفية كشف وظائف تطبيق ويب Spring Boot من خلال بروتوكول سياق النموذج (MCP)، وإضافته كأداة إلى GitHub Copilot، والتفاعل مع تطبيقك باستخدام اللغة الطبيعية في وضع وكيل Copilot Chat.

لقطة شاشة تظهر GitHub Copilot يتصل بخادم Todos MCP المستضاف في Azure App Service.

إذا كان تطبيق الويب الخاص بك يحتوي بالفعل على ميزات مفيدة، مثل التسوق أو حجز الفنادق أو إدارة البيانات، فمن السهل إتاحة هذه الإمكانات من أجل:

  • أي تطبيق يدعم تكامل MCP، مثل وضع عامل GitHub Copilot Chat في Visual Studio Code أو في GitHub Codespaces.
  • عامل مخصص يصل إلى الأدوات البعيدة باستخدام عميل MCP.

من خلال إضافة خادم MCP إلى تطبيق الويب الخاص بك، يمكنك تمكين عامل لفهم قدرات التطبيق واستخدامها عندما يستجيب لمطالبات المستخدم. وهذا يعني أن أي شيء يمكن لتطبيقك القيام به، يمكن للعامل القيام به أيضا.

  • إضافة خادم MCP إلى تطبيق الويب الخاص بك.
  • اختبر خادم MCP محليا في وضع عامل GitHub Copilot Chat.
  • انشر خادم MCP إلى Azure App Service واتصل به في GitHub Copilot Chat.

Prerequisites

يفترض هذا البرنامج التعليمي أنك تعمل مع العينة المستخدمة في البرنامج التعليمي: إنشاء تطبيق ويب Java Spring Boot باستخدام Azure App Service على Linux وAzure Cosmos DB.

كحد أدنى، افتح نموذج التطبيق في GitHub Codespaces ونشر التطبيق عن طريق تشغيل azd up.

إضافة خادم MCP إلى تطبيق الويب الخاص بك

  1. في مساحة التعليمات البرمجية، افتح pom.xml وأضف الحزمة spring-ai-starter-mcp-server-webmvc إلى مشروعك:

    <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>1.0.0</version>
</dependency>

  2. Open src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/TodoApplication.java. لتبسيط السيناريو، ستضيف جميع التعليمات البرمجية لخادم MCP هنا.

  3. في نهاية TodoApplication.java، أضف الفئة التالية.

    @Service
class TodoListToolService {
    private final TodoItemRepository todoItemRepository;

    public TodoListToolService(TodoItemRepository todoItemRepository) {
        this.todoItemRepository = todoItemRepository;
    }

    @Tool(description = "Get a todo item by its id")
    public Optional<TodoItem> getTodoItem(String id) {
        return todoItemRepository.findById(id);
    }

    @Tool(description = "Get all todo items")
    public List<TodoItem> getAllTodoItems() {
        return todoItemRepository.findAll();
    }

    @Tool(description = "Add a new todo item")
    public String addNewTodoItem(String description, String owner) {
        TodoItem item = new TodoItem(UUID.randomUUID().toString(), description, owner);
        todoItemRepository.save(item);
        return "Todo item created";
    }

    @Tool(description = "Update an existing todo item")
    public String updateTodoItem(String id, String description, String owner, boolean finished) {
        if (!todoItemRepository.existsById(id)) {
            return "Todo item not found";
        }
        TodoItem item = new TodoItem(id, description, owner);
        item.setFinish(finished);
        todoItemRepository.save(item);
        return "Todo item updated";
    }

    @Tool(description = "Delete a todo item by its id")
    public String deleteTodoItem(String id) {
        if (!todoItemRepository.existsById(id)) {
            return "Todo item not found";
        }
        todoItemRepository.deleteById(id);
        return "Todo item deleted";
    }
}

    توفر التعليمات البرمجية أعلاه الأدوات ل Spring الذكاء الاصطناعي باستخدام السمات المحددة التالية:

    • @Service: وضع علامات TodoListToolService كخدمة مدارة بواسطة Spring.
    • @Tool: وضع علامة على أسلوب كأداة قابلة للاستدعاء في Spring الذكاء الاصطناعي.
    • description: توفر أوصافا يمكن للبشر قراءتها لكل أداة. يساعد عامل الاستدعاء على فهم كيفية استخدام الأداة.

    تقوم هذه التعليمات البرمجية بتكرار وظائف src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java الحالية، وهو أمر غير ضروري، ولكنك ستحتفظ به من أجل التبسيط. من أفضل الممارسات نقل منطق التطبيق إلى فئة خدمة، ثم استدعاء أساليب الخدمة من TodoListController وإلى TodoListToolService.

  4. في TodoApplication.java ، أضف الطريقة التالية إلى TodoApplication الفصل.

    @Bean
public ToolCallbackProvider todoTools(TodoListToolService todoListToolService) {
    return MethodToolCallbackProvider.builder().toolObjects(todoListToolService).build();
}

    يوفر هذا الأسلوب الأدوات في TodoListToolService كرد اتصال ل Spring الذكاء الاصطناعي. بشكل افتراضي، يقوم التكوين التلقائي لخادم MCP في الحزمة spring-ai-starter-mcp-server-webmvc تلقائيا بربط عمليات الاسترجاع هذه للأداة. أيضا، بشكل افتراضي، نقطة نهاية خادم MCP هي <base-url>/sse.

  5. في الجزء العلوي من TodoApplication.java، أضف عمليات الاستيراد التالية.

    import java.util.List;
import java.util.Optional;
import java.util.UUID;

import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Service;

import com.microsoft.azure.appservice.examples.springbootmongodb.dao.TodoItemRepository;
import com.microsoft.azure.appservice.examples.springbootmongodb.model.TodoItem;

اختبار خادم MCP محليا

  1. في الوحدة الطرفية لمساحة التعليمات البرمجية، قم بتشغيل التطبيق باستخدام mvn spring-boot:run.

  2. حدد فتح في المستعرض، ثم أضف مهمة.

    اترك Spring Boot قيد التشغيل. نقطة نهاية خادم MCP قيد التشغيل الآن http://localhost:8080/sse .

  3. مرة أخرى في مساحة التعليمات البرمجية، افتح دردشة Copilot، ثم حدد وضع الوكيل في مربع المطالبة.

  4. حدد الزر أدوات ، ثم حدد إضافة المزيد من الأدوات... في القائمة المنسدلة.

    لقطة شاشة توضح كيفية إضافة خادم MCP في وضع عامل GitHub Copilot Chat.

  5. حدد إضافة خادم MCP.

  6. حدد HTTP (HTTP أو Server-Sent Events).

  7. في Enter Server URL، اكتب http://localhost:8080/sse.

  8. في Enter Server ID، اكتب todos-mcp أو أي اسم تريده.

  9. حدد إعدادات مساحة العمل.

  10. في نافذة Copilot Chat جديدة، اكتب شيئا مثل "Show me the todos".

  11. بشكل افتراضي، يعرض لك GitHub Copilot تأكيد أمان عند استدعاء خادم MCP. حدد متابعة.

    لقطة شاشة تعرض رسالة الأمان الافتراضية من استدعاء MCP في GitHub Copilot Chat.

    يجب أن تشاهد الآن استجابة تشير إلى نجاح استدعاء أداة MCP.

    لقطة شاشة توضح أن الاستجابة من استدعاء أداة MCP في نافذة GitHub Copilot Chat.

نشر خادم MCP إلى App Service

  1. مرة أخرى في الوحدة الطرفية لمساحة التعليمات البرمجية، انشر التغييرات الخاصة بك عن طريق تنفيذ التغييرات (أسلوب GitHub Actions) أو تشغيل azd up (أسلوب Azure Developer CLI).

  2. في إخراج AZD، ابحث عن عنوان URL لتطبيقك. يبدو عنوان URL كما يلي في إخراج AZD:

     Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <app-url>

  3. بمجرد azd up الانتهاء ، افتح .vscode/mcp.json. تغيير عنوان URL إلى <app-url>/sse.

  4. أعلى تكوين خادم MCP المعدل، حدد ابدأ.

    لقطة شاشة توضح كيفية بدء تشغيل خادم MCP يدويا من ملف mcp.json المحلي.

  5. ابدأ نافذة GitHub Copilot Chat جديدة. يجب أن تكون قادرا على عرض المهام وإنشاءها وتحديثها وحذفها في عامل Copilot.

أفضل الممارسات الأمنية

عندما يتم استدعاء خادم MCP الخاص بك بواسطة وكيل مدعوم بنماذج لغوية كبيرة (LLM)، كن على دراية بهجمات الحقن الفوري . ضع في اعتبارك أفضل ممارسات الأمان التالية:

  • المصادقة والتفويض: قم بتأمين خادم MCP الخاص بك باستخدام مصادقة Microsoft Entra لضمان وصول المستخدمين أو الوكلاء المصرح لهم فقط إلى أدواتك. انظر استدعاءات بروتوكول السياق الآمن إلى Azure App Service من Visual Studio Code with Microsoft Entra Authentication للحصول على دليل خطوة بخطوة.
  • التحقق من صحة الإدخال وتعقيمه: يحذف مثال التعليمات البرمجية في هذا البرنامج التعليمي التحقق من صحة الإدخال وتعقيمه للبساطة والوضوح. في سيناريوهات الإنتاج، قم دائما بتنفيذ التحقق الصحيح والتعقيم لحماية التطبيق الخاص بك. بالنسبة إلى Spring، راجع Spring: التحقق من صحة إدخال النموذج.
  • HTTPS: يعتمد النموذج على Azure App Service، الذي يفرض HTTPS بشكل افتراضي ويوفر شهادات TLS/SSL مجانية لتشفير البيانات أثناء النقل.
  • مبدأ الامتياز الأقل: يعرض فقط الأدوات والبيانات الضرورية المطلوبة لحالة الاستخدام الخاصة بك. تجنب الكشف عن العمليات الحساسة ما لم يكن ذلك ضروريا.
  • تحديد المعدل والتقييد: استخدم إدارة واجهة برمجة التطبيقات أو البرامج الوسيطة المخصصة لمنع إساءة الاستخدام وهجمات رفض الخدمة.
  • التسجيل والمراقبة: الوصول إلى السجل واستخدام نقاط نهاية MCP للتدقيق والكشف عن الحالات الشاذة. مراقبة النشاط المشبوه.
  • تكوين CORS: تقييد الطلبات عبر الأصل بالمجالات الموثوق بها إذا تم الوصول إلى خادم MCP الخاص بك من المستعرضات. لمزيد من المعلومات، راجع تمكين CORS.
  • تحديثات منتظمة: حافظ على تحديث تبعياتك للتخفيف من الثغرات الأمنية المعروفة.

موارد إضافية

  • Last updated on