Sviluppo di server MCP: rendi l'Agentic AI il "cliente zero" della tua API

I team di ingegneria di Red Hat Trusted Profile Analyzer (TPA) e Trustify hanno deciso di sperimentare il Model Context Protocol (MCP). In questo articolo illustreremo le sfide che abbiamo dovuto affrontare in questo percorso, sperando che sia di supporto ad altri team impegnati in iniziative simili.

Alcune informazioni essenziali: Red Hat Trusted Profile Analyzer (TPA) è un prodotto Red Hat per la gestione delle distinte base del software (SBOM): le memorizza e correla i pacchetti al loro interno con vulnerabilità pubbliche note. Si basa sul progetto upstream Trustify.

A un livello superficiale, la sua architettura è piuttosto "tradizionale":

• Il frontend è sviluppato utilizzando i componenti React e PatternFly (trustify-ui)
• Il backend è sviluppato con Rust, si connette a un'istanza di database e archivia le SBOM in uno storage compatibile con S3

Lo svolgimento del lavoro ha incluso queste fasi:

1. progettazione dell'integrazione del server MCP con TPA/Trustify;
2. definizione delle descrizioni degli strumenti del server MCP;
3. progettazione dei parametri dello strumento del server MCP.

Abbiamo individuato gli elementi da considerare in ogni fase e il risultato finale è il server MCP disponibile su GitHub. 

Progettazione dell'integrazione del server MCP con TPA/Trustify

Prima di approfondire la definizione dell'integrazione tra il server MCP e Trustify, ci siamo posti una domanda ricorrente nella vita di un ingegnere del software: quale libreria adotterò in questo progetto? Devo iniziare da zero e sviluppare tutto in autonomia?

Siamo sinceri sostenitori dell'open source, pertanto abbiamo esaminato l'attuale panorama delle librerie Rust (l'opzione che ci allettava di più, visto che Trustify è sviluppato principalmente in Rust) per l'implementazione di un server MCP.

La nostra ricerca non ha richiesto molto tempo perché abbiamo scoperto che MCP fornisce alcune librerie ufficiali nella sua organizzazione GitHub e tra queste era presente una libreria sviluppata con Rust.

Questa libreria, oltre a includere il codice necessario per supportare lo sviluppo di un server MCP, fornisce anche un ottimo gruppo di esempi da cui partire.

Abbiamo capito subito che, oltre ai dettagli specifici della libreria per l'esecuzione del server MCP e alla definizione degli strumenti disponibili con i relativi parametri, dovevamo decidere il modo in cui il server MCP poteva ottenere l'accesso ai dati "backend".

Abbiamo preso in considerazione due opzioni. Il server MCP poteva recuperare i dati:

• tramite connessione diretta al database in cui il backend di Trustify archivia i dati, oppure
• tramite chiamata agli endpoint REST forniti dal backend di Trustify.

Come si può immaginare, entrambi hanno dei pro e dei contro, motivo per cui è partita un'accesa discussione che riassumerò di seguito.

Vantaggi della connessione diretta al database:

1. accesso ai dati efficiente;
2. opportunità di adottare un approccio text to SQL.

Svantaggi:

1. il server MCP deve trovarsi allo stesso livello dell'architettura del backend;
2. sarebbe necessario duplicare il codice per gestire l'accesso ai dati rispetto al codice nel backend;
3. sarebbe necessario gestire il formato dei dati per definire gli output delle chiamate degli strumenti MCP.

Vantaggi della chiamata agli endpoint REST:

1. le chiamate rispettano l'autenticazione e l'autorizzazione già in vigore sulle API backend;
2. utilizzando la stessa sorgente, i dati disponibili sul server MCP sono perfettamente coerenti con quelli disponibili nell'interfaccia utente;
3. l'output JSON è disponibile gratuitamente inviando semplicemente l'output restituito dalle API backend.

Svantaggi:

1. prestazioni più lente a causa del passaggio tra più livelli dell'architettura.

Alla fine abbiamo deciso di chiamare gli endpoint REST dagli strumenti del server MCP, perché lo svantaggio di dover co-localizzare il server MCP accanto al backend e "abbastanza vicino" al database poteva davvero essere un ostacolo, soprattutto nel server MCP, dove il trasporto stdio viene eseguito localmente sugli host degli sviluppatori.

Nella fase di sviluppo iniziale, un ulteriore vantaggio è stato avere tutti i dati formattati "gratuitamente" in risposte JSON.

Definizione delle descrizioni degli strumenti del server MCP

Dopo aver deciso che gli strumenti del server MCP avrebbero chiamato le API di backend, siamo passati alla scelta della descrizione dei diversi strumenti. Nella prima iterazione, volevamo che ogni strumento MCP chiamasse un singolo endpoint API backend.

Considerando che Trustify documenta gli endpoint disponibili utilizzando il file OpenAPI openapi.yaml, abbiamo deciso di utilizzare la descrizione e le definizioni degli endpoint OpenAPI come descrizione dello strumento MCP in modo da poter valutare l'efficacia della documentazione di questi endpoint per i nostri utenti. Così facendo, la nostra Agentic AI è diventata il "cliente zero" delle nostre API.

Tutto ciò è stato fatto con l'approccio del miglioramento continuo: se le descrizioni delle API di Trustify sono abbastanza buone da poter essere gestite da un LLM, anche i nostri utenti dovrebbero essere in grado di comprendere questo tipo di documentazione.

Questo approccio ci ha aiutato a migliorare ogni endpoint e ci ha consentito di prendere la decisione di progettazione successiva.

Progettazione dei parametri degli strumenti del server MCP

A questo punto, abbiamo affrontato il problema relativo ai parametri di input per la chiamata dello strumento e, per farlo, abbiamo dovuto fare un passo indietro. L'endpoint di Trustify per il recupero di un elenco di entità accetta un parametro di query q. Questo parametro consente agli utenti di specificare una query in base a una grammatica definita nelle specifiche OpenAPI. 

Le opzioni a nostra disposizione erano:

1. esporre direttamente il parametro q path dell'endpoint come parametro di input dello strumento MCP;
2. esporre i campi interni disponibili per la creazione del valore della query per il parametro q come parametri di input dello strumento MCP.

Abbiamo testato entrambi gli approcci.

Il primo richiede una descrizione approfondita e dettagliata del parametro della query che, al momento, non è fornito dalla specifica OpenAPI. Riteniamo che un elenco completo dei campi interrogabili dovrebbe essere una parte obbligatoria (piuttosto che facoltativa) della documentazione. Sarebbe utile che tutti gli utenti avessero accesso a queste informazioni.

Questo secondo approccio semplifica il processo per l'agente IA. L'elenco esplicito dei parametri su cui eseguire query, come la gravità della vulnerabilità, la data di pubblicazione o la descrizione, rende le informazioni più fruibili per l'LLM. In questo modo non è più necessario che l'LLM interpreti prima la grammatica di una query, che può essere un processo complesso nel primo approccio.

Un'ulteriore considerazione è che l'elenco esplicito di tutti i parametri disponibili nello strumento MCP richiede un lavoro continuo per mantenere la coerenza con l'implementazione effettiva dell'endpoint backend. D'altra parte, esporre solo un sottoinsieme dei parametri disponibili riduce la versatilità dello strumento senza alcuna garanzia che i costi di manutenzione vengano ridotti.

Abbiamo deciso di utilizzare un parametro di query q per lo strumento MCP e ne miglioreremo la descrizione all'interno della definizione OpenAPI in modo che tutti gli utenti possano beneficiarne.

Considerazioni finali

Nella progettazione di un server MCP abbiamo adottato il seguente approccio:

• il server MCP sfrutta le API esistenti;
• il server MCP sfrutta la documentazione OpenAPI esistente;
• gli strumenti server MCP espongono gli stessi parametri previsti dall'endpoint API remoto.

Come accennato in precedenza, il risultato finale è disponibile su GitHub.