Criando um cliente com LLM

Até agora, você viu como criar um servidor e um cliente. O cliente foi capaz de chamar o servidor explicitamente para listar suas ferramentas, recursos e prompts. No entanto, essa abordagem não é muito prática. Seu usuário vive na era dos agentes e espera usar prompts e se comunicar com um LLM para realizar tarefas. Para o usuário, não importa se você usa MCP ou não para armazenar suas capacidades, mas ele espera interagir usando linguagem natural. Então, como resolvemos isso? A solução é adicionar um LLM ao cliente.

Visão Geral

Nesta lição, focamos em adicionar um LLM ao cliente e mostramos como isso proporciona uma experiência muito melhor para o usuário.

Objetivos de Aprendizagem

Ao final desta lição, você será capaz de:

Criar um cliente com um LLM.
Interagir de forma integrada com um servidor MCP usando um LLM.
Proporcionar uma melhor experiência ao usuário final no lado do cliente.

Abordagem

Vamos tentar entender a abordagem que precisamos adotar. Adicionar um LLM parece simples, mas como realmente fazemos isso?

Aqui está como o cliente interagirá com o servidor:

Estabelecer conexão com o servidor.
Listar capacidades, prompts, recursos e ferramentas, e salvar seus esquemas.
Adicionar um LLM e passar as capacidades salvas e seus esquemas em um formato que o LLM entenda.
Processar um prompt do usuário, passando-o para o LLM junto com as ferramentas listadas pelo cliente.

Ótimo, agora entendemos como podemos fazer isso em um nível alto. Vamos tentar na prática no exercício abaixo.

Exercício: Criando um cliente com um LLM

Neste exercício, aprenderemos a adicionar um LLM ao nosso cliente.

Autenticação usando GitHub Personal Access Token

Criar um token do GitHub é um processo simples. Veja como fazer:

Vá para Configurações do GitHub – Clique na sua foto de perfil no canto superior direito e selecione Configurações.
Navegue até Configurações de Desenvolvedor – Role para baixo e clique em Configurações de Desenvolvedor.
Selecione Tokens de Acesso Pessoal – Clique em Tokens de acesso pessoal e depois em Gerar novo token.
Configure seu Token – Adicione uma nota para referência, defina uma data de expiração e selecione os escopos (permissões) necessários.
Gere e Copie o Token – Clique em Gerar token e certifique-se de copiá-lo imediatamente, pois você não poderá vê-lo novamente.

-1- Conectar ao servidor

Vamos criar nosso cliente primeiro:

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
import OpenAI from "openai";
import { z } from "zod"; // Import zod for schema validation

class MCPClient {
    private openai: OpenAI;
    private client: Client;
    constructor(){
        this.openai = new OpenAI({
            baseURL: "https://models.inference.ai.azure.com", 
            apiKey: process.env.GITHUB_TOKEN,
        });

        this.client = new Client(
            {
                name: "example-client",
                version: "1.0.0"
            },
            {
                capabilities: {
                prompts: {},
                resources: {},
                tools: {}
                }
            }
            );    
    }
}

No código acima, nós:

Importamos as bibliotecas necessárias.
Criamos uma classe com dois membros, client e openai, que nos ajudarão a gerenciar um cliente e interagir com um LLM, respectivamente.
Configuramos nossa instância de LLM para usar os modelos do GitHub, definindo baseUrl para apontar para a API de inferência.

Python

from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command="mcp",  # Executable
    args=["run", "server.py"],  # Optional command line arguments
    env=None,  # Optional environment variables
)


async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(
            read, write
        ) as session:
            # Initialize the connection
            await session.initialize()


if __name__ == "__main__":
    import asyncio

    asyncio.run(run())

No código acima, nós:

Importamos as bibliotecas necessárias para MCP.
Criamos um cliente.

.NET

using Azure;
using Azure.AI.Inference;
using Azure.Identity;
using System.Text.Json;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol.Transport;
using System.Text.Json;

var clientTransport = new StdioClientTransport(new()
{
    Name = "Demo Server",
    Command = "/workspaces/mcp-for-beginners/03-GettingStarted/02-client/solution/server/bin/Debug/net8.0/server",
    Arguments = [],
});

await using var mcpClient = await McpClientFactory.CreateAsync(clientTransport);

Java

Primeiro, você precisará adicionar as dependências do LangChain4j ao seu arquivo pom.xml. Adicione essas dependências para habilitar a integração com MCP e suporte aos modelos do GitHub:

<properties>
    <langchain4j.version>1.0.0-beta3</langchain4j.version>
</properties>

<dependencies>
    <!-- LangChain4j MCP Integration -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-mcp</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    
    <!-- OpenAI Official API Client -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai-official</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    
    <!-- GitHub Models Support -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-github-models</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    
    <!-- Spring Boot Starter (optional, for production apps) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

Em seguida, crie sua classe de cliente Java:

import dev.langchain4j.mcp.McpToolProvider;
import dev.langchain4j.mcp.client.DefaultMcpClient;
import dev.langchain4j.mcp.client.McpClient;
import dev.langchain4j.mcp.client.transport.McpTransport;
import dev.langchain4j.mcp.client.transport.http.HttpMcpTransport;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openaiofficial.OpenAiOfficialChatModel;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.service.tool.ToolProvider;

import java.time.Duration;
import java.util.List;

public class LangChain4jClient {
    
    public static void main(String[] args) throws Exception {        // Configure the LLM to use GitHub Models
        ChatLanguageModel model = OpenAiOfficialChatModel.builder()
                .isGitHubModels(true)
                .apiKey(System.getenv("GITHUB_TOKEN"))
                .timeout(Duration.ofSeconds(60))
                .modelName("gpt-4.1-nano")
                .build();

        // Create MCP transport for connecting to server
        McpTransport transport = new HttpMcpTransport.Builder()
                .sseUrl("http://localhost:8080/sse")
                .timeout(Duration.ofSeconds(60))
                .logRequests(true)
                .logResponses(true)
                .build();

        // Create MCP client
        McpClient mcpClient = new DefaultMcpClient.Builder()
                .transport(transport)
                .build();
    }
}

No código acima, nós:

Adicionamos dependências do LangChain4j: Necessárias para integração com MCP, cliente oficial OpenAI e suporte aos modelos do GitHub.
Importamos as bibliotecas do LangChain4j: Para integração com MCP e funcionalidade de modelo de chat OpenAI.
Criamos um ChatLanguageModel: Configurado para usar os modelos do GitHub com seu token do GitHub.
Configuramos transporte HTTP: Usando Server-Sent Events (SSE) para conectar ao servidor MCP.
Criamos um cliente MCP: Que gerenciará a comunicação com o servidor.
Usamos o suporte integrado do LangChain4j para MCP: Que simplifica a integração entre LLMs e servidores MCP.

Rust

Este exemplo assume que você tem um servidor MCP baseado em Rust em execução. Se você não tiver um, consulte a lição 01-first-server para criar o servidor.

Depois de ter seu servidor MCP em Rust, abra um terminal e navegue até o mesmo diretório do servidor. Em seguida, execute o seguinte comando para criar um novo projeto de cliente LLM:

mkdir calculator-llmclient
cd calculator-llmclient
cargo init

Adicione as seguintes dependências ao seu arquivo Cargo.toml:

[dependencies]
async-openai = { version = "0.29.0", features = ["byot"] }
rmcp = { version = "0.5.0", features = ["client", "transport-child-process"] }
serde_json = "1.0.141"
tokio = { version = "1.46.1", features = ["rt-multi-thread"] }

Note

Não há uma biblioteca oficial de Rust para OpenAI, no entanto, o crate async-openai é uma biblioteca mantida pela comunidade que é comumente usada.

Abra o arquivo src/main.rs e substitua seu conteúdo pelo seguinte código:

use async_openai::{Client, config::OpenAIConfig};
use rmcp::{
    RmcpError,
    model::{CallToolRequestParam, ListToolsResult},
    service::{RoleClient, RunningService, ServiceExt},
    transport::{ConfigureCommandExt, TokioChildProcess},
};
use serde_json::{Value, json};
use std::error::Error;
use tokio::process::Command;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Initial message
    let mut messages = vec![json!({"role": "user", "content": "What is the sum of 3 and 2?"})];

    // Setup OpenAI client
    let api_key = std::env::var("OPENAI_API_KEY")?;
    let openai_client = Client::with_config(
        OpenAIConfig::new()
            .with_api_base("https://models.github.ai/inference/chat")
            .with_api_key(api_key),
    );

    // Setup MCP client
    let server_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
        .parent()
        .unwrap()
        .join("calculator-server");

    let mcp_client = ()
        .serve(
            TokioChildProcess::new(Command::new("cargo").configure(|cmd| {
                cmd.arg("run").current_dir(server_dir);
            }))
            .map_err(RmcpError::transport_creation::<TokioChildProcess>)?,
        )
        .await?;

    // TODO: Get MCP tool listing 

    // TODO: LLM conversation with tool calls

    Ok(())
}

Este código configura uma aplicação básica em Rust que se conectará a um servidor MCP e aos modelos do GitHub para interações com LLM.

Important

Certifique-se de definir a variável de ambiente OPENAI_API_KEY com seu token do GitHub antes de executar a aplicação.

Ótimo, para o próximo passo, vamos listar as capacidades no servidor.

-2- Listar capacidades do servidor

Agora vamos conectar ao servidor e solicitar suas capacidades:

TypeScript

Na mesma classe, adicione os seguintes métodos:

async connectToServer(transport: Transport) {
     await this.client.connect(transport);
     this.run();
     console.error("MCPClient started on stdin/stdout");
}

async run() {
    console.log("Asking server for available tools");

    // listing tools
    const toolsResult = await this.client.listTools();
}

No código acima, nós:

Adicionamos código para conectar ao servidor, connectToServer.
Criamos um método run responsável por gerenciar o fluxo do aplicativo. Até agora, ele apenas lista as ferramentas, mas adicionaremos mais em breve.

Python

# List available resources
resources = await session.list_resources()
print("LISTING RESOURCES")
for resource in resources:
    print("Resource: ", resource)

# List available tools
tools = await session.list_tools()
print("LISTING TOOLS")
for tool in tools.tools:
    print("Tool: ", tool.name)
    print("Tool", tool.inputSchema["properties"])

Aqui está o que adicionamos:

Listamos recursos e ferramentas e os imprimimos. Para ferramentas, também listamos inputSchema, que usaremos mais tarde.

.NET

async Task<List<ChatCompletionsToolDefinition>> GetMcpTools()
{
    Console.WriteLine("Listing tools");
    var tools = await mcpClient.ListToolsAsync();

    List<ChatCompletionsToolDefinition> toolDefinitions = new List<ChatCompletionsToolDefinition>();

    foreach (var tool in tools)
    {
        Console.WriteLine($"Connected to server with tools: {tool.Name}");
        Console.WriteLine($"Tool description: {tool.Description}");
        Console.WriteLine($"Tool parameters: {tool.JsonSchema}");

        // TODO: convert tool definition from MCP tool to LLm tool     
    }

    return toolDefinitions;
}

No código acima, nós:

Listamos as ferramentas disponíveis no servidor MCP.
Para cada ferramenta, listamos nome, descrição e seu esquema. Este último será usado para chamar as ferramentas em breve.

Java

// Create a tool provider that automatically discovers MCP tools
ToolProvider toolProvider = McpToolProvider.builder()
        .mcpClients(List.of(mcpClient))
        .build();

// The MCP tool provider automatically handles:
// - Listing available tools from the MCP server
// - Converting MCP tool schemas to LangChain4j format
// - Managing tool execution and responses

No código acima, nós:

Criamos um McpToolProvider que descobre e registra automaticamente todas as ferramentas do servidor MCP.
O provedor de ferramentas lida com a conversão entre esquemas de ferramentas MCP e o formato de ferramentas do LangChain4j internamente.
Essa abordagem abstrai o processo manual de listagem e conversão de ferramentas.

Rust

Recuperar ferramentas do servidor MCP é feito usando o método list_tools. Na sua função main, após configurar o cliente MCP, adicione o seguinte código:

// Get MCP tool listing 
let tools = mcp_client.list_tools(Default::default()).await?;

-3- Converter capacidades do servidor para ferramentas do LLM

O próximo passo após listar as capacidades do servidor é convertê-las em um formato que o LLM entenda. Depois de fazer isso, podemos fornecer essas capacidades como ferramentas para o LLM.

TypeScript

Adicione o seguinte código para converter a resposta do servidor MCP em um formato de ferramenta que o LLM possa usar:

openAiToolAdapter(tool: {
    name: string;
    description?: string;
    input_schema: any;
    }) {
    // Create a zod schema based on the input_schema
    const schema = z.object(tool.input_schema);

    return {
        type: "function" as const, // Explicitly set type to "function"
        function: {
        name: tool.name,
        description: tool.description,
        parameters: {
        type: "object",
        properties: tool.input_schema.properties,
        required: tool.input_schema.required,
        },
        },
    };
}

O código acima pega uma resposta do servidor MCP e a converte em um formato de definição de ferramenta que o LLM possa entender.

Vamos atualizar o método run para listar as capacidades do servidor:

async run() {
    console.log("Asking server for available tools");
    const toolsResult = await this.client.listTools();
    const tools = toolsResult.tools.map((tool) => {
        return this.openAiToolAdapter({
        name: tool.name,
        description: tool.description,
        input_schema: tool.inputSchema,
        });
    });
}

No código acima, atualizamos o método run para mapear os resultados e, para cada entrada, chamar openAiToolAdapter.

Python

Primeiro, vamos criar a seguinte função de conversão:

def convert_to_llm_tool(tool):
    tool_schema = {
        "type": "function",
        "function": {
            "name": tool.name,
            "description": tool.description,
            "type": "function",
            "parameters": {
                "type": "object",
                "properties": tool.inputSchema["properties"]
            }
        }
    }

    return tool_schema

Na função acima, convert_to_llm_tools, pegamos uma resposta de ferramenta MCP e a convertemos em um formato que o LLM possa entender.

Em seguida, vamos atualizar nosso código de cliente para aproveitar essa função:
```
for tool in tools.tools:
    print("Tool: ", tool.name)
    print("Tool", tool.inputSchema["properties"])
    functions.append(convert_to_llm_tool(tool))
```
Aqui, estamos adicionando uma chamada para convert_to_llm_tool para converter a resposta de ferramenta MCP em algo que possamos alimentar ao LLM mais tarde.

.NET

Vamos adicionar código para converter a resposta de ferramenta MCP em algo que o LLM possa entender:

ChatCompletionsToolDefinition ConvertFrom(string name, string description, JsonElement jsonElement)
{ 
    // convert the tool to a function definition
    FunctionDefinition functionDefinition = new FunctionDefinition(name)
    {
        Description = description,
        Parameters = BinaryData.FromObjectAsJson(new
        {
            Type = "object",
            Properties = jsonElement
        },
        new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase })
    };

    // create a tool definition
    ChatCompletionsToolDefinition toolDefinition = new ChatCompletionsToolDefinition(functionDefinition);
    return toolDefinition;
}

No código acima, nós:

Criamos uma função ConvertFrom que recebe nome, descrição e esquema de entrada.
Definimos funcionalidade que cria uma FunctionDefinition que é passada para uma ChatCompletionsDefinition. Esta última é algo que o LLM pode entender.

Vamos ver como podemos atualizar algum código existente para aproveitar essa função acima:

async Task<List<ChatCompletionsToolDefinition>> GetMcpTools()
{
    Console.WriteLine("Listing tools");
    var tools = await mcpClient.ListToolsAsync();

    List<ChatCompletionsToolDefinition> toolDefinitions = new List<ChatCompletionsToolDefinition>();

    foreach (var tool in tools)
    {
        Console.WriteLine($"Connected to server with tools: {tool.Name}");
        Console.WriteLine($"Tool description: {tool.Description}");
        Console.WriteLine($"Tool parameters: {tool.JsonSchema}");

        JsonElement propertiesElement;
        tool.JsonSchema.TryGetProperty("properties", out propertiesElement);

        var def = ConvertFrom(tool.Name, tool.Description, propertiesElement);
        Console.WriteLine($"Tool definition: {def}");
        toolDefinitions.Add(def);

        Console.WriteLine($"Properties: {propertiesElement}");        
    }

    return toolDefinitions;
}

No código acima, nós:

Atualizamos a função para converter a resposta de ferramenta MCP em uma ferramenta LLM. Vamos destacar o código que adicionamos:
```
JsonElement propertiesElement;
tool.JsonSchema.TryGetProperty("properties", out propertiesElement);

var def = ConvertFrom(tool.Name, tool.Description, propertiesElement);
Console.WriteLine($"Tool definition: {def}");
toolDefinitions.Add(def);
```
O esquema de entrada faz parte da resposta da ferramenta, mas está no atributo "properties", então precisamos extraí-lo. Além disso, agora chamamos ConvertFrom com os detalhes da ferramenta. Agora que fizemos o trabalho pesado, vamos ver como tudo se junta ao processar um prompt do usuário a seguir.

Java

// Create a Bot interface for natural language interaction
public interface Bot {
    String chat(String prompt);
}

// Configure the AI service with LLM and MCP tools
Bot bot = AiServices.builder(Bot.class)
        .chatLanguageModel(model)
        .toolProvider(toolProvider)
        .build();

No código acima, nós:

Definimos uma interface simples Bot para interações em linguagem natural.
Usamos os AiServices do LangChain4j para vincular automaticamente o LLM ao provedor de ferramentas MCP.
O framework lida automaticamente com a conversão de esquemas de ferramentas MCP e chamadas de função nos bastidores.
Essa abordagem elimina a conversão manual de ferramentas - o LangChain4j lida com toda a complexidade de converter ferramentas MCP para um formato compatível com LLM.

Rust

Para converter a resposta de ferramenta MCP em um formato que o LLM possa entender, adicionaremos uma função auxiliar que formata a listagem de ferramentas. Adicione o seguinte código ao seu arquivo main.rs abaixo da função main. Isso será chamado ao fazer solicitações ao LLM:

async fn format_tools(tools: &ListToolsResult) -> Result<Vec<Value>, Box<dyn Error>> {
    let tools_json = serde_json::to_value(tools)?;
    let Some(tools_array) = tools_json.get("tools").and_then(|t| t.as_array()) else {
        return Ok(vec![]);
    };

    let formatted_tools = tools_array
        .iter()
        .filter_map(|tool| {
            let name = tool.get("name")?.as_str()?;
            let description = tool.get("description")?.as_str()?;
            let schema = tool.get("inputSchema")?;

            Some(json!({
                "type": "function",
                "function": {
                    "name": name,
                    "description": description,
                    "parameters": {
                        "type": "object",
                        "properties": schema.get("properties").unwrap_or(&json!({})),
                        "required": schema.get("required").unwrap_or(&json!([]))
                    }
                }
            }))
        })
        .collect();

    Ok(formatted_tools)
}

Ótimo, estamos prontos para processar solicitações de usuários, então vamos abordar isso a seguir.

-4- Processar solicitações de prompt do usuário

Nesta parte do código, processaremos solicitações de usuários.

TypeScript

Adicione um método que será usado para chamar nosso LLM:

async callTools(
    tool_calls: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[],
    toolResults: any[]
) {
    for (const tool_call of tool_calls) {
    const toolName = tool_call.function.name;
    const args = tool_call.function.arguments;

    console.log(`Calling tool ${toolName} with args ${JSON.stringify(args)}`);


    // 2. Call the server's tool 
    const toolResult = await this.client.callTool({
        name: toolName,
        arguments: JSON.parse(args),
    });

    console.log("Tool result: ", toolResult);

    // 3. Do something with the result
    // TODO  

    }
}

No código acima, nós:

Adicionamos um método callTools.

O método pega uma resposta do LLM e verifica quais ferramentas foram chamadas, se houver:

for (const tool_call of tool_calls) {
const toolName = tool_call.function.name;
const args = tool_call.function.arguments;

console.log(`Calling tool ${toolName} with args ${JSON.stringify(args)}`);

// call tool
}

Chama uma ferramenta, se o LLM indicar que ela deve ser chamada:

// 2. Call the server's tool 
const toolResult = await this.client.callTool({
    name: toolName,
    arguments: JSON.parse(args),
});

console.log("Tool result: ", toolResult);

// 3. Do something with the result
// TODO

Atualize o método run para incluir chamadas ao LLM e chamar callTools:

// 1. Create messages that's input for the LLM
const prompt = "What is the sum of 2 and 3?"

const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
        {
            role: "user",
            content: prompt,
        },
    ];

console.log("Querying LLM: ", messages[0].content);

// 2. Calling the LLM
let response = this.openai.chat.completions.create({
    model: "gpt-4o-mini",
    max_tokens: 1000,
    messages,
    tools: tools,
});    

let results: any[] = [];

// 3. Go through the LLM response,for each choice, check if it has tool calls 
(await response).choices.map(async (choice: { message: any; }) => {
    const message = choice.message;
    if (message.tool_calls) {
        console.log("Making tool call")
        await this.callTools(message.tool_calls, results);
    }
});

Ótimo, vamos listar o código completo:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
import OpenAI from "openai";
import { z } from "zod"; // Import zod for schema validation

class MyClient {
    private openai: OpenAI;
    private client: Client;
    constructor(){
        this.openai = new OpenAI({
            baseURL: "https://models.inference.ai.azure.com", // might need to change to this url in the future: https://models.github.ai/inference
            apiKey: process.env.GITHUB_TOKEN,
        });

        this.client = new Client(
            {
                name: "example-client",
                version: "1.0.0"
            },
            {
                capabilities: {
                prompts: {},
                resources: {},
                tools: {}
                }
            }
            );    
    }

    async connectToServer(transport: Transport) {
        await this.client.connect(transport);
        this.run();
        console.error("MCPClient started on stdin/stdout");
    }

    openAiToolAdapter(tool: {
        name: string;
        description?: string;
        input_schema: any;
          }) {
          // Create a zod schema based on the input_schema
          const schema = z.object(tool.input_schema);
      
          return {
            type: "function" as const, // Explicitly set type to "function"
            function: {
              name: tool.name,
              description: tool.description,
              parameters: {
              type: "object",
              properties: tool.input_schema.properties,
              required: tool.input_schema.required,
              },
            },
          };
    }
    
    async callTools(
        tool_calls: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[],
        toolResults: any[]
      ) {
        for (const tool_call of tool_calls) {
          const toolName = tool_call.function.name;
          const args = tool_call.function.arguments;
    
          console.log(`Calling tool ${toolName} with args ${JSON.stringify(args)}`);
    
    
          // 2. Call the server's tool 
          const toolResult = await this.client.callTool({
            name: toolName,
            arguments: JSON.parse(args),
          });
    
          console.log("Tool result: ", toolResult);
    
          // 3. Do something with the result
          // TODO  
    
         }
    }

    async run() {
        console.log("Asking server for available tools");
        const toolsResult = await this.client.listTools();
        const tools = toolsResult.tools.map((tool) => {
            return this.openAiToolAdapter({
              name: tool.name,
              description: tool.description,
              input_schema: tool.inputSchema,
            });
        });

        const prompt = "What is the sum of 2 and 3?";
    
        const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
            {
                role: "user",
                content: prompt,
            },
        ];

        console.log("Querying LLM: ", messages[0].content);
        let response = this.openai.chat.completions.create({
            model: "gpt-4o-mini",
            max_tokens: 1000,
            messages,
            tools: tools,
        });    

        let results: any[] = [];
    
        // 1. Go through the LLM response,for each choice, check if it has tool calls 
        (await response).choices.map(async (choice: { message: any; }) => {
          const message = choice.message;
          if (message.tool_calls) {
              console.log("Making tool call")
              await this.callTools(message.tool_calls, results);
          }
        });
    }
    
}

let client = new MyClient();
 const transport = new StdioClientTransport({
            command: "node",
            args: ["./build/index.js"]
        });

client.connectToServer(transport);

Python

Vamos adicionar algumas importações necessárias para chamar um LLM:

# llm
import os
from azure.ai.inference import ChatCompletionsClient
from azure.ai.inference.models import SystemMessage, UserMessage
from azure.core.credentials import AzureKeyCredential
import json

Em seguida, vamos adicionar a função que chamará o LLM:

# llm

def call_llm(prompt, functions):
    token = os.environ["GITHUB_TOKEN"]
    endpoint = "https://models.inference.ai.azure.com"

    model_name = "gpt-4o"

    client = ChatCompletionsClient(
        endpoint=endpoint,
        credential=AzureKeyCredential(token),
    )

    print("CALLING LLM")
    response = client.complete(
        messages=[
            {
            "role": "system",
            "content": "You are a helpful assistant.",
            },
            {
            "role": "user",
            "content": prompt,
            },
        ],
        model=model_name,
        tools = functions,
        # Optional parameters
        temperature=1.,
        max_tokens=1000,
        top_p=1.    
    )

    response_message = response.choices[0].message
    
    functions_to_call = []

    if response_message.tool_calls:
        for tool_call in response_message.tool_calls:
            print("TOOL: ", tool_call)
            name = tool_call.function.name
            args = json.loads(tool_call.function.arguments)
            functions_to_call.append({ "name": name, "args": args })

    return functions_to_call

No código acima, nós:

Passamos nossas funções, que encontramos no servidor MCP e convertemos, para o LLM.
Em seguida, chamamos o LLM com essas funções.
Depois, inspecionamos o resultado para ver quais funções devemos chamar, se houver.
Finalmente, passamos um array de funções para chamar.

Último passo, vamos atualizar nosso código principal:

prompt = "Add 2 to 20"

# ask LLM what tools to all, if any
functions_to_call = call_llm(prompt, functions)

# call suggested functions
for f in functions_to_call:
    result = await session.call_tool(f["name"], arguments=f["args"])
    print("TOOLS result: ", result.content)

Lá, esse foi o último passo. No código acima, nós:

Chamamos uma ferramenta MCP via call_tool usando uma função que o LLM achou que deveríamos chamar com base em nosso prompt.
Imprimimos o resultado da chamada da ferramenta para o servidor MCP.

.NET

Vamos mostrar algum código para fazer uma solicitação de prompt ao LLM:

var tools = await GetMcpTools();

for (int i = 0; i < tools.Count; i++)
{
    var tool = tools[i];
    Console.WriteLine($"MCP Tools def: {i}: {tool}");
}

// 0. Define the chat history and the user message
var userMessage = "add 2 and 4";

chatHistory.Add(new ChatRequestUserMessage(userMessage));

// 1. Define tools
ChatCompletionsToolDefinition def = CreateToolDefinition();


// 2. Define options, including the tools
var options = new ChatCompletionsOptions(chatHistory)
{
    Model = "gpt-4o-mini",
    Tools = { tools[0] }
};

// 3. Call the model  

ChatCompletions? response = await client.CompleteAsync(options);
var content = response.Content;

No código acima, nós:

Recuperamos ferramentas do servidor MCP, var tools = await GetMcpTools().
Definimos um prompt do usuário userMessage.
Construímos um objeto de opções especificando modelo e ferramentas.
Fizemos uma solicitação ao LLM.

Um último passo, vamos ver se o LLM acha que devemos chamar uma função:

// 4. Check if the response contains a function call
ChatCompletionsToolCall? calls = response.ToolCalls.FirstOrDefault();
for (int i = 0; i < response.ToolCalls.Count; i++)
{
    var call = response.ToolCalls[i];
    Console.WriteLine($"Tool call {i}: {call.Name} with arguments {call.Arguments}");
    //Tool call 0: add with arguments {"a":2,"b":4}

    var dict = JsonSerializer.Deserialize<Dictionary<string, object>>(call.Arguments);
    var result = await mcpClient.CallToolAsync(
        call.Name,
        dict!,
        cancellationToken: CancellationToken.None
    );

    Console.WriteLine(result.Content.First(c => c.Type == "text").Text);

}

No código acima, nós:

Iteramos por uma lista de chamadas de função.
Para cada chamada de ferramenta, extraímos nome e argumentos e chamamos a ferramenta no servidor MCP usando o cliente MCP. Finalmente, imprimimos os resultados.

Aqui está o código completo:

using Azure;
using Azure.AI.Inference;
using Azure.Identity;
using System.Text.Json;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol.Transport;
using System.Text.Json;

var endpoint = "https://models.inference.ai.azure.com";
var token = Environment.GetEnvironmentVariable("GITHUB_TOKEN"); // Your GitHub Access Token
var client = new ChatCompletionsClient(new Uri(endpoint), new AzureKeyCredential(token));
var chatHistory = new List<ChatRequestMessage>
{
    new ChatRequestSystemMessage("You are a helpful assistant that knows about AI")
};

var clientTransport = new StdioClientTransport(new()
{
    Name = "Demo Server",
    Command = "/workspaces/mcp-for-beginners/03-GettingStarted/02-client/solution/server/bin/Debug/net8.0/server",
    Arguments = [],
});

Console.WriteLine("Setting up stdio transport");

await using var mcpClient = await McpClientFactory.CreateAsync(clientTransport);

ChatCompletionsToolDefinition ConvertFrom(string name, string description, JsonElement jsonElement)
{ 
    // convert the tool to a function definition
    FunctionDefinition functionDefinition = new FunctionDefinition(name)
    {
        Description = description,
        Parameters = BinaryData.FromObjectAsJson(new
        {
            Type = "object",
            Properties = jsonElement
        },
        new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase })
    };

    // create a tool definition
    ChatCompletionsToolDefinition toolDefinition = new ChatCompletionsToolDefinition(functionDefinition);
    return toolDefinition;
}



async Task<List<ChatCompletionsToolDefinition>> GetMcpTools()
{
    Console.WriteLine("Listing tools");
    var tools = await mcpClient.ListToolsAsync();

    List<ChatCompletionsToolDefinition> toolDefinitions = new List<ChatCompletionsToolDefinition>();

    foreach (var tool in tools)
    {
        Console.WriteLine($"Connected to server with tools: {tool.Name}");
        Console.WriteLine($"Tool description: {tool.Description}");
        Console.WriteLine($"Tool parameters: {tool.JsonSchema}");

        JsonElement propertiesElement;
        tool.JsonSchema.TryGetProperty("properties", out propertiesElement);

        var def = ConvertFrom(tool.Name, tool.Description, propertiesElement);
        Console.WriteLine($"Tool definition: {def}");
        toolDefinitions.Add(def);

        Console.WriteLine($"Properties: {propertiesElement}");        
    }

    return toolDefinitions;
}

// 1. List tools on mcp server

var tools = await GetMcpTools();
for (int i = 0; i < tools.Count; i++)
{
    var tool = tools[i];
    Console.WriteLine($"MCP Tools def: {i}: {tool}");
}

// 2. Define the chat history and the user message
var userMessage = "add 2 and 4";

chatHistory.Add(new ChatRequestUserMessage(userMessage));


// 3. Define options, including the tools
var options = new ChatCompletionsOptions(chatHistory)
{
    Model = "gpt-4o-mini",
    Tools = { tools[0] }
};

// 4. Call the model  

ChatCompletions? response = await client.CompleteAsync(options);
var content = response.Content;

// 5. Check if the response contains a function call
ChatCompletionsToolCall? calls = response.ToolCalls.FirstOrDefault();
for (int i = 0; i < response.ToolCalls.Count; i++)
{
    var call = response.ToolCalls[i];
    Console.WriteLine($"Tool call {i}: {call.Name} with arguments {call.Arguments}");
    //Tool call 0: add with arguments {"a":2,"b":4}

    var dict = JsonSerializer.Deserialize<Dictionary<string, object>>(call.Arguments);
    var result = await mcpClient.CallToolAsync(
        call.Name,
        dict!,
        cancellationToken: CancellationToken.None
    );

    Console.WriteLine(result.Content.First(c => c.Type == "text").Text);

}

// 5. Print the generic response
Console.WriteLine($"Assistant response: {content}");

Java

try {
    // Execute natural language requests that automatically use MCP tools
    String response = bot.chat("Calculate the sum of 24.5 and 17.3 using the calculator service");
    System.out.println(response);

    response = bot.chat("What's the square root of 144?");
    System.out.println(response);

    response = bot.chat("Show me the help for the calculator service");
    System.out.println(response);
} finally {
    mcpClient.close();
}

No código acima, nós:

Usamos prompts simples em linguagem natural para interagir com as ferramentas do servidor MCP.
O framework LangChain4j lida automaticamente com:
- Converter prompts de usuários em chamadas de ferramentas quando necessário.
- Chamar as ferramentas MCP apropriadas com base na decisão do LLM.
- Gerenciar o fluxo de conversa entre o LLM e o servidor MCP.
O método bot.chat() retorna respostas em linguagem natural que podem incluir resultados de execuções de ferramentas MCP.
Essa abordagem proporciona uma experiência perfeita ao usuário, onde ele não precisa saber sobre a implementação MCP subjacente.

Exemplo de código completo:

public class LangChain4jClient {
    
    public static void main(String[] args) throws Exception {        ChatLanguageModel model = OpenAiOfficialChatModel.builder()
                .isGitHubModels(true)
                .apiKey(System.getenv("GITHUB_TOKEN"))
                .timeout(Duration.ofSeconds(60))
                .modelName("gpt-4.1-nano")
                .timeout(Duration.ofSeconds(60))
                .build();

        McpTransport transport = new HttpMcpTransport.Builder()
                .sseUrl("http://localhost:8080/sse")
                .timeout(Duration.ofSeconds(60))
                .logRequests(true)
                .logResponses(true)
                .build();

        McpClient mcpClient = new DefaultMcpClient.Builder()
                .transport(transport)
                .build();

        ToolProvider toolProvider = McpToolProvider.builder()
                .mcpClients(List.of(mcpClient))
                .build();

        Bot bot = AiServices.builder(Bot.class)
                .chatLanguageModel(model)
                .toolProvider(toolProvider)
                .build();

        try {
            String response = bot.chat("Calculate the sum of 24.5 and 17.3 using the calculator service");
            System.out.println(response);

            response = bot.chat("What's the square root of 144?");
            System.out.println(response);

            response = bot.chat("Show me the help for the calculator service");
            System.out.println(response);
        } finally {
            mcpClient.close();
        }
    }
}

Rust

Aqui é onde ocorre a maior parte do trabalho. Chamaremos o LLM com o prompt inicial do usuário, depois processaremos a resposta para ver se alguma ferramenta precisa ser chamada. Se for o caso, chamaremos essas ferramentas e continuaremos a conversa com o LLM até que nenhuma chamada de ferramenta seja necessária e tenhamos uma resposta final. Adicione a seguinte função ao seu arquivo main.rs:

async fn call_llm(
    client: &Client<OpenAIConfig>,
    messages: &[Value],
    tools: &ListToolsResult,
) -> Result<Value, Box<dyn Error>> {
    let response = client
        .completions()
        .create_byot(json!({
            "messages": messages,
            "model": "openai/gpt-4.1",
            "tools": format_tools(tools).await?,
        }))
        .await?;
    Ok(response)
}

Essa função recebe o cliente LLM, uma lista de mensagens (incluindo o prompt do usuário), ferramentas do servidor MCP e envia uma solicitação ao LLM, retornando a resposta.

A resposta do LLM conterá um array de choices. Precisaremos processar o resultado para verificar se há tool_calls presentes. Isso nos informa que o LLM está solicitando que uma ferramenta específica seja chamada com argumentos. Adicione o seguinte código ao final do seu arquivo main.rs para definir uma função que lida com a resposta do LLM:

async fn process_llm_response(
    llm_response: &Value,
    mcp_client: &RunningService<RoleClient, ()>,
    openai_client: &Client<OpenAIConfig>,
    mcp_tools: &ListToolsResult,
    messages: &mut Vec<Value>,
) -> Result<(), Box<dyn Error>> {
    let Some(message) = llm_response
        .get("choices")
        .and_then(|c| c.as_array())
        .and_then(|choices| choices.first())
        .and_then(|choice| choice.get("message"))
    else {
        return Ok(());
    };

    // Print content if available
    if let Some(content) = message.get("content").and_then(|c| c.as_str()) {
        println!("🤖 {}", content);
    }

    // Handle tool calls
    if let Some(tool_calls) = message.get("tool_calls").and_then(|tc| tc.as_array()) {
        messages.push(message.clone()); // Add assistant message

        // Execute each tool call
        for tool_call in tool_calls {
            let (tool_id, name, args) = extract_tool_call_info(tool_call)?;
            println!("⚡ Calling tool: {}", name);

            let result = mcp_client
                .call_tool(CallToolRequestParam {
                    name: name.into(),
                    arguments: serde_json::from_str::<Value>(&args)?.as_object().cloned(),
                })
                .await?;

            // Add tool result to messages
            messages.push(json!({
                "role": "tool",
                "tool_call_id": tool_id,
                "content": serde_json::to_string_pretty(&result)?
            }));
        }

        // Continue conversation with tool results
        let response = call_llm(openai_client, messages, mcp_tools).await?;
        Box::pin(process_llm_response(
            &response,
            mcp_client,
            openai_client,
            mcp_tools,
            messages,
        ))
        .await?;
    }
    Ok(())
}

Se tool_calls estiverem presentes, a função extrai as informações da ferramenta, chama o servidor MCP com a solicitação da ferramenta e adiciona os resultados às mensagens da conversa. Em seguida, continua a conversa com o LLM, e as mensagens são atualizadas com a resposta do assistente e os resultados da chamada da ferramenta.

Para extrair as informações de chamada de ferramenta que o LLM retorna para chamadas MCP, adicionaremos outra função auxiliar para extrair tudo o que é necessário para fazer a chamada. Adicione o seguinte código ao final do seu arquivo main.rs:

fn extract_tool_call_info(tool_call: &Value) -> Result<(String, String, String), Box<dyn Error>> {
    let tool_id = tool_call
        .get("id")
        .and_then(|id| id.as_str())
        .unwrap_or("")
        .to_string();
    let function = tool_call.get("function").ok_or("Missing function")?;
    let name = function
        .get("name")
        .and_then(|n| n.as_str())
        .unwrap_or("")
        .to_string();
    let args = function
        .get("arguments")
        .and_then(|a| a.as_str())
        .unwrap_or("{}")
        .to_string();
    Ok((tool_id, name, args))
}

Com todas as partes no lugar, agora podemos lidar com o prompt inicial do usuário e chamar o LLM. Atualize sua função main para incluir o seguinte código:

// LLM conversation with tool calls
let response = call_llm(&openai_client, &messages, &tools).await?;
process_llm_response(
    &response,
    &mcp_client,
    &openai_client,
    &tools,
    &mut messages,
)
.await?;

Isso consultará o LLM com o prompt inicial do usuário pedindo a soma de dois números e processará a resposta para lidar dinamicamente com chamadas de ferramentas.

Ótimo, você conseguiu!

Tarefa

Pegue o código do exercício e desenvolva o servidor com mais ferramentas. Em seguida, crie um cliente com um LLM, como no exercício, e teste-o com diferentes prompts para garantir que todas as ferramentas do servidor sejam chamadas dinamicamente. Essa forma de construir um cliente garante que o usuário final terá uma ótima experiência, pois poderá usar prompts em vez de comandos exatos do cliente, sem perceber que um servidor MCP está sendo chamado.

Solução

Principais Aprendizados

Adicionar um LLM ao seu cliente oferece uma maneira melhor para os usuários interagirem com servidores MCP.
É necessário converter a resposta do servidor MCP para algo que o LLM possa entender.

Exemplos

Recursos Adicionais

O Que Vem a Seguir

Próximo: Consumindo um servidor usando o Visual Studio Code

Aviso Legal:
Este documento foi traduzido utilizando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional feita por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Criando um cliente com LLM

Visão Geral

Objetivos de Aprendizagem

Abordagem

Exercício: Criando um cliente com um LLM

Autenticação usando GitHub Personal Access Token

-1- Conectar ao servidor

TypeScript

Python

.NET

Java

Rust

-2- Listar capacidades do servidor

TypeScript

Python

.NET

Java

Rust

-3- Converter capacidades do servidor para ferramentas do LLM

TypeScript

Python

.NET

Java

Rust

-4- Processar solicitações de prompt do usuário

TypeScript

Python

.NET

Java

Rust

Tarefa

Solução

Principais Aprendizados

Exemplos

Recursos Adicionais

O Que Vem a Seguir

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Criando um cliente com LLM

Visão Geral

Objetivos de Aprendizagem

Abordagem

Exercício: Criando um cliente com um LLM

Autenticação usando GitHub Personal Access Token

-1- Conectar ao servidor

TypeScript

Python

.NET

Java

Rust

-2- Listar capacidades do servidor

TypeScript

Python

.NET

Java

Rust

-3- Converter capacidades do servidor para ferramentas do LLM

TypeScript

Python

.NET

Java

Rust

-4- Processar solicitações de prompt do usuário

TypeScript

Python

.NET

Java

Rust

Tarefa

Solução

Principais Aprendizados

Exemplos

Recursos Adicionais

O Que Vem a Seguir