Integrare un'app di App Service come server MCP per GitHub Copilot Chat (Spring Boot)

In questa esercitazione si apprenderà come esporre le funzionalità di un'app Web Spring Boot tramite il protocollo MCP (Model Context Protocol), aggiungerlo come strumento a GitHub Copilot e interagire con l'app usando il linguaggio naturale in modalità agente di Copilot Chat.

Se l'applicazione Web dispone già di funzionalità utili, ad esempio shopping, prenotazione hotel o gestione dei dati, è facile rendere disponibili queste funzionalità per:

• Qualsiasi applicazione che supporta l'integrazione MCP, ad esempio la modalità agente di Chat di GitHub Copilot in Visual Studio Code o in GitHub Codespaces.
• Agente personalizzato che accede a strumenti remoti tramite un client MCP.

Aggiungendo un server MCP all'app Web, si abilita un agente per comprendere e usare le funzionalità dell'app quando risponde alle richieste degli utenti. Ciò significa che qualsiasi operazione che l'app può fare, anche l'agente può fare.

• Aggiungere un server MCP alla web app.
• Testare il server MCP in locale in modalità agente Chat di GitHub Copilot.
• Distribuire il server MCP nel servizio app di Azure e connetterlo in GitHub Copilot Chat.

Prerequisites

Questa esercitazione presuppone che si stia usando l'esempio usato in Esercitazione: Creare un'app Web Java Spring Boot con il servizio app di Azure in Linux e Azure Cosmos DB.

Aprire almeno l'applicazione di esempio in GitHub Codespaces e distribuire l'app eseguendo azd up.

Aggiungere un server MCP all'app Web

1. Nello spazio di codice aprire pom.xml e aggiungere il spring-ai-starter-mcp-server-webmvc pacchetto al progetto:

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

2. Aprire src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/TodoApplication.java. Per semplicità dello scenario, si aggiungerà qui tutto il codice del server MCP.

3. Alla fine di TodoApplication.java aggiungere la classe seguente.

   @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";
       }
   }
   

   Il codice precedente rende disponibili gli strumenti per Spring AI usando gli attributi specifici seguenti:

   • @Service: contrassegna TodoListToolService come servizio gestito da Spring.
   • @Tool: contrassegna un metodo come strumento chiamabile in Spring AI.
   • description: forniscono descrizioni leggibili per ogni strumento. Aiuta l'agente chiamante a comprendere come usare lo strumento.

   Questo codice duplica la funzionalità di src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java esistente, che non è necessaria, ma verrà mantenuto per semplicità. Una procedura consigliata consiste nello spostare la logica dell'app in una classe di servizio, quindi chiamare i metodi del servizio sia da TodoListController che da TodoListToolService.

4. In TodoApplication.java aggiungere il metodo seguente alla TodoApplication classe .

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

   Questo metodo fornisce gli strumenti in TodoListToolService come callback per Spring AI. Per impostazione predefinita, la configurazione automatica del server MCP nel pacchetto spring-ai-starter-mcp-server-webmvc collega automaticamente questi callback degli strumenti. Inoltre, per impostazione predefinita, l'endpoint del server MCP è <base-url>/sse.

5. Nella parte superiore di TodoApplication.java aggiungere le importazioni seguenti.

   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;
   

Testare il server MCP in locale

1. Nel terminale codespace eseguire l'applicazione con mvn spring-boot:run.

2. Selezionare Apri nel browser e quindi aggiungere un'attività.

   Lasciare Spring Boot in esecuzione. Il tuo endpoint server MCP è ora in esecuzione su http://localhost:8080/sse.

3. Nel codespace aprire Copilot Chat e quindi selezionare Modalità agente nella casella di richiesta.

4. Selezionare il pulsante Strumenti e quindi aggiungi altri strumenti nell'elenco a discesa.

   

5. Selezionare Aggiungi server MCP.

6. Selezionare HTTP (HTTP o Eventi inviati dal server).

7. In Immettere l'URL del server digitare http://localhost:8080/sse.

8. In Immettere l'ID server digitare todos-mcp o qualsiasi nome desiderato.

9. Selezionare Impostazioni area di lavoro.

10. Nella nuova finestra di chat di Copilot, digita qualcosa come "Mostrami i 'todos'."

11. Per impostazione predefinita, GitHub Copilot mostra una conferma di sicurezza quando si richiama un server MCP. Seleziona Continua.

    

    Verrà visualizzata una risposta che indica che la chiamata allo strumento MCP ha esito positivo.

    

Distribuire il server MCP su App Service

1. Tornare al terminale codespace, distribuire le modifiche eseguendo il commit delle modifiche (metodo GitHub Actions) o eseguendo azd up (metodo dell'interfaccia della riga di comando per sviluppatori di Azure).

2. Nell'output AZD trovare l'URL dell'app. L'URL è simile al seguente nell'output AZD:

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

3. Al termine di azd up, aprire .vscode/mcp.json. Modificare l'URL in <app-url>/sse.

4. Sopra la configurazione del server MCP modificata, selezionare Avvia.

   

5. Avviare una nuova finestra di Chat di GitHub Copilot. Dovrebbe essere possibile visualizzare, creare, aggiornare ed eliminare attività nell'agente Copilot.

Procedure consigliate per la sicurezza

Quando il server MCP viene chiamato da un agente basato su modelli linguistici di grandi dimensioni (LLM), prestare attenzione agli attacchi di prompt injection. Considerare le procedure consigliate per la sicurezza seguenti:

• Autenticazione e autorizzazione: proteggere il server MCP con l'autenticazione Microsoft Entra per garantire che solo gli utenti o gli agenti autorizzati possano accedere agli strumenti. Per una guida dettagliata, vedere Proteggere le chiamate MCP (Model Context Protocol) al Servizio app di Azure da Visual Studio Code con l'autenticazione di Microsoft Entra.
• Convalida e purificazione dell'input: il codice di esempio in questa esercitazione omette la convalida e la purificazione dell'input per semplicità e chiarezza. Negli scenari di produzione implementare sempre la convalida e la purificazione appropriate per proteggere l'applicazione. Per Spring, consultare Spring: Convalida dell'input del modulo.
• HTTPS: L'esempio si basa sul servizio app di Azure, che applica HTTPS per impostazione predefinita e fornisce certificati TLS/SSL gratuiti per crittografare i dati in transito.
• Principio dei privilegi minimi: esporre solo gli strumenti e i dati necessari per il caso d'uso. Evitare di esporre operazioni sensibili, a meno che non sia necessario.
• Limitazione della frequenza e controllo della larghezza di banda: usare Gestione API o middleware personalizzato per evitare attacchi denial-of-service e abusi.
• Registrazione e monitoraggio: accesso e utilizzo dei log degli endpoint MCP per il controllo e il rilevamento delle anomalie. Monitorare l'attività sospetta.
• Configurazione CORS: limitare le richieste tra le origini ai domini attendibili se si accede al server MCP dai browser. Per altre informazioni, vedere Abilitare CORS.
• Aggiornamenti regolari: mantenere aggiornate le dipendenze per attenuare le vulnerabilità note.

Altre risorse

• Integrare l'intelligenza artificiale nelle applicazioni del servizio app di Azure
• Spring AI: Boot Starter per il server MCP