MCP Server e Telegram: Estendere gli Agenti AI con Strumenti Personalizzati

L’era dell’Intelligenza Artificiale Generativa ha reso gli Agenti uno strumento onnipresente. Per sfruttare appieno il loro potenziale, gli Agenti devono interagire con il mondo esterno, eseguendo azioni specifiche come inviare email, interrogare database o inviare notifiche. 

È qui che entra in gioco l’MCP (Model Context Protocol) Server, un framework che permette di esporre queste funzionalità in modo standardizzato e accessibile.

Questo articolo tecnico esplora il concetto di MCP Server, di cui abbiamo parlato nell’episodio dedicato del nostro podcast Bitrock Tech Radio e nel nostro articolo sulla Platform Shifting e i nuovi protocolli MCP e A2A , presentando un’implementazione pratica in TypeScript che crea un canale di comunicazione diretto verso un account Telegram personale.

Il Model Context Protocol (MCP)

Il Model Context Protocol (MCP) è un protocollo di comunicazione e un insieme di specifiche che definiscono un modo standardizzato per esporre strumenti, risorse e prompt agli LLM.

In sostanza, l’MCP funge da intermediario universale per:

  1. Standardizzazione: Definisce un formato comune per la descrizione delle funzionalità (strumenti).
  2. Accessibilità: Consente a qualsiasi agente AI compatibile di scoprire e invocare queste funzionalità in modo remoto.
  3. Estensibilità: Permette agli sviluppatori di integrare rapidamente nuove capacità (API personalizzate, servizi esterni, logica interna) nell’ecosistema degli agenti AI.

L’ MCP Server

Un MCP Server è un’applicazione che implementa il protocollo MCP. La sua funzione principale è registrare, descrivere ed eseguire i tool che espone. Quando un agente AI – il Client MCP come può essere Claude Desktop o un’IDE come VS Code – deve eseguire un’azione specifica, interroga l’MCP Server per ottenere una descrizione dei tool disponibili e successivamente invoca quello più appropriato, passando i parametri necessari.

Questo meccanismo è fondamentale per il tool-use o function calling degli LLM, consentendo loro di superare la limitazione di non poter interagire direttamente con il mondo reale.

Il Caso d’Uso: Note Programmatiche con Telegram

L’esempio pratico che analizziamo in questo articolo è la creazione di un MCP Server in TypeScript, il cui unico scopo è esporre un tool denominato send-note. Questo strumento permette di inviare messaggi (note) direttamente a un canale o una chat Telegram specifica, offrendo un meccanismo di notifica rapido e programmatico per script, processi o, ovviamente, altri agenti AI.

Il Ruolo del Bot Telegram

Per inviare messaggi a Telegram in modo programmatico, non è possibile utilizzare un account utente standard: è necessario creare un bot Telegram.

Un bot è un’applicazione che opera tramite l’API di Telegram.

  • Creazione: Un bot si crea facilmente tramite il bot ufficiale @BotFather su Telegram. Questo processo genera un Token API unico.
  • Identificazione: Per inviare un messaggio a un utente specifico, il bot ha bisogno del Chat ID (l’identificatore della conversazione tra l’utente e il bot).
  • Interazione: Tutte le operazioni avvengono inviando richieste HTTP al server API di Telegram, utilizzando il Token API per l’autenticazione.

La configurazione, come descritto nel file README.md del progetto, richiede due variabili d’ambiente essenziali per il funzionamento del server:

  • TELEGRAM_TOKEN: Per autenticare le richieste API del bot.
  • TELEGRAM_PERSONAL_CHAT_ID: Per specificare il destinatario del messaggio (l’utente).

Implementazione Tecnica in TypeScript

Il server è stato sviluppato in TypeScript, un superset tipizzato di JavaScript che apporta maggiore robustezza e manutenibilità al codice. L’utilizzo dell’SDK ufficiale di MCP facilita notevolmente l’implementazione del protocollo.

File index.ts

Il cuore del progetto risiede nel file index.ts. Analizziamo i passaggi chiave:

Inizializzazione del Server e del Transport

  1. McpServer: Viene importata la classe base per l’implementazione del server MCP. L’oggetto di configurazione definisce metadati importanti come name e version, che l’agente client utilizzerà per identificare e descrivere il server.
  2. StdioServerTransport: Il protocollo MCP definisce come le informazioni devono essere scambiate. In questo caso, viene scelto il StdioServerTransport, che utilizza i flussi di input/output standard (stdin/stdout) per la comunicazione. Questa è una modalità comune per i server che vengono eseguiti come processi child o integrati in ambienti di sviluppo locale come un IDE (ES: VS Code).

Definizione dello strumento send-note

L’operazione chiave è la registrazione del tool, che chiameremo send-note, utilizzando il metodo server.tool().

  1. Firma (Schema Zod): L’MCP Server utilizza la libreria Zod (z nell’esempio) per definire in modo rigoroso e tipizzato gli input che il tool si aspetta. In questo caso, è richiesto un unico parametro message che deve essere una stringa con una lunghezza minima di 1 e massima di 4096 caratteri (il limite standard di Telegram per i messaggi). Questa tipizzazione è essenziale per la capacità degli Agenti AI di costruire le chiamate di funzione corrette.
  2. Metadati (Hint): L’oggetto contenente title, readOnlyHint, destructiveHint, ecc., fornisce informazioni semantiche all’agente AI. L’impostazione openWorldHint: true indica che l’esecuzione di questo strumento può avere effetti esterni sul mondo (in questo caso, l’invio di un messaggio), un dettaglio cruciale per la logica decisionale dell’agente.

Esecuzione del tool

Il corpo della funzione async definisce la logica che viene eseguita quando il tool viene invocato:

  1. Costruzione dell’URL: La variabile d’ambiente TELEGRAM_API contiene l’URL di base per l’API di Telegram (che include il token del bot). La richiesta viene indirizzata al metodo /sendMessage.
  2. Chiamata fetch: Viene effettuata una richiesta POST con un payload JSON che include il chat_id (il destinatario, preso dalle variabili d’ambiente) e il text (il contenuto del messaggio, passato come parametro dal Client MCP).
  3. Gestione degli Errori: Il codice controlla il successo della risposta (if (!res.ok)). In caso di fallimento, restituisce un oggetto che include isError: true e un messaggio di errore leggibile (content), rispettando il formato di risposta standard dell’MCP. In caso di successo, restituisce il messaggio di conferma.

Integrazione delle Variabili d’Ambiente

Il file env.ts (implicito nell’uso di TELEGRAM_API e TELEGRAM_PERSONAL_CHAT_ID) è responsabile della lettura e della validazione delle credenziali sensibili dal file .env. Questo approccio disaccoppia la logica del server dalle configurazioni specifiche e assicura che le chiavi non vengano accidentalmente commesse nel controllo versione.

Architettura e flusso di lavoro

Per capire come l’MCP Server si inserisce nell’architettura più ampia, consideriamo il tipico flusso di lavoro:

  1. Avvio: L’MCP Server viene avviato (ad esempio, con npm start) ed è in ascolto sul canale StdioServerTransport.
  2. Scoperta (Client): Un Agente AI (Client MCP), come un modello LLM, si connette al server (o carica la sua descrizione del tool) e scopre l’esistenza del tool send-note, insieme alla sua descrizione e ai suoi parametri.
  3. Decisione (Agente AI): L’Agente AI riceve un prompt dall’utente, ad esempio: “Ricordami di chiamare la mamma domani mattina alle 9”. L’agente riconosce che l’azione appropriata è “inviare una nota” e costruisce la chiamata allo strumento send-note con il parametro message: “Ricordami di chiamare la mamma domani mattina alle 9”.
  4. Invocazione (MCP): L’Agente invia un messaggio di invocazione formattato via stdin all’MCP Server.
  5. Esecuzione (Server): L’MCP Server riceve il messaggio, estrae il parametro message e ne esegue il callback associato, che è la richiesta HTTP all’API di Telegram.
  6. Conferma (Server e Client): Il Server riceve la risposta da Telegram, la incapsula in una risposta MCP (successo/errore) e la invia all’Agente AI tramite stdout. L’Agente AI può quindi utilizzare questa conferma per informare l’utente.

Vantaggi e conclusioni

L’implementazione di un MCP Server per le notifiche Telegram dimostra la potenza e i vantaggi tecnologici apportati da questo protocollo, fra cui:

  • Tipizzazione Forte (TypeScript): La combinazione di TypeScript e Zod garantisce che i parametri di input siano convalidati prima di essere utilizzati, riducendo gli errori di runtime causati da input non validi provenienti da agenti AI o client.
  • Decoupling (Disaccoppiamento): L’Agente AI non deve conoscere l’API di Telegram, il Token, o il Chat ID. Deve solo conoscere la firma del tool send-note. L’MCP Server funge da livello di astrazione che gestisce la logica complessa e la gestione delle credenziali.
  • Scalabilità Futura: Aggiungere nuove funzionalità (es. send-image, create-reminder) richiede solo la registrazione di un nuovo tool nel server, senza dover modificare la logica dell’Agente AI.

Il potenziale dell’MCP

Sebbene l’esempio di Telegram sia semplice, la filosofia dell’MCP Server è applicabile a scenari molto più complessi:

  • Automazione Aziendale: Esporre strumenti per la creazione di ticket in Jira, l’aggiornamento di record in Salesforce o l’invio di query a database aziendali.
  • Integrazione Ibrida: Consentire a un Agente AI di interagire con sistemi legacy (datati) in modo standardizzato.
  • Gestione di Risorse: Fornire accesso controllato a dati o file (il concetto di resources nell’MCP), come documenti in Drive o fogli di calcolo.

L’MCP Server non è solo un pattern di integrazione: è un ponte essenziale che trasforma i modelli di linguaggio da semplici motori di testo in agenti attivi capaci di eseguire azioni significative nel mondo digitale.

Utilizzare il server MCP appena creato

Utilizzo in VSCode

Creare un file chiamato mcp.json nella cartella .vscode e modificarlo in questo modo:

Utilizzo in Claude Desktop

Modificare il file claude_desktop_config.json in questo modo:

Risorse utili

Autore: Daniel Zotti, Team Leader e Tech Leader Frontend @ Bitrock

Vuoi saperne di più sui nostri servizi? Compila il modulo e fissa un incontro con il nostro team!