MCP Sem Boilerplate: Servidor e Cliente Auto-Curativo da Solon AI

Se você tem acompanhado esta série, viu como a Solon AI transmite chat como eventos semânticos e como ela divide documentos por significado. Desta vez, passamos da infraestrutura de conversa para a infraestrutura de capacidade: como a Solon AI transforma código Java comum em serviços MCP (Modelo de Protocolo de Contexto), e como consome servidores MCP remotos sem escrever código de protocolo manualmente.

Todo o código neste post foi verificado contra a árvore de origem da Solon AI 4.1.x (solon-ai-mcp e mcp-core módulos).

Por que MCP e por que em processo?

O MCP padroniza como uma aplicação LLM descobre e invoca ferramentas, lê recursos e carrega prompts de um provedor externo. Em vez de codificar chamadas de função em seu pipeline de prompt, você aponta seu aplicativo para um endpoint MCP — local ou remoto — e a lista de capacidades chega pela rede.

A Solon AI oferece suporte ao MCP em duas camadas:

• mcp-core — uma implementação de protocolo autônoma cobrindo revisões da especificação MCP de 2024-11-05 até 2025-11-25.
• solon-ai-mcp — a camada voltada para a aplicação: um servidor orientado a anotações e um cliente compatível com ToolProvider que se conecta diretamente ao ChatModel.

O objetivo de design é visível na direção da dependência: a camada de protocolo não sabe nada sobre a Solon AI, e a camada de integração adiciona quase nada que você tenha que aprender.

O servidor: uma anotação por capacidade

Declare uma classe de endpoint com @McpServerEndpoint, depois anote métodos simples:

@McpServerEndpoint(
        mcpEndpoint = "/mcp/sse",
        heartbeatInterval = "30s")
@Component
public class McpServerTool {
    // Dica: habilite a flag do compilador -parameters,
    // ou dê a cada @Param um nome explícito.
    @ToolMapping(description = "查询天气预报")
    public String getWeather(@Param(description = "城市位置") String location) {
        return "晴，14度";
    }
}

Esse é o servidor completo. Na inicialização, McpPlugin escaneia classes @McpServerEndpoint e constrói um McpServerEndpointProvider a partir delas. Provedores em nível de método — MethodToolProvider, MethodResourceProvider, MethodPromptProvider — extraem métodos @ToolMapping, @ResourceMapping e @PromptMapping e os registram com o ciclo de vida do endpoint. Sem esquemas JSON para manter manualmente, sem interruptor de despacho, sem fiação de transporte.

Detalhes que vale a pena saber:

• heartbeatInterval tem como padrão "30s" no lado do servidor.
• sseEndpoint() e messageEndpoint() estão obsoletos; o unificado mcpEndpoint() é o caminho a seguir.
• Existem dois modelos de hospedagem: um host com estado (STREAMABLE canal) que mantém o estado da sessão por cliente, e um sem estado (STREAMABLE_STATELESS) onde cada solicitação carrega tudo o que precisa — a melhor opção atrás de balanceadores de carga.
• enableOutputSchema() pode ativar a validação do esquema de saída para ferramentas que precisam disso.

O cliente: McpClientProvider

No lado do consumidor, uma classe implementa ToolProvider, ResourceProvider e PromptProvider:

McpClientProvider mcpClient = McpClientProvider.builder()
        .url("http://localhost:8081/sse")
        .build();

ChatModel chatModel = ChatModel.of(chatConfig)
        .defaultToolAdd(mcpClient)
        .build();

ChatResponse resp = chatModel
        .prompt("杭州天气和北京降雨量如何？")
        .call();

O provedor é preguiçoso: o McpAsyncClient subjacente é criado no primeiro uso, protegido por um bloqueio. A partir de então, ChatModel trata as ferramentas MCP exatamente como ferramentas de função locais — o modelo as vê em sua lista de ferramentas, escolhe uma e a Solon AI roteia a invocação através de callTool(name, args).

Quatro canais, um construtor

McpChannel define STDIO, SSE, STREAMABLE e STREAMABLE_STATELESS. O construtor escolhe o transporte para você:

Para granularidade por chamada em vez de padrões, empurre a lista de ferramentas nas opções do prompt:

chatModel.prompt("今天杭州的天气情况？")
        .options(options -> options.toolAdd(mcpClient)