Contribuir al servidor de herramientas MCP de código abierto de Vonage

El servidor de herramientas MCP de Vonage es de código abierto y fácil de usar para principiantes. Añade funciones SDK reales a través de PR sencillas y directrices MCP claras.

Introducción

Digamos que estás jugando con el Servidor de herramientas MCP de Vonage. Has visto cómo los agentes de IA pueden enviar mensajes alegres para las fiestas a través de WhatsApp, RCS, o has creado un chatbot de Claude para interactuar con el servidor MCP. Bastante genial, ¿verdad?

Pero entonces tu cerebro lanza una chispa: "Espera un segundo. ¿Y si quiero añadir MMS? ¿O comprobar si un número ha cambiado recientemente de SIM antes de enviarle información confidencial? ¿Podría añadir también más funciones desde la Voice API?".

Spoiler: Sí que puedes. Y mejor aún, ¡estás invitado!

El servidor de herramientas MCP de Vonage es completamente de código abierto y está listo para tus contribuciones. Esta guía te muestra cómo agregar una nueva herramienta (como verify-number) y enviar una solicitud de extracción (PR), manteniendo todo alineado con la estructura de las herramientas existentes.

Profundicemos.

Lee hasta el final para descubrir un atajo de AI que puede ayudarte a añadir herramientas aún más rápido.

Primero, entender la estructura

Antes de sumergirte en el código, dedica algo de tiempo a explorar la arquitectura. No tienes que memorizar cada línea, pero entender cómo encajan las piezas ayudará a que tu herramienta encaje sin problemas.

Componentes básicos

Configuración de entorno y autenticación

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

Configuración modular de canales

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

Función de mensajería unificada

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

Sencilla, limpia y diseñada para ser reutilizada.

Nuestros patrones MCP

Hemos aprendido mucho construyendo nuestras primeras herramientas y hemos establecido algunas reglas generales que hacen que las integraciones IA-agente sean más fluidas y predecibles. Si vas a contribuir, por favor, cíñete a ellas:

1. Una herramienta = Un trabajo

A los agentes de IA les resulta más fácil razonar sobre herramientas claras y con un único propósito. Cuando cada herramienta hace exactamente una cosa, es más fácil de descubrir, documentar y confundir la lógica de planificación del agente.

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

Nota: El servidor se importa del paquete paquete MCP server bindings

Evita las herramientas multiusos:

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

2. Validar como si fuera en serio

¿Malas entradas? ¿Faltan variables de entorno? Detéctelos pronto y con claridad.

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

Y responda siempre de una forma estructurada que el agente pueda analizar:

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

3. Zod para esquemas de entrada

Mantenga las cosas seguras y bien documentadas:

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

Si no has utilizado Zod es una forma de definir y validar entradas en un solo lugar, como los tipos de TypeScript, pero con comprobaciones en tiempo de ejecución. Asegura que tu herramienta solo se ejecuta cuando las entradas son válidas, y ofrece a los agentes descripciones claras de lo que significa cada campo.

Incluirá este inputSchema como parte del comando servidor.registerTool() para que cuando se registre la herramienta, sepa exactamente qué forma de entrada debe esperar y cómo validarla.

4. Docs First, Always

Añada su herramienta a la tabla README e incluye un ejemplo de uso. Tu futuro yo, y todos los desarrolladores posteriores, te lo agradecerán.

Añadamos juntos una herramienta

Digamos que quieres ayudar a mejorar el Servidor de Herramientas MCP añadiendo una nueva herramienta enfocada. En este caso, veremos cómo crear una que compruebe si un número de teléfono ha sufrido recientemente un SIM, un indicador común de fraude. La llamaremos check-sim-swap.

Esta herramienta utiliza la API de Identity Insightsque proporciona información en tiempo real sobre un número de teléfono, incluidos los eventos de intercambio de SIM. Mantendremos el alcance: una herramienta, un trabajo.

Paso 1: Configure su entorno de desarrollo local

Primero, bifurca el repositorio del servidor MCP y clona tu bifurcación:

# 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 no ha utilizado make es esencialmente un ejecutor de tareas que ayuda a agrupar múltiples comandos. Echa un vistazo al Makefile para ver qué comandos específicos se están ejecutando.

Aunque se originó en los ecosistemas C y C++, también funciona bien para flujos de trabajo de propósito general, incluyendo proyectos JavaScript y TypeScript. En este repositorio, lo utilizamos para agilizar comandos rutinarios como la instalación de dependencias o la preparación del entorno de desarrollo.

Aquí, make setup instalará las dependencias y preparará tu entorno para trabajar con el proyecto.

Paso 2: Escribir la herramienta

Ahora abra src/index.ts y registra tu nueva herramienta con el servidor.

Pega el siguiente código:

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

Esta herramienta hace una cosa: dado un número de teléfono, comprueba si la tarjeta SIM ha sido intercambiada en los últimos 10 días (240 horas). En caso afirmativo, devuelve la marca de tiempo. Si no, confirma que no se ha producido ningún intercambio reciente.

Paso 3: Actualizar los documentos

Abra el archivo README.md y añada su nueva herramienta a la tabla de herramientas:

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

Añade un ejemplo 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?

Paso 4: Pruebas locales

Asegúrese de que su herramienta se construye y pasa las comprobaciones:

make check
make build
npm run start

Paso 5: Cree su Pull Request

Cuando todo esté en orden, confirma los cambios y envíalos:

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

Dirígete a GitHub y abre tu pull request. Puntos extra por incluir una captura de pantalla de tu herramienta trabajando con tu agente de IA.

Patrones avanzados para funciones complejas

Probablemente no lo necesite para herramientas sencillas, pero para procesos de larga duración o masivos, considere esta estructura.

Manejo de operaciones asíncronas con seguimiento de estado

Para operaciones que requieren tiempo (como los flujos de trabajo de verificación):

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

Operaciones por lotes

Para operaciones a granel:

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

Algunas cosas que hay que tener en cuenta

Antes de enviar su pull request, asegúrese de que todo sigue funcionando como se esperaba. Ejecutando make check debería detectar la mayoría de los errores de tipado. Pero no se detenga ahí. Prueba manualmente que todas las herramientas existentes se comportan correctamente, y comprueba que tus adiciones no han roto accidentalmente ninguna funcionalidad existente. TypeScript debería compilar limpiamente antes de empujar.

Los nombres importan más de lo que crees. Utilice mayúsculas y minúsculas para los nombres de las herramientas (por ejemplo, utilice check-sim-swap, y no checkSimSwap). Las variables de entorno deben seguir MAYÚSCULAS_SNAKE_CASE y siempre con el prefijo VONAGE_. Y cuando escriba funciones, utilice la vieja y fiable camelCase.

La gestión de errores es otro aspecto crítico: no des por sentado que las cosas siempre van a ir bien. Gestione casos extremos como fallos de red, credenciales no válidas, límites de velocidad de la API y entradas de usuario malformadas. Si su herramienta no falla con elegancia, causará dolores de cabeza tanto a los usuarios posteriores como a los agentes.

Por último, si tu herramienta introduce nuevas variables de entorno, documéntalas claramente. Añádelas a la tabla de variables de entorno del README con una breve descripción de lo que hace cada clave y si es necesaria. Ese pequeño acto de documentación puede ahorrarte a ti mismo (o a tus compañeros colaboradores) muchos quebraderos de cabeza más adelante.

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

Bonificación: Uso conjunto de ambos servidores MCP

Si trabajas con un agente de AI, puedes simplificar el proceso de contribución ejecutando tanto el servidor de herramientas MCP de Vonage como el Servidor MCP de documentación de Vonage en tándem. La combinación le da a tu agente acceso a las definiciones de herramientas del proyecto, así como a la documentación oficial de la API de Vonage, lo que facilita la redacción de nuevas herramientas que sigan los patrones establecidos.

Con ambos servidores activos, a menudo se puede iniciar desde un prompt como:

"Quiero agregar una nueva herramienta al servidor de herramientas MCP de Vonage que utilice Verify API para iniciar un flujo de trabajo de verificación telefónica. Por favor, sigue la estructura de una herramienta por archivo, usa Zod para la validación de entrada e incluye un ejemplo de uso para el README. Consulta la documentación de Vonage para conocer los últimos parámetros".

Este enfoque no sustituirá a las pruebas o revisiones, pero puede ayudarle a avanzar con rapidez y a mantener los cambios alineados con las convenciones del proyecto.

Conclusión

El código abierto funciona mejor cuando participan personas como tú. Si tienes una idea para una nueva función del SDK, tal vez sea MMS, o la gestión de llamadas, o incluso la gestión de Account, ¡constrúyela! Y si no estás seguro de por dónde empezar, ponte en contacto con nosotros y podremos trabajar juntos. Nos encantan las relaciones públicas.

Estamos impacientes por ver qué se te ocurre.