Genkit MCP

[!ADVERTENCIA]
Este complemento es experimental, lo que significa que es posible que no tenga soporte a largo plazo y que las API estén sujetas a cambios disruptivos con mayor frecuencia.

Este complemento proporciona integración entre Genkit y el Protocolo de Contexto de Modelo (MCP). MCP es un estándar abierto que permite a los desarrolladores crear servidores que proporcionan herramientas, recursos y avisos a los clientes. Genkit MCP permite a los desarrolladores consumir herramientas, avisos y recursos de MCP como cliente y proporcionar herramientas y avisos como servidor.

Instalación

Para comenzar, necesitará Genkit y el complemento MCP:

npm i genkit genkitx-mcp

Related MCP server: MCP Server

Cliente MCP

Para crear un cliente MCP, se llama a la función mcpClient para generar un complemento Genkit para un servidor MCP. Por ejemplo, para usar el servidor de sistema de archivos de ejemplo de MCP:

import { genkit } from 'genkit';
import { mcpClient } from 'genkitx-mcp';

// the filesystem server requires one or more allowed directories
const ALLOWED_DIRS = ['/Users/yourusername/Desktop'];

const filesystemClient = mcpClient({
  name: 'filesystem',
  serverProcess: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-everything', ...ALLOWED_DIRS],
  },
});

const ai = genkit({
  plugins: [
    filesystemClient /* ... other plugins such as model providers ...*/,
  ],
});

La mayoría de los servidores MCP están diseñados para ejecutarse como procesos generados en la misma máquina mediante el transporte stdio . Al proporcionar la opción serverProcess , se especifican el comando, los argumentos y las variables de entorno para generar el servidor como subproceso.

Opciones de mcpClient()

• name : (obligatorio) El nombre de este cliente, que asigna espacios de nombres a sus herramientas y avisos.

• version : (opcional) Número de versión del cliente. El valor predeterminado es "1.0.0".

• Debe proporcionar uno de los siguientes:

  • serverProcess : Parámetros para iniciar un proceso de servidor local utilizando el transporte MCP stdio.

    • command : Ruta de comandos del shell para iniciar el servidor MCP. Puede ser, por ejemplo, npx o uvx para descargar y ejecutar el servidor desde un gestor de paquetes.

    • args : (opcional) Matriz de argumentos de cadena para pasar al comando.

    • env : (opcional) Objeto de valor clave de las variables de entorno que se pasarán al comando.

  • serverUrl : la URL de un servidor remoto al que conectarse mediante el transporte SSE MCP.

  • ** serverWebsocketUrl : la URL de un servidor remoto al que conectarse mediante el transporte MCP de WebSocket.

  • transport : un objeto de transporte MCP existente para conectarse al servidor.

• rawToolResponses : (opcional) Indicador booleano. Si es true , las respuestas de la herramienta se devuelven en su formato MCP original; de lo contrario, se procesan para compatibilidad con Genkit.

Uso de acciones MCP

El cliente MCP de Genkit detecta automáticamente las herramientas y los avisos disponibles y los registra en Genkit, haciéndolos disponibles dondequiera que se puedan usar otras herramientas y avisos. Para acceder a los recursos, se registran las herramientas especiales list_resources y read_resource , que accederán a los recursos del servidor.

Todas las acciones de MCP tienen un espacio de nombres bajo el nombre que usted proporciona, por lo que un cliente llamado filesystem registrará herramientas como filesystem/read_file .

Respuestas de la herramienta

Las herramientas MCP devuelven una matriz content , a diferencia de una respuesta estructurada como la mayoría de las herramientas Genkit. El complemento MCP de Genkit intenta analizar y convertir el contenido devuelto:

1. Si el contenido es texto y JSON válido, se analiza y se devuelve el JSON.

2. Si el contenido es texto y no JSON válido, se devuelve el texto.

3. Si el contenido tiene una sola parte que no es texto, se devuelve.

4. Si el contenido tiene partes múltiples o mixtas, se devuelve la respuesta del contenido completo.

Servidor MCP

También puedes exponer todas las herramientas y avisos de una instancia de Genkit como un servidor MCP:

import { genkit, z } from 'genkit';
import { mcpServer } from 'genkitx-mcp';

const ai = genkit({});

ai.defineTool(
  {
    name: 'add',
    description: 'add two numbers together',
    inputSchema: z.object({ a: z.number(), b: z.number() }),
    outputSchema: z.number(),
  },
  async ({ a, b }) => {
    return a + b;
  }
);

ai.definePrompt(
  {
    name: "happy",
    description: "everybody together now",
    input: {
      schema: z.object({
        action: z.string().default("clap your hands").optional(),
      }),
    },
  },
  `If you're happy and you know it, {{action}}.`
);

mcpServer(ai, { name: 'example_server', version: '0.0.1' }).start();

Lo anterior iniciará un servidor MCP con el transporte stdio que expone una herramienta llamada add y un indicador llamado happy . Para iniciar el servidor con un transporte diferente, use mcpServer(...).start(otherTransport) .

Limitaciones conocidas

• Las solicitudes de MCP solo pueden tomar parámetros de cadena, por lo que las entradas a los esquemas deben ser objetos con solo valores de propiedad de cadena.

• Los mensajes de MCP solo admiten mensajes user y model . Los mensajes system no son compatibles.

• Los mensajes de MCP solo admiten un único "tipo" dentro de un mensaje, por lo que no es posible mezclar medios y texto en el mismo mensaje.

Probando su servidor MCP

Puedes probar tu servidor MCP con el inspector oficial. Por ejemplo, si el código de tu servidor se compila en dist/index.js , podrías ejecutar:

npx @modelcontextprotocol/inspector dist/index.js

Una vez que inicie el inspector, podrá enumerar indicaciones y acciones y probarlas manualmente.