Contribua com o servidor de ferramentas de código aberto do Vonage MCP

O servidor de ferramentas MCP da Vonage é de código aberto e fácil de usar para iniciantes. Adicione recursos reais do SDK por meio de PRs simples e diretrizes claras do MCP.

Introdução

Então, digamos que você esteja experimentando o Servidor de Ferramentas MCP da Vonage. Você já viu como os agentes de IA podem enviar mensagens festivas e animadas pelo WhatsApp, RCS, ou já criou um chatbot Claude para interagir com o MCP Server. Muito legal, né?

Mas então você tem um lampejo: “Espera aí. E se eu quiser adicionar MMS? Ou talvez verificar há quanto tempo um número sofreu troca de SIM antes de enviar informações confidenciais por mensagem de texto? Será que eu poderia adicionar mais recursos da Voice API também?”

Spoiler: Sim, você pode. E melhor ainda: você está convidado!

O Servidor de Ferramentas do MCP da Vonage é totalmente de código aberto e está pronto para receber suas contribuições. Este guia explica como adicionar uma nova ferramenta (como verify-number) e enviar uma solicitação de pull (PR), mantendo tudo alinhado com a estrutura das ferramentas existentes.

Vamos ao que interessa.

Leia até o fim para conhecer um atalho legal com IA que pode te ajudar a adicionar ferramentas ainda mais rápido.

Primeiro, entenda a estrutura

Antes de mergulhar no código, reserve um tempo para explorar a arquitetura. Você não precisa memorizar cada linha, mas entender como as peças se encaixam ajudará sua ferramenta a se integrar sem problemas.

Componentes principais

Configuração do ambiente e das autorizações

const vonage = new Vonage(
  new Auth({
    apiKey: process.env.VONAGE_API_KEY!,
    apiSecret: process.env.VONAGE_API_SECRET!,
    applicationId: appId!,
    privateKey: privateKey,
  })
);

Configuração modular de canais

const CHANNEL_CONFIGS = {
  whatsapp: {
    channel: Channels.WHATSAPP,
    getFrom: () => whatsappNumber,
    requiresValidation: () => !!whatsappNumber,
    validationError: 'VONAGE_WHATSAPP_NUMBER is not set.',
  },
  // ...rcs, sms, etc.
};

Função de Mensagens Unificadas

async function sendChannelMessage(channelKey, to, message, useFailover = false) {
  // This one handles everything from validation to failover logic
}

Simples, elegante e projetado para ser reutilizado.

Nossos padrões MCP

Aprendemos muito ao desenvolver nossas primeiras ferramentas e estabelecemos algumas diretrizes práticas que tornam as integrações com agentes de IA mais tranquilas e previsíveis. Se você estiver contribuindo, por favor, siga essas diretrizes:

1. Uma ferramenta = uma tarefa

Ferramentas claras e com uma única finalidade são mais fáceis de serem compreendidas pelos agentes de IA. Quando cada ferramenta faz exatamente uma coisa, ela se torna mais fácil de identificar, mais simples de documentar e muito menos propensa a confundir a lógica de planejamento do agente.

server.registerTool('whatsapp-send-text', {...});
server.registerTool('whatsapp-send-text-with-sms-failover', {...});

Observação: o servidor é importado do pacote de ligações do servidor MCP

Evite ferramentas multifuncionais, como:

server.registerTool('send-message', {
  inputSchema: {
    channel: z.enum(['whatsapp', 'rcs', 'sms']),
    useFailover: z.boolean().optional(),
    // too many optional inputs = confusing agents
  }
});

2. Valide com convicção

Entradas incorretas? Variáveis de ambiente ausentes? Identifique esses problemas logo no início e com clareza.

if (!whatsappNumber) {
  throw new Error('VONAGE_WHATSAPP_NUMBER is not set.');
}

const formatted = await formatPhoneNumber(to);
if (!formatted) {
  throw new Error(`Invalid phone number format: ${to}`);
}

E sempre responda de maneira estruturada, para que o agente possa interpretar:

return {
  content: [{ type: 'text', text: `Error: ${error.message}` }],
};

3. Zod para esquemas de entrada

Mantenha tudo com segurança de tipos e bem documentado:

inputSchema: {
  to: z.string().describe('Recipient phone number in E.164 format'),
  message: z.string().describe('Message content to send'),
}

Se você ainda não usou o Zod antes, pense nele como uma maneira de definir e validar entradas em um único lugar, como os tipos do TypeScript, mas com verificações em tempo de execução. Ele garante que sua ferramenta só seja executada quando as entradas forem válidas e fornece aos agentes descrições claras do que cada campo significa.

Você incluirá isto inputSchema como parte do server.registerTool() , de modo que, quando sua ferramenta for registrada, ela saiba exatamente qual formato de entrada esperar e como validá-la antecipadamente.

4. A documentação em primeiro lugar, sempre

Adicione sua ferramenta à tabela do README e inclua um exemplo de uso. Seu eu do futuro, e todos os desenvolvedores que vierem depois de você, vão agradecer.

Vamos adicionar uma ferramenta juntos

Digamos que você queira ajudar a melhorar o MCP Tooling Server adicionando uma nova ferramenta específica. Nesse caso, vamos explicar como criar uma ferramenta que verifique se um número de telefone passou recentemente por uma troca de SIM, um indicador comum de fraude. Vamos chamá-la de check-sim-swap.

Esta ferramenta utiliza a API do Identity Insights, que fornece informações em tempo real sobre um número de telefone, incluindo eventos de troca de SIM. Vamos manter o escopo bem definido: uma ferramenta, uma função.

Passo 1: Configure seu ambiente de desenvolvimento local

Primeiro, faça um fork do repositório do servidor MCP e clone seu fork:

# Fork the repo on GitHub
git clone https://github.com/YOUR_USERNAME/vonage-mcp-server-api-bindings.git
cd vonage-mcp-server-api-bindings

make setup

Se você ainda não usou o make antes, ele é basicamente um executador de tarefas que ajuda a agrupar vários comandos. Dê uma olhada no Makefile para ver quais comandos específicos estão sendo executados.

Embora tenha surgido nos ecossistemas do C e do C++, ele também funciona bem para fluxos de trabalho de uso geral, incluindo projetos em JavaScript e TypeScript. Neste repositório, nós o utilizamos para otimizar comandos de rotina, como a instalação de dependências ou a preparação do ambiente de desenvolvimento.

Aqui, o comando `setup` instalará as dependências e deixará seu ambiente pronto para trabalhar com o projeto.

Etapa 2: Escrever a ferramenta

Agora abra src/index.ts e registre sua nova ferramenta no servidor.

Cole o código a seguir:

server.registerTool(
  'check-sim-swap',
  {
    title: 'SIM Swap Check',
    description: 'Check if a phone number has recently had a SIM change.',
    inputSchema: {
      number: z.string().describe('Phone number in E.164 format'),
    },
  },
  async ({ number }) => {
    try {
      const formatted = await formatPhoneNumber(number);
      if (!formatted) {
        throw new Error(`Invalid phone number format: ${number}`);
      }

      const response = await vonage.identityInsights.getInsights({
        phone_number: formatted,
        purpose: 'FraudPreventionAndDetection',
        insights: {
          sim_swap: {
            period: 240 // last 240 hours
          }
        }
      });

      const { sim_swap } = response.insights;

      return {
        content: [{
          type: 'text',
          text: sim_swap?.is_swapped
            ? `SIM swap detected! Most recent swap was on: ${sim_swap.latest_sim_swap_at}`
            : `No recent SIM swap detected.`,
        }],
      };
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `Error checking SIM swap: ${error.message}`,
        }],
      };
    }
  }
);

Essa ferramenta faz uma única coisa: a partir de um número de telefone, ela verifica se o cartão SIM foi trocado nos últimos 10 dias (240 horas). Se for o caso, ela retorna o carimbo de data e hora. Caso contrário, ela confirma que não houve nenhuma troca recente.

Etapa 3: Atualizar a documentação

Abra o arquivo arquivo README.md e adicione sua nova ferramenta à tabela de ferramentas:

| **Identity** | `check-sim-swap` | Check if a phone number has had a recent SIM change |

Adicione um exemplo de uso:

#### Check if a phone number has had a SIM swap

Can you check whether +14155550123 has had a SIM swap in the past 10 days?

Etapa 4: Testar localmente

Certifique-se de que sua ferramenta seja compilada e passe nas verificações:

make check
make build
npm run start

Etapa 5: Crie sua solicitação de pull

Quando tudo estiver certo, faça o commit e envie suas alterações:

git checkout -b feature/add-check-sim-swap
git add .
git commit -m "Add check-sim-swap tool with Zod validation and Identity Insights API"
git push origin feature/add-check-sim-swap

Acesse o GitHub e abra sua solicitação de pull. Você ganha pontos extras se incluir uma captura de tela da sua ferramenta funcionando com o seu Agente de IA!

Padrões avançados para características complexas

Provavelmente você não precisará disso para ferramentas simples, mas, para processos demorados ou em massa, considere essa estrutura.

Gerenciamento de operações assíncronas com acompanhamento de status

Para operações que levam tempo (como fluxos de trabalho de verificação):

server.registerTool('start-verification', {
  inputSchema: {
    number: z.string(),
    workflow_id: z.string().optional(),
  },
  async ({ number, workflow_id }) => {
    // Implement tracking logic here
  }
});

Operações em lote

Para operações em massa:

server.registerTool('verify-numbers-batch', {
  inputSchema: {
    numbers: z.array(z.string()),
  },
  async ({ numbers }) => {
    // Loop through and verify all
  }
});

Algumas coisas a se ter em atenção

Antes de enviar sua solicitação de pull, certifique-se de que tudo ainda funcione conforme o esperado. Execute make check deve detectar a maioria dos erros de linting e de tipagem. Mas não pare por aí. Teste manualmente se todas as ferramentas existentes estão funcionando corretamente e verifique novamente se suas adições não prejudicaram acidentalmente nenhuma funcionalidade existente. O TypeScript deve compilar sem erros antes de você fazer o push.

A escolha do nome é mais importante do que você imagina. Use o formato “kebab-case” para os nomes das ferramentas (por exemplo, use check-sim-swap, e não checkSimSwap). As variáveis de ambiente devem seguir a convenção convenção UPPER_SNAKE_CASE , sempre precedidas por VONAGE_. E ao escrever funções, use o bom e velho camelCase.

O tratamento de erros é outra área crítica: não presuma que tudo sempre correrá bem. Lide com casos extremos, como falhas de rede, credenciais inválidas, limites de taxa da API e entradas de usuário com formato incorreto. Se sua ferramenta não lidar com erros de maneira adequada, isso causará dores de cabeça tanto para os usuários quanto para os agentes.

Por fim, se sua ferramenta introduzir novas variáveis de ambiente, documente-as com clareza. Adicione-as à tabela de variáveis de ambiente do arquivo README, incluindo uma breve descrição do que cada chave faz e se ela é obrigatória. Esse pequeno ato de documentação pode poupar a você mesmo no futuro (ou aos seus colegas colaboradores) muita dor de cabeça mais tarde.

Checklist of contribution requirements for a Vonage open-source pull request, including code quality, documentation, testing, security, and consistency.

Bônus: Como usar os dois servidores MCP em conjunto

Ao trabalhar com um agente de IA, você pode simplificar o processo de contribuição executando tanto o Servidor de Ferramentas MCP da Vonage quanto a Servidor de Documentação MCP da Vonage em conjunto. Essa combinação dá ao seu agente acesso às definições de ferramentas do projeto, bem como à documentação oficial da API da Vonage, o que facilita a criação de novas ferramentas que sigam os padrões estabelecidos.

Com os dois servidores ativos, muitas vezes é possível começar com um prompt como este:

“Gostaria de adicionar uma nova ferramenta ao Servidor de Ferramentas do MCP da Vonage que utilize a Verify API para iniciar um fluxo de trabalho de verificação por telefone. Por favor, siga a estrutura de uma ferramenta por arquivo, utilize o Zod para validação de entradas e inclua um exemplo de uso no arquivo README. Consulte a documentação da Vonage para obter os parâmetros mais recentes.”

Essa abordagem não substituirá os testes nem a revisão, mas pode ajudá-lo a agir com rapidez e manter suas alterações alinhadas às convenções do projeto.

Conclusão

O código aberto funciona melhor quando pessoas como você se envolvem. Se você tem uma ideia para um novo recurso do SDK — seja MMS, gerenciamento de chamadas ou até mesmo gerenciamento de Accounts —, crie-o! E se você não souber por onde começar, entre em contato, e podemos trabalhar nisso juntos. Adoramos PRs!

Estamos ansiosos para ver o que vocês vão criar.