MCP for Dart

MCP (Model Context Protocol) para Dart

mcp_dart é um SDK Dart e Flutter de dupla era para clientes, servidores e hosts de IA MCP. Ele implementa a superfície de wire completa do núcleo cliente/servidor da especificação MCP 2026-07-28 bloqueada, mantém o conjunto de recursos MCP 2025-11-25 e negocia especificações anteriores suportadas baseadas em inicialização.

Aqui, núcleo significa os requisitos normativos de wire atribuídos aos papéis de cliente e servidor pela especificação final fixada. Isso exclui extensões MCP opcionais, comportamento de UI do host, uma implementação de servidor de autorização, resolução de referência externa JSON Schema e vocabulários JSON Schema personalizados.

[!IMPORTANT] Os pacotes estáveis atuais são mcp_dart 2.4.0 e mcp_dart_cli 0.2.0; a restrição de SDK ^2.3.0 da CLI aceita 2.4. O código-fonte atual passa em todos os requisitos pontuados nos conjuntos oficiais de cliente e servidor alpha.11 MCP 2025-11-25 e 2026-07-28, incluindo todos os 25 cenários de autorização 2026 exigidos, além de interoperabilidade bidirecional com o SDK TypeScript 2.0.0 e o SDK Python 2.0.0 publicados.

Meta do SDK Nível 1

O projeto está buscando MCP SDK Nível 1. O Nível 1 ainda não é reivindicado ou atribuído. A linha de base técnica está verde; as etapas restantes de auditoria oficial, governança de repositório e Grupo de Trabalho do SDK são rastreadas no roteiro e no inventário de cobertura de 48 recursos.

O contrato público de manutenção está documentado no guia de contribuição, política de segurança, política de dependências e política de versionamento.

Requisitos

Pacote	SDK Dart mínimo
mcp_dart 2.4.0	3.4
mcp_dart_cli 0.2.0	3.12

Projetos gerados apenas com SDK mantêm o mínimo Dart 3.4 do SDK. Projetos CLI usam Dart 3.12 porque a CLI e sua cadeia de ferramentas têm como alvo essa versão.

Instale o Dart em dart.dev.

Instalação

Canal de produção

Use o pacote estável mais recente para projetos de produção:

dart pub add mcp_dart

Fixar a versão estável do SDK

Fixe explicitamente a linha estável 2.4 quando a resolução reprodutível de dependências for importante:

dependencies:
  mcp_dart: ^2.4.0

Os trechos abaixo usam a linha estável atual do SDK. As versões dos pacotes permanecem separadas dos perfis de protocolo: McpProtocol.stable nomeia a política de compatibilidade padrão do SDK.

O SDK e a CLI são versionados de forma independente. A restrição ^2.3.0 da CLI estável permanece compatível com o SDK 2.4.

Para integração direta com o SDK, comece com o guia de introdução. A CLI abaixo é opcional e fornece comandos de scaffolding, inspeção e conformidade.

O que o SDK oferece

• Servidores, clientes e integrações de host MCP com APIs Dart null-safe.
• APIs principais de ferramentas, recursos, prompts, conclusão, elicitação, assinaturas, logging, raízes e amostragem com comportamento selecionado para a era de protocolo negociada. O logging MCP 2026-07-28 é mantido para compatibilidade, mas está obsoleto upstream.
• Transports Stdio, Streamable HTTP, fluxo de IO e personalizados.
• Hooks de descoberta/PKCE de cliente OAuth, callbacks de autenticação de servidor, proteção contra rebinding de DNS e validação estrita de Streamable HTTP.
• Uma implementação experimental de extensão Tasks, auxiliares de metadados MCP Apps e negociação genérica de extensões. As extensões são separadas da cobertura principal do protocolo; Tasks não é uma extensão oficial nem parte da reivindicação de conformidade principal do SDK.
• Conformidade automatizada MCP 2025-11-25 e MCP 2026-07-28, interoperabilidade bidirecional com o SDK TypeScript 2.0.0 publicado, interoperabilidade bidirecional com o SDK Python 2.0.0, testes de transporte em navegador real, uma integração real de serviço Flutter Web no Chrome, testes de widget determinísticos e um portão independente do Test Suite JSON Schema fixado.
• mcp_dart 2.4.0 adiciona um cliente legado HTTP+SSE obsoleto e opcional com roteamento de mesma origem e interoperabilidade bidirecional contra pares oficiais do SDK TypeScript 1.30.0 e SDK Python 2.0.0.

O MCP tem três papéis: um host possui a experiência do usuário, um cliente conecta esse host a um servidor, e um servidor expõe ferramentas, recursos e prompts. Um host pode gerenciar vários clientes e servidores.

Perfis de protocolo

Perfil	Comportamento do protocolo
McpProtocol.stable	Perfil padrão de dupla era: prefira MCP 2026-07-28, depois volte para especificações MCP baseadas em inicialização; sondas de descoberta somente com corpo são limitadas a 5 segundos
McpProtocol.legacy	Perfil da era de inicialização: negocie a especificação MCP 2025-11-25, MCP 2025-06-18, MCP 2025-03-26, MCP 2024-11-05 ou MCP 2024-10-07
McpProtocol.require2026	Exija MCP 2026-07-28 e rejeite inicialização legada

Use stableProtocolVersion ou defaultProtocolVersion para MCP 2026-07-28. previewProtocolVersion permanece como um alias obsoleto para aplicativos construídos contra um pré-lançamento 2.3. latestInitializationProtocolVersion permanece 2025-11-25 quando o perfil padrão volta para o ciclo de vida legado. Para compatibilidade, latestProtocolVersion e supportedProtocolVersions mantêm seus valores da era de inicialização mcp_dart 2.2; use allSupportedProtocolVersions para a lista de dupla era.

Selecione um perfil somente quando precisar restringir a negociação:

final legacyClient = McpClient(
  const Implementation(name: 'my-client', version: '1.0.0'),
  options: const McpClientOptions(protocol: McpProtocol.legacy),
);

final strict2026Server = McpServer(
  const Implementation(name: 'my-server', version: '1.0.0'),
  options: const McpServerOptions(protocol: McpProtocol.require2026),
);

Consulte o guia de transição MCP 2026-07-28 para regras de fallback e APIs específicas do MCP 2026-07-28, ou execute o exemplo estrito MCP 2026-07-28. Aplicativos que atualizam da linha estável 2.2 também devem seguir o guia de migração 2.2 para 2.3.

Início rápido com a CLI

Instale a CLI estável correspondente:

dart pub global activate mcp_dart_cli 0.2.0
mcp_dart create my_server
cd my_server
mcp_dart inspect

A CLI 0.2.0 cria um projeto com mcp_dart: ^2.3.0. O inspetor inicia o servidor stdio gerado por conta própria. Depois de sair do inspetor interativo, você pode executar uma única ferramenta diretamente:

mcp_dart inspect --tool add --json-args '{"a": 1, "b": 2}'

Comandos úteis:

Comando	Finalidade
create	Criar um servidor MCP Dart usando o canal SDK emparelhado com a CLI
serve	Executar um servidor gerado via stdio ou HTTP
doctor	Verificar a saúde e a conectividade do projeto
inspect	Usar interativamente os recursos de um servidor
inspect-server	Produzir um relatório estruturado para um servidor ativo
inspect-client	Executar um harness stdio que inspeciona um cliente conectado
trace	Fazer proxy e registrar uma sessão stdio real
conformance	Executar os fixtures de regressão de protocolo integrados do repositório

Consulte a documentação da CLI para opções de comando e escopo.

Documentação

• Comece: introdução, guia do servidor, guia do cliente, referência rápida
• Atualize: guia de migração 2.2 para 2.3, livros de receitas de migração, guia de transição MCP 2026-07-28
• Construa: ferramentas, transports, exemplos, MCP Apps
• Implante: segurança Streamable HTTP, exemplos OAuth, receitas Flutter
• Verifique: matriz de interoperabilidade, cobertura MCP 2025-11-25, cobertura MCP 2026-07-28, runbook do dia 0

Exemplos de integração independentes podem declarar requisitos mais novos de SDK Dart; verifique o README de cada exemplo antes de executá-lo.

Autenticação

StreamableHttpClientTransport suporta OAuthClientProvider e descoberta opcional de código de autorização. Servidores podem usar authenticator ou authenticationHandler e publicar metadados de recursos protegidos.

Os exemplos OAuth verificados armazenam tokens em arquivos de texto simples para aprendizado local. Aplicativos de produção devem usar armazenamento seguro da plataforma ou um serviço de credenciais criptografado. Consulte os exemplos OAuth e autenticação Streamable HTTP.

Não exponha servidores HTTP de exemplo diretamente a redes não confiáveis. Implantações de produção devem usar TLS, autenticar solicitações e configurar as proteções de Host e Origem documentadas.

Suporte de plataforma

Alvo	Stdio	Streamable HTTP	HTTP+SSE legado	Fluxo IO/personalizado
VM Dart / servidor desktop	Sim	Cliente e servidor	Cliente e servidor	Sim
Navegador / Flutter Web	Sem spawn de processo	Cliente	Cliente	Sim
Flutter mobile	Somente auxiliares nativos gerenciados pelo aplicativo	Cliente remoto	Cliente remoto	Sim
Flutter desktop	Processos auxiliares locais	Cliente e servidor	Cliente e servidor	Sim

HTTP+SSE legado está obsoleto sob MCP SEP-2596 e é mantido apenas para compatibilidade explícita. Use Streamable HTTP para novas integrações remotas.

Consulte receitas de host e cliente Flutter para orientação sobre ciclo de vida e armazenamento seguro.

Escolhendo um pacote MCP Dart

A equipe Dart mantém dart_mcp em dart-lang/ai. Escolha-o quando preferir as APIs da equipe Dart. Escolha mcp_dart quando precisar da superfície de transporte, segurança, compatibilidade, extensão e inspeção deste SDK. Verifique novamente as versões atuais de ambos os pacotes antes de uma decisão de produção.

Suporte

• Problemas e relatórios de bugs
• Política de contribuição e triagem de problemas
• Política de segurança
• Política de dependências
• Política de versionamento
• Roteiro Nível 1
• SDK no pub.dev
• Referência da API 2.4.0
• Changelog
• Especificação MCP 2026-07-28
• Especificação MCP 2025-11-25