Tragen Sie zum Open Source Vonage MCP Tooling Server bei

Der Vonage MCP Tooling Server ist Open Source und anfängerfreundlich. Fügen Sie echte SDK-Funktionen durch unkomplizierte PRs und klare MCP-Richtlinien hinzu.

Einführung

Nehmen wir also an, Sie spielen mit dem Vonage MCP Tooling Server. Sie haben gesehen, wie KI-Agenten fröhliche Urlaubsnachrichten über WhatsApp oder RCS senden können, oder Sie haben einen Claude Chatbot gebaut gebaut, der mit dem MCP Server interagiert. Ziemlich klasse, oder?

Aber dann schaltet sich Ihr Gehirn ein: "Moment mal. Was, wenn ich MMS hinzufügen möchte? Oder vielleicht prüfen, wie lange eine Nummer schon mit der SIM-Karte getauscht wurde, bevor ich ihr sensible Informationen schicke? Könnte ich auch weitere Funktionen über die Voice API hinzufügen?"

Spoiler: Ja, Sie können. Und was noch besser ist, du bist dazu eingeladen!

Der Vonage MCP Tooling Server ist vollständig quelloffen und bereit für Ihre Beiträge. Diese Anleitung zeigt Ihnen, wie Sie ein neues Tool (wie verify-number) und einen Pull-Request (PR) einreichen, wobei alles mit der Struktur der bestehenden Tools übereinstimmt.

Schauen wir genauer hin.

Lesen Sie bis zum Ende, um eine coole KI-Verknüpfung zu entdecken, mit der Sie Werkzeuge noch schneller hinzufügen können.

Verstehen Sie zunächst die Struktur

Bevor Sie in den Code eintauchen, nehmen Sie sich etwas Zeit, um die Architektur zu erkunden. Sie müssen nicht jede Zeile auswendig lernen, aber wenn Sie verstehen, wie die Teile zusammenpassen, kann sich Ihr Tool reibungslos einfügen.

Kernkomponenten

Umgebung & Autorisierungseinstellungen

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

Modulare Kanalkonfiguration

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

Unified Messaging-Funktion

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

Einfach, sauber und für die Wiederverwendung konzipiert.

Unsere MCP-Muster

Wir haben viel gelernt, während wir unsere ersten Tools entwickelt haben, und wir haben uns auf einige Faustregeln geeinigt, die die Integration von KI-Agenten reibungsloser und berechenbarer machen. Wenn Sie einen Beitrag leisten, halten Sie sich bitte an diese Regeln:

1. Ein Werkzeug = eine Aufgabe

KI-Agenten können mit eindeutigen, zweckgebundenen Werkzeugen besser umgehen. Wenn jedes Werkzeug genau eine Aufgabe erfüllt, ist es leichter auffindbar, einfacher zu dokumentieren und bringt die Planungslogik des Agenten weit weniger durcheinander.

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

Anmerkung: Der Server wird importiert aus dem MCP-Server-Bindungspaket

Vermeiden Sie Allround-Tools wie:

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

2. Bestätigen Sie, als ob Sie es ernst meinen

Falsche Eingaben? Fehlende Umgebungsvariablen? Erkennen Sie diese frühzeitig und eindeutig.

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

Und antworten Sie immer in einer strukturierten Form, die der Agent analysieren kann:

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

3. Zod für Eingabeschemata

Halten Sie die Dinge typsicher und gut dokumentiert:

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

Falls Sie noch nicht mit Zod noch nicht verwendet haben, sollten Sie es als eine Möglichkeit betrachten, Eingaben an einem Ort zu definieren und zu validieren, wie TypeScript-Typen, aber mit Laufzeitprüfungen. Es stellt sicher, dass Ihr Tool nur ausgeführt wird, wenn die Eingaben gültig sind, und gibt Agenten klare Beschreibungen, was jedes Feld bedeutet.

Sie fügen dieses inputSchema als Teil der Methode server.registerTool() Aufrufs, so dass es bei der Registrierung Ihres Tools genau weiß, welche Eingabeform es erwarten kann und wie es im Vorfeld zu validieren ist.

4. Dokumente zuerst, immer

Fügen Sie Ihr Werkzeug in die README-Tabelle und fügen Sie ein Anwendungsbeispiel hinzu. Ihr zukünftiges Ich und jeder Entwickler nach Ihnen wird es Ihnen danken.

Lassen Sie uns gemeinsam ein Werkzeug hinzufügen

Nehmen wir an, Sie möchten den MCP Tooling Server verbessern, indem Sie ein gezieltes neues Tool hinzufügen. In diesem Fall zeigen wir Ihnen, wie Sie ein Tool erstellen, das prüft, ob eine Telefonnummer kürzlich einen SIM-Tausch, ein üblicher Indikator für Betrug. Wir nennen es check-sim-swap.

Dieses Tool verwendet die Identitätseinblicke-APIdie Echtzeit-Informationen über eine Telefonnummer liefert, einschließlich SIM-Wechsel-Ereignisse. Wir halten die Dinge im Rahmen: ein Tool, eine Aufgabe.

Schritt 1: Einrichten Ihrer lokalen Entwicklungsumgebung

Forken Sie zunächst das MCP-Server-Repository und klonen Sie Ihren 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

Wenn Sie noch nicht mit make noch nie benutzt haben, ist es im Wesentlichen ein Task-Runner, der dabei hilft, mehrere Befehle zu bündeln. Schauen Sie sich das Makefile um zu sehen, welche spezifischen Befehle ausgeführt werden.

Obwohl es ursprünglich für C- und C++-Ökosysteme entwickelt wurde, eignet es sich auch für allgemeine Arbeitsabläufe, einschließlich JavaScript- und TypeScript-Projekten. In diesem Repository verwenden wir es, um Routinebefehle wie die Installation von Abhängigkeiten oder die Vorbereitung der Entwicklungsumgebung zu rationalisieren.

hier, make setup installiert die Abhängigkeiten und macht Ihre Umgebung bereit für die Arbeit mit dem Projekt.

Schritt 2: Schreiben Sie das Tool

Öffnen Sie nun src/index.ts und registrieren Sie Ihr neues Tool auf dem Server.

Fügen Sie den folgenden Code ein:

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

Dieses Tool hat nur eine Aufgabe: Es prüft anhand einer Telefonnummer, ob die SIM-Karte in den letzten 10 Tagen (240 Stunden) ausgetauscht wurde. Wenn ja, gibt es den Zeitstempel zurück. Wenn nicht, bestätigt es, dass kein Austausch stattgefunden hat.

Schritt 3: Aktualisieren der Dokumente

Öffnen Sie die README.md und fügen Sie Ihr neues Werkzeug in die Werkzeugtabelle ein:

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

Fügen Sie ein Anwendungsbeispiel hinzu:

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

Schritt 4: Lokaler Test

Vergewissern Sie sich, dass Ihr Werkzeug gebaut wird und die Prüfungen besteht:

make check
make build
npm run start

Schritt 5: Erstellen Sie Ihren Pull Request

Wenn alles gut aussieht, übertragen Sie die Änderungen und veröffentlichen Sie sie:

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

Gehen Sie zu GitHub und öffnen Sie Ihren Pull-Request. Bonuspunkte für einen Screenshot Ihres Tools, das mit Ihrem KI-Agenten arbeitet!

Erweiterte Muster für komplexe Merkmale

Für einfache Werkzeuge werden Sie dies wahrscheinlich nicht benötigen, aber für lang laufende oder umfangreiche Prozesse sollten Sie diese Struktur in Betracht ziehen.

Handhabung asynchroner Vorgänge mit Statusverfolgung

Für Vorgänge, die Zeit in Anspruch nehmen (wie Überprüfungsabläufe):

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

Stapelverarbeitung

Für Massengeschäfte:

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

Ein paar Dinge, auf die man achten sollte

Bevor Sie Ihren Pull-Request einreichen, stellen Sie sicher, dass alles noch wie erwartet funktioniert. Ausführen von make check sollte die meisten Linting- und Typfehler aufdecken. Aber hören Sie damit nicht auf. Testen Sie manuell, ob sich alle vorhandenen Werkzeuge korrekt verhalten, und überprüfen Sie, ob Ihre Ergänzungen nicht versehentlich eine vorhandene Funktionalität zerstört haben. TypeScript sollte sauber kompiliert sein, bevor Sie es pushen.

Die Namensgebung ist wichtiger, als Sie vielleicht denken. Bleiben Sie bei der Großschreibung von Werkzeugnamen (verwenden Sie zum Beispiel check-sim-swap, nicht checkSimSwap). Umgebungsvariablen sollten der UPPER_SNAKE_CASE Konvention folgen, immer mit dem Präfix VONAGE_. Und wenn Sie Funktionen schreiben, verwenden Sie die gute alte, zuverlässige camelCase.

Ein weiterer kritischer Bereich ist die Fehlerbehandlung: Gehen Sie nicht davon aus, dass alles immer reibungslos abläuft. Behandeln Sie Grenzfälle wie Netzwerkausfälle, ungültige Anmeldedaten, API-Ratenbeschränkungen und fehlerhafte Benutzereingaben. Wenn Ihr Tool nicht ordnungsgemäß funktioniert, wird es sowohl den nachgeschalteten Benutzern als auch den Agenten Kopfschmerzen bereiten.

Wenn Ihr Tool neue Umgebungsvariablen einführt, sollten Sie diese klar dokumentieren. Fügen Sie sie der Tabelle der Umgebungsvariablen in der README-Datei hinzu, mit einer kurzen Beschreibung, was jeder Schlüssel bewirkt und ob er erforderlich ist. Dieser kleine Akt der Dokumentation kann Ihnen (oder Ihren Mitstreitern) später eine Menge Kopfzerbrechen ersparen.

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

Bonus: Beide MCP-Server gemeinsam nutzen

Wenn Sie mit einem AI-Agenten arbeiten, können Sie den Beitragsprozess vereinfachen, indem Sie sowohl den Vonage MCP Tooling Server als auch den Vonage Dokumentation MCP Server gemeinsam ausführen. Durch diese Kombination hat Ihr Agent Zugriff auf die Tooldefinitionen des Projekts sowie auf die offizielle Vonage API-Dokumentation, was die Erstellung neuer Tools, die den etablierten Mustern folgen, erleichtert.

Wenn beide Server aktiv sind, können Sie oft mit einer Eingabeaufforderung wie dieser beginnen:

"Ich möchte dem Vonage MCP Tooling Server ein neues Tool hinzufügen, das die Verify API verwendet, um einen Telefonverifizierungsworkflow zu starten. Bitte folgen Sie der Struktur "Ein Tool pro Datei", verwenden Sie Zod für die Eingabevalidierung und fügen Sie ein Anwendungsbeispiel für die README bei. Die neuesten Parameter finden Sie in den Vonage-Dokumenten."

Dieser Ansatz ersetzt nicht das Testen oder Überprüfen, aber er kann Ihnen helfen, schnell voranzukommen und Ihre Änderungen mit den Konventionen des Projekts in Einklang zu bringen.

Einpacken

Open Source funktioniert am besten, wenn Menschen wie Sie sich beteiligen. Wenn Sie eine Idee für eine neue SDK-Funktion haben, z. B. MMS, Anrufabwicklung oder sogar Account-Verwaltung, entwickeln Sie sie! Und wenn Sie sich nicht sicher sind, wo Sie anfangen sollen, melden Sie sich, und wir können gemeinsam daran arbeiten. Wir lieben PRs!

Wir sind gespannt, was ihr euch einfallen lasst.