GoSudaCapire meglio gli MCP host
Cos'è MCP
MCP è un protocollo sviluppato da Anthropic per Claude. MCP è l'acronimo di Model Context Protocol e consente a un LLM di richiedere attivamente azioni o risorse dall'esterno. MCP è, letteralmente, un protocollo che si limita a fornire richieste e risposte; pertanto, il processo e l'esecuzione devono essere implementati dallo sviluppatore.
Sul funzionamento interno
Prima di descrivere il funzionamento interno, vorrei soffermarmi su Gemini Function Calling. Gemini Function Calling, così come MCP, consente a un LLM di invocare attivamente operazioni esterne. A questo punto potrebbe sorgere il dubbio sul motivo per cui sia stato introdotto Function Calling. La ragione è che Function Calling è apparso prima di MCP e, poiché utilizza lo stesso schema OpenAPI, risulta compatibile; si è quindi ipotizzato che il suo comportamento sia simile. Di conseguenza, poiché la documentazione di Gemini Function Calling è relativamente più dettagliata, si è ritenuto che potesse essere utile e lo si è quindi incluso.
Il flusso complessivo è il seguente.
- Si definisce una funzione.
- Si invia a Gemini la definizione della funzione insieme al prompt.
- "Send user prompt along with the function declaration(s) to the model. It analyzes the request and determines if a function call would be helpful. If so, it responds with a structured JSON object."
- Se necessario, Gemini richiede una chiamata di funzione.
- Se Gemini lo ritiene necessario, il chiamante riceve il nome e i parametri per la chiamata di funzione.
- Il chiamante può decidere se eseguire o meno la chiamata.
- Eseguire la chiamata e restituire un valore legittimo
- Non eseguire la chiamata e restituire dati come se fosse stata eseguita
- Ignorarla semplicemente
- Nel corso di questo processo, Gemini può richiedere l'esecuzione di più funzioni contemporaneamente, oppure, dopo aver osservato il risultato di una funzione, richiederne un'altra.
- Quando si ottiene una risposta ordinata, il processo termina.
Questo flusso è, in generale, coerente con quello di MCP. Ne viene data una descrizione simile anche nel tutorial di MCP. Anche ollama tools presenta un comportamento analogo.
Inoltre, fortunatamente, questi tre strumenti, ollama tools, MCP e Gemini Function Calling, condividono quasi la stessa struttura dello schema, quindi implementando solo MCP è possibile utilizzarlo in tutti e tre i contesti.
Ah, e c'è anche uno svantaggio comune a tutti: poiché è il modello a eseguire effettivamente le chiamate, se il modello utilizzato non è in buone condizioni, può non invocare le funzioni, invocarle in modo errato oppure inviare richieste DoS al server MCP, causando così comportamenti anomali.
Host MCP in Go
mcphost di mark3lab
In Go esiste mcphost, in fase di sviluppo presso l'organizzazione mark3lab.
L'utilizzo è molto semplice.
1go install github.com/mark3labs/mcphost@latest
Dopo l'installazione, si crea il file $HOME/.mcp.json con il seguente contenuto.
1{
2 "mcpServers": {
3 "sqlite": {
4 "command": "uvx",
5 "args": [
6 "mcp-server-sqlite",
7 "--db-path",
8 "/tmp/foo.db"
9 ]
10 },
11 "filesystem": {
12 "command": "npx",
13 "args": [
14 "-y",
15 "@modelcontextprotocol/server-filesystem",
16 "/tmp"
17 ]
18 }
19 }
20}
Quindi lo si esegue con un modello di ollama come segue.
Naturalmente, se necessario, prima si scarica il modello con ollama pull mistral-small.
In generale si consigliano Claude o qwen2.5, ma per il momento io suggerisco mistral-small.
1mcphost -m ollama:mistral-small
Tuttavia, eseguendo in questo modo, è possibile utilizzarlo solo in modalità domanda e risposta nell'ambiente CLI.
Per questo motivo, modificheremo il codice di questo mcphost per renderlo più programmabile.
Fork di mcphost
Come già visto, mcphost include la funzionalità di estrazione dei metadati e di invocazione delle funzioni tramite MCP. Pertanto, sono necessarie la parte che chiama l'LLM, quella che gestisce il server MCP e quella che gestisce la cronologia dei messaggi.
La parte corrispondente è stata estratta nel Runner del seguente package.
1package runner
2
3import (
4 "context"
5 "encoding/json"
6 "fmt"
7 "log"
8 "strings"
9 "time"
10
11 mcpclient "github.com/mark3labs/mcp-go/client"
12 "github.com/mark3labs/mcp-go/mcp"
13
14 "github.com/mark3labs/mcphost/pkg/history"
15 "github.com/mark3labs/mcphost/pkg/llm"
16)
17
18type Runner struct {
19 provider llm.Provider
20 mcpClients map[string]*mcpclient.StdioMCPClient
21 tools []llm.Tool
22
23 messages []history.HistoryMessage
24}
Non esamineremo separatamente le dichiarazioni interne di questa parte. Sono comunque quasi identiche ai loro nomi.
1func NewRunner(systemPrompt string, provider llm.Provider, mcpClients map[string]*mcpclient.StdioMCPClient, tools []llm.Tool) *Runner {
2 return &Runner{
3 provider: provider,
4 mcpClients: mcpClients,
5 tools: tools,
6 messages: []history.HistoryMessage{
7 {
8 Role: "system",
9 Content: []history.ContentBlock{{
10 Type: "text",
11 Text: systemPrompt,
12 }},
13 },
14 },
15 }
16}
Per mcpClients e tools, utilizzati qui, si veda il file corrispondente.
Per provider, utilizzeremo quello di ollama, quindi si veda il file corrispondente.
Il piatto principale è il metodo Run.
1func (r *Runner) Run(ctx context.Context, prompt string) (string, error) {
2 if len(prompt) != 0 {
3 r.messages = append(r.messages, history.HistoryMessage{
4 Role: "user",
5 Content: []history.ContentBlock{{
6 Type: "text",
7 Text: prompt,
8 }},
9 })
10 }
11
12 llmMessages := make([]llm.Message, len(r.messages))
13 for i := range r.messages {
14 llmMessages[i] = &r.messages[i]
15 }
16
17 const initialBackoff = 1 * time.Second
18 const maxRetries int = 5
19 const maxBackoff = 30 * time.Second
20
21 var message llm.Message
22 var err error
23 backoff := initialBackoff
24 retries := 0
25 for {
26 message, err = r.provider.CreateMessage(
27 context.Background(),
28 prompt,
29 llmMessages,
30 r.tools,
31 )
32 if err != nil {
33 if strings.Contains(err.Error(), "overloaded_error") {
34 if retries >= maxRetries {
35 return "", fmt.Errorf(
36 "claude is currently overloaded. please wait a few minutes and try again",
37 )
38 }
39
40 time.Sleep(backoff)
41 backoff *= 2
42 if backoff > maxBackoff {
43 backoff = maxBackoff
44 }
45 retries++
46 continue
47 }
48
49 return "", err
50 }
51
52 break
53 }
54
55 var messageContent []history.ContentBlock
56
57 var toolResults []history.ContentBlock
58 messageContent = []history.ContentBlock{}
59
60 if message.GetContent() != "" {
61 messageContent = append(messageContent, history.ContentBlock{
62 Type: "text",
63 Text: message.GetContent(),
64 })
65 }
66
67 for _, toolCall := range message.GetToolCalls() {
68 input, _ := json.Marshal(toolCall.GetArguments())
69 messageContent = append(messageContent, history.ContentBlock{
70 Type: "tool_use",
71 ID: toolCall.GetID(),
72 Name: toolCall.GetName(),
73 Input: input,
74 })
75
76 parts := strings.Split(toolCall.GetName(), "__")
77
78 serverName, toolName := parts[0], parts[1]
79 mcpClient, ok := r.mcpClients[serverName]
80 if !ok {
81 continue
82 }
83
84 var toolArgs map[string]interface{}
85 if err := json.Unmarshal(input, &toolArgs); err != nil {
86 continue
87 }
88
89 var toolResultPtr *mcp.CallToolResult
90 req := mcp.CallToolRequest{}
91 req.Params.Name = toolName
92 req.Params.Arguments = toolArgs
93 toolResultPtr, err = mcpClient.CallTool(
94 context.Background(),
95 req,
96 )
97
98 if err != nil {
99 errMsg := fmt.Sprintf(
100 "Error calling tool %s: %v",
101 toolName,
102 err,
103 )
104 log.Printf("Error calling tool %s: %v", toolName, err)
105
106 toolResults = append(toolResults, history.ContentBlock{
107 Type: "tool_result",
108 ToolUseID: toolCall.GetID(),
109 Content: []history.ContentBlock{{
110 Type: "text",
111 Text: errMsg,
112 }},
113 })
114
115 continue
116 }
117
118 toolResult := *toolResultPtr
119
120 if toolResult.Content != nil {
121 resultBlock := history.ContentBlock{
122 Type: "tool_result",
123 ToolUseID: toolCall.GetID(),
124 Content: toolResult.Content,
125 }
126
127 var resultText string
128 for _, item := range toolResult.Content {
129 if contentMap, ok := item.(map[string]interface{}); ok {
130 if text, ok := contentMap["text"]; ok {
131 resultText += fmt.Sprintf("%v ", text)
132 }
133 }
134 }
135
136 resultBlock.Text = strings.TrimSpace(resultText)
137
138 toolResults = append(toolResults, resultBlock)
139 }
140 }
141
142 r.messages = append(r.messages, history.HistoryMessage{
143 Role: message.GetRole(),
144 Content: messageContent,
145 })
146
147 if len(toolResults) > 0 {
148 r.messages = append(r.messages, history.HistoryMessage{
149 Role: "user",
150 Content: toolResults,
151 })
152
153 return r.Run(ctx, "")
154 }
155
156 return message.GetContent(), nil
157}
Il codice stesso è stato ottenuto combinando parti del file corrispondente.
In sintesi, il contenuto è il seguente.
- Si invia la lista degli strumenti insieme al prompt, richiedendo se eseguire una chiamata o generare una risposta.
- Quando viene generata una risposta, la ricorsione si interrompe e il risultato viene restituito.
- Se l'LLM richiede l'esecuzione di uno strumento, l'host invoca il server MCP.
- Si aggiunge il risultato alla cronologia e si torna al punto 1.
Conclusioni
Già finito?
In realtà non c'è molto altro da dire. Questo articolo è stato scritto principalmente per aiutare a comprendere in linea generale il funzionamento di un server MCP. Spero che questo testo abbia contribuito, anche se in misura modesta, a far capire il funzionamento di un host MCP.