Contribuer au serveur d'outils MCP Open Source de Vonage

Le serveur d'outils MCP de Vonage est open source et convivial pour les débutants. Ajoutez de vraies fonctionnalités SDK grâce à des PR simples et des directives MCP claires.

Introduction

Disons que vous jouez avec le serveur d'outils MCP de serveur d'outils MCP de Vonage. Vous avez vu comment les agents d'intelligence artificielle peuvent envoyer des messages de vacances joyeux via WhatsApp, RCS, ou vous avez construit un chatbot Claude. construit un chatbot Claude pour interagir avec le serveur MCP. Plutôt sympa, non ?

Mais votre cerveau se met en marche : "Attendez une seconde. Et si je voulais ajouter des MMS ? Ou peut-être vérifier depuis combien de temps un numéro a été changé de carte SIM avant de lui envoyer des informations sensibles par SMS ? Pourrais-je aussi ajouter d'autres fonctionnalités à partir de la Voice API ?"

Spoiler : Oui, vous pouvez. Et mieux encore, vous y êtes invité !

Le serveur d'outils MCP de Serveur d'outils MCP de Vonage est entièrement ouvert et prêt à recevoir vos contributions. Ce guide vous explique comment ajouter un nouvel outil (comme Verify-number) et de soumettre une demande d'extraction (PR), tout en respectant la structure des outils existants.

Voyons ce qu'il en est.

Lisez jusqu'à la fin pour découvrir un raccourci IA génial qui peut vous aider à ajouter des outils encore plus rapidement.

D'abord, comprendre la structure

Avant de plonger dans le code, prenez le temps d'explorer l'architecture. Il n'est pas nécessaire de mémoriser chaque ligne, mais la compréhension de la façon dont les pièces s'emboîtent aidera votre outil à s'intégrer en douceur.

Composants essentiels

Configuration de l'environnement et de l'authentification

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

Configuration modulaire des canaux

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

Fonction de messagerie unifiée

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

Simple, propre et conçu pour être réutilisé.

Nos modèles MCP

Nous avons beaucoup appris en construisant nos premiers outils, et nous nous sommes mis d'accord sur quelques règles empiriques qui rendent les intégrations IA-agent plus fluides et plus prévisibles. Si vous contribuez, merci de respecter ces règles :

1. Un outil = un travail

Des outils clairs et à but unique sont plus faciles à raisonner pour les agents d'intelligence artificielle. Lorsque chaque outil ne fait qu'une seule chose, il est plus facile à découvrir et à documenter, et il est beaucoup moins susceptible d'embrouiller la logique de planification de l'agent.

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

Note : Le serveur est importé du paquet MCP server bindings package

Évitez les outils à tout faire, comme les outils de travail à la chaîne :

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

2. Validez comme vous le pensez

Mauvaises entrées ? Variables d'environnement manquantes ? Il faut les repérer rapidement et clairement.

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}`);
}

Et répondez toujours d'une manière structurée que l'agent peut analyser :

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

3. Zod pour les schémas d'entrée

Veillez à ce que les choses soient sûres au niveau des types et bien documentées :

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

Si vous n'avez pas utilisé Zod il s'agit d'un moyen de définir et de valider les entrées en un seul endroit, comme les types TypeScript, mais avec des vérifications au moment de l'exécution. Il garantit que votre outil ne s'exécute que lorsque les entrées sont valides et donne aux agents des descriptions claires de la signification de chaque champ.

Vous inclurez ce inputSchema dans le cadre de la méthode server.registerTool() de sorte que lorsque votre outil est enregistré, il sait exactement à quelle forme d'entrée s'attendre et comment la valider d'emblée.

4. Les documents d'abord, toujours

Ajoutez votre outil au tableau du README et inclure un exemple d'utilisation. Votre futur utilisateur, et tous les développeurs qui suivront, vous remercieront.

Ajoutons un outil ensemble

Imaginons que vous souhaitiez contribuer à l'amélioration du MCP Tooling Server en ajoutant un nouvel outil ciblé. Dans ce cas, nous allons voir comment créer un outil qui vérifie si un numéro de téléphone a récemment fait l'objet d'une échange de carte SIM, un indicateur courant de fraude. Nous l'appellerons check-sim-swap.

Cet outil utilise l Identity Insights APIIdentity Insights, qui fournit des informations en temps réel sur un numéro de téléphone, y compris les événements de changement de carte SIM. Nous allons nous limiter à un seul outil, une seule tâche.

Étape 1 : Configurer votre environnement de développement local

Tout d'abord, faites un fork du repo du serveur MCP et clonez votre 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

Si vous n'avez pas utilisé make il s'agit essentiellement d'un programme d'exécution de tâches qui permet de regrouper plusieurs commandes. Consultez le fichier Makefile pour voir quelles commandes spécifiques sont exécutées.

Bien qu'il soit né dans les écosystèmes C et C++, il fonctionne bien pour les flux de travail généraux, y compris les projets JavaScript et TypeScript. Dans ce référentiel, nous l'utilisons pour rationaliser les commandes de routine telles que l'installation des dépendances ou la préparation de l'environnement de développement.

Ici, make setup installera les dépendances et préparera votre environnement à travailler avec le projet.

Étape 2 : Rédiger l'outil

Ouvrez maintenant src/index.ts et enregistrez votre nouvel outil auprès du serveur.

Collez le code suivant :

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}`,
        }],
      };
    }
  }
);

Cet outil fait une chose : étant donné un numéro de téléphone, il vérifie si la carte SIM a été échangée au cours des 10 derniers jours (240 heures). Si c'est le cas, il renvoie l'horodatage. Si ce n'est pas le cas, il confirme qu'il n'y a pas eu d'échange récent.

Étape 3 : Mise à jour des documents

Ouvrez le fichier README.md et ajoutez votre nouvel outil au tableau des outils :

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

Ajouter un exemple d'utilisation :

#### 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?

Étape 4 : Tester localement

Assurez-vous que votre outil est construit et qu'il passe les contrôles :

make check
make build
npm run start

Étape 5 : Créer une demande de retrait

Lorsque tout semble correct, validez et transférez vos modifications :

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

Rendez-vous sur GitHub et ouvrez votre demande de téléchargement. Vous obtiendrez des points bonus si vous incluez une capture d'écran de votre outil fonctionnant avec votre agent d'intelligence artificielle !

Modèles avancés pour des caractéristiques complexes

Vous n'en aurez probablement pas besoin pour des outils simples, mais pour des processus de longue durée ou en masse, envisagez cette structure.

Gestion des opérations asynchrones avec suivi d'état

Pour les opérations qui prennent du temps (comme les processus de vérification) :

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

Opérations par lots

Pour les opérations en vrac :

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

Quelques points à surveiller

Avant de soumettre votre pull request, assurez-vous que tout fonctionne toujours comme prévu. Exécution make check devrait permettre d'attraper la plupart des erreurs de linting et de type. Mais ne vous arrêtez pas là. Testez manuellement que tous les outils existants se comportent correctement, et vérifiez que vos ajouts n'ont pas accidentellement cassé une fonctionnalité existante. TypeScript devrait se compiler proprement avant que vous ne le poussiez.

Les noms ont plus d'importance que vous ne le pensez. Les noms d'outils doivent être écrits en majuscules (par exemple, utilisez check-sim-swap, et non checkSimSwap). Les variables d'environnement doivent respecter le format MAJUSCULES_SNAKE_CASE et toujours préfixées par VONAGE_. Et lorsque vous écrivez des fonctions, utilisez les bonnes vieilles et fiables camelCase.

La gestion des erreurs est un autre domaine critique : ne partez pas du principe que tout se passera toujours bien. Gérez les cas limites tels que les pannes de réseau, les identifiants non valides, les limites de débit de l'API et les entrées utilisateur mal formées. Si votre outil ne fonctionne pas de manière satisfaisante, il causera des maux de tête aux utilisateurs en aval et aux agents.

Enfin, si votre outil introduit de nouvelles variables d'environnement, documentez-les clairement. Ajoutez-les au tableau des variables d'environnement du README avec une brève description de la fonction de chaque clé et de son utilité. Ce petit geste de documentation peut éviter à votre futur utilisateur (ou à vos collègues contributeurs) de se prendre la tête plus tard.

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

Bonus : Utilisation conjointe des deux serveurs MCP

En travaillant avec un agent AI, vous pouvez simplifier le processus de contribution en exécutant à la fois le serveur d'outils MCP de Vonage et le serveur MCP de documentation de Vonage. Vonage Documentation MCP Server en tandem. Cette combinaison permet à votre agent d'accéder aux définitions des outils du projet ainsi qu'à la documentation officielle de l'API de Vonage, ce qui facilite l'élaboration de nouveaux outils qui suivent les modèles établis.

Lorsque les deux serveurs sont actifs, vous pouvez souvent démarrer à partir d'une invite telle que :

"Je souhaite ajouter un nouvel outil au serveur d'outils MCP de Vonage qui utilise l'API Verify pour lancer un flux de travail de vérification du téléphone. Veuillez respecter la structure d'un outil par fichier, utiliser Zod pour la validation des entrées et inclure un exemple d'utilisation dans le README. Référez-vous à la documentation de Vonage pour les derniers paramètres."

Cette approche ne remplacera pas les tests ou les révisions, mais elle peut vous aider à avancer rapidement et à aligner vos changements sur les conventions du projet.

Conclusion

L'open source fonctionne mieux lorsque des personnes comme vous s'impliquent. Si vous avez une idée pour une nouvelle fonctionnalité du SDK, qu'il s'agisse de MMS, de gestion des appels ou même de gestion des comptes, créez-la ! Et si vous ne savez pas par où commencer, contactez-nous et nous pourrons y travailler ensemble. Nous aimons les RP !

Nous sommes impatients de voir ce que vous allez inventer.