mcp-agent-kit

un SDK completo e intuitivo para construir servidores MCP, agentes MCP e integraciones con LLM (OpenAI, Claude, Gemini) con el mínimo esfuerzo. Abstrae toda la complejidad del protocolo MCP, proporciona un agente inteligente con enrutamiento automático de modelos e incluye un cliente universal para APIs externas, todo a través de una única interfaz simple y potente. Perfecto para chatbots, automatización empresarial, integraciones de sistemas internos y desarrollo rápido de ecosistemas basados en MCP.

GitHub

Documentación

mcp-agent-kit

La forma más fácil de crear servidores MCP, agentes de IA y chatbots con cualquier LLM

mcp-agent-kit es un paquete de TypeScript que simplifica la creación de:

🔌 Servidores MCP (Protocolo de Contexto de Modelo)
🤖 Agentes de IA con múltiples proveedores de LLM
🧠 Enrutadores Inteligentes para orquestación multi-LLM
💬 Chatbots con memoria de conversación
🌐 Ayudantes de API con reintentos y tiempo de espera

Características

Configuración Cero: Funciona de inmediato con valores predeterminados inteligentes
Multi-Proveedor: Soporte para OpenAI, Anthropic, Gemini, Ollama
Seguro en Tipos: Soporte completo de TypeScript con autocompletado
Listo para Producción: Reintentos, tiempos de espera y manejo de errores integrados
Amigable para Desarrolladores: Configuración en una línea para funciones complejas
Extensible: Fácil de agregar proveedores personalizados y middleware

Instalación

npm install mcp-agent-kit

Inicio Rápido

Crear un Agente de IA (¡en 1 línea!)

import { createAgent } from "mcp-agent-kit";

const agent = createAgent({ provider: "openai" });
const response = await agent.chat("Hello!");
console.log(response.content);

Crear un Servidor MCP (¡en 1 función!)

import { createMCPServer } from "mcp-agent-kit";

const server = createMCPServer({
  name: "my-server",
  tools: [
    {
      name: "get_weather",
      description: "Get weather for a location",
      inputSchema: {
        type: "object",
        properties: {
          location: { type: "string" },
        },
      },
      handler: async ({ location }) => {
        return `Weather in ${location}: Sunny, 72°F`;
      },
    },
  ],
});

await server.start();

Crear un Chatbot con Memoria

import { createChatbot, createAgent } from "mcp-agent-kit";

const bot = createChatbot({
  agent: createAgent({ provider: "openai" }),
  system: "You are a helpful assistant",
  maxHistory: 10,
});

await bot.chat("Hi, my name is John");
await bot.chat("What is my name?"); // Remembers context!

Documentación

Agentes de IA

Crea agentes inteligentes que funcionan con múltiples proveedores de LLM.

Uso Básico

import { createAgent } from "mcp-agent-kit";

const agent = createAgent({
  provider: "openai",
  model: "gpt-4-turbo-preview",
  temperature: 0.7,
  maxTokens: 2000,
});

const response = await agent.chat("Explain TypeScript");
console.log(response.content);

Proveedores Soportados

Proveedor	Modelos	Clave de API Requerida
OpenAI	GPT-4, GPT-3.5	✅ Sí
Anthropic	Claude 3.5, Claude 3	✅ Sí
Gemini	Gemini 2.0+	✅ Sí
Ollama	Modelos locales	❌ No

Con Herramientas (Llamada de Funciones)

const agent = createAgent({
  provider: "openai",
  tools: [
    {
      name: "calculate",
      description: "Perform calculations",
      parameters: {
        type: "object",
        properties: {
          operation: { type: "string", enum: ["add", "subtract"] },
          a: { type: "number" },
          b: { type: "number" },
        },
        required: ["operation", "a", "b"],
      },
      handler: async ({ operation, a, b }) => {
        return operation === "add" ? a + b : a - b;
      },
    },
  ],
});

const response = await agent.chat("What is 15 + 27?");

Con Prompt de Sistema

const agent = createAgent({
  provider: "anthropic",
  system: "You are an expert Python developer. Always provide code examples.",
});

Llamada Inteligente de Herramientas

La Llamada Inteligente de Herramientas agrega confiabilidad y rendimiento a la ejecución de herramientas con reintentos automáticos, tiempo de espera y almacenamiento en caché.

Configuración Básica

const agent = createAgent({
  provider: "openai",
  toolConfig: {
    forceToolUse: true,      // Force model to use tools
    maxRetries: 3,           // Retry up to 3 times on failure
    toolTimeout: 30000,      // 30 second timeout
    onToolNotCalled: "retry", // Action when tool not called
  },
  tools: [...],
});

Con Almacenamiento en Caché

const agent = createAgent({
  provider: "openai",
  toolConfig: {
    cacheResults: {
      enabled: true,
      ttl: 300000,    // Cache for 5 minutes
      maxSize: 100,   // Store up to 100 results
    },
  },
  tools: [...],
});

Ejecución Directa de Herramientas

// Execute a tool directly with retry and caching
const result = await agent.executeTool("get_weather", {
  location: "San Francisco, CA",
});

Opciones de Configuración

Opción	Tipo	Predeterminado	Descripción
`forceToolUse`	boolean	false	Forzar al modelo a usar herramientas cuando estén disponibles
`maxRetries`	number	3	Intentos máximos de reintento en fallo de herramienta
`onToolNotCalled`	string	"retry"	Acción cuando la herramienta no se llama: "retry", "error", "warn", "allow"
`toolTimeout`	number	30000	Tiempo de espera para ejecución de herramientas (ms)
`cacheResults.enabled`	boolean	true	Habilitar almacenamiento en caché de resultados
`cacheResults.ttl`	number	300000	Tiempo de vida del caché (ms)
`cacheResults.maxSize`	number	100	Máximo de resultados almacenados en caché
`debug`	boolean	false	Habilitar registro de depuración

Ejemplo Completo

const agent = createAgent({
  provider: "openai",
  model: "gpt-4-turbo-preview",
  toolConfig: {
    forceToolUse: true,
    maxRetries: 3,
    onToolNotCalled: "retry",
    toolTimeout: 30000,
    cacheResults: {
      enabled: true,
      ttl: 300000,
      maxSize: 100,
    },
    debug: true,
  },
  tools: [
    {
      name: "get_weather",
      description: "Get current weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string" },
        },
        required: ["location"],
      },
      handler: async ({ location }) => {
        // Your weather API logic
        return { location, temp: 72, condition: "Sunny" };
      },
    },
  ],
});

// Use in chat - tools are automatically called
const response = await agent.chat("What's the weather in NYC?");

// Or execute directly with retry and caching
const result = await agent.executeTool("get_weather", {
  location: "New York, NY",
});

Servidores MCP

Crea servidores de Protocolo de Contexto de Modelo para exponer herramientas y recursos.

Servidor MCP Básico

import { createMCPServer } from "mcp-agent-kit";

const server = createMCPServer({
  name: "my-mcp-server",
  port: 7777,
  logLevel: "info",
});

await server.start(); // Starts on stdio by default

Con Herramientas

const server = createMCPServer({
  name: "weather-server",
  tools: [
    {
      name: "get_weather",
      description: "Get current weather",
      inputSchema: {
        type: "object",
        properties: {
          location: { type: "string" },
          units: { type: "string", enum: ["celsius", "fahrenheit"] },
        },
        required: ["location"],
      },
      handler: async ({ location, units = "celsius" }) => {
        // Your weather API logic here
        return { location, temp: 22, units, condition: "Sunny" };
      },
    },
  ],
});

Con Recursos

const server = createMCPServer({
  name: "data-server",
  resources: [
    {
      uri: "config://app-settings",
      name: "Application Settings",
      description: "Current app configuration",
      mimeType: "application/json",
      handler: async () => {
        return JSON.stringify({ version: "1.0.0", env: "production" });
      },
    },
  ],
});

Transporte WebSocket

const server = createMCPServer({
  name: "ws-server",
  port: 8080,
});

await server.start("websocket"); // Use WebSocket instead of stdio

Enrutador LLM

Enruta solicitudes a diferentes LLM según reglas inteligentes.

Enrutador Básico

import { createLLMRouter } from "mcp-agent-kit";

const router = createLLMRouter({
  rules: [
    {
      when: (input) => input.length < 200,
      use: { provider: "openai", model: "gpt-4-turbo-preview" },
    },
    {
      when: (input) => input.includes("code"),
      use: { provider: "anthropic", model: "claude-3-5-sonnet-20241022" },
    },
    {
      default: true,
      use: { provider: "openai", model: "gpt-4-turbo-preview" },
    },
  ],
});

const response = await router.route("Write a function to sort an array");

Con Respaldo y Reintento

const router = createLLMRouter({
  rules: [...],
  fallback: {
    provider: 'openai',
    model: 'gpt-4-turbo-preview'
  },
  retryAttempts: 3,
  logLevel: 'debug'
});

Estadísticas del Enrutador

const stats = router.getStats();
console.log(stats);
// { totalRules: 3, totalAgents: 2, hasFallback: true }

const agents = router.listAgents();
console.log(agents);
// ['openai:gpt-4-turbo-preview', 'anthropic:claude-3-5-sonnet-20241022']

Chatbots

Crea IA conversacional con gestión automática de memoria.

Chatbot Básico

import { createChatbot, createAgent } from "mcp-agent-kit";

const bot = createChatbot({
  agent: createAgent({ provider: "openai" }),
  system: "You are a helpful assistant",
  maxHistory: 10,
});

await bot.chat("Hi, I am learning TypeScript");
await bot.chat("Can you help me with interfaces?");
await bot.chat("Thanks!");

Con Enrutador

const bot = createChatbot({
  router: createLLMRouter({ rules: [...] }),
  maxHistory: 20
});

Gestión de Memoria

// Get conversation history
const history = bot.getHistory();

// Get statistics
const stats = bot.getStats();
console.log(stats);
// {
//   messageCount: 6,
//   userMessages: 3,
//   assistantMessages: 3,
//   oldestMessage: Date,
//   newestMessage: Date
// }

// Reset conversation
bot.reset();

// Update system prompt
bot.setSystemPrompt("You are now a Python expert");

Solicitudes de API

Solicitudes HTTP simplificadas con reintento automático y tiempo de espera.

Solicitud Básica

import { api } from "mcp-agent-kit";

const response = await api.get("https://api.example.com/data");
console.log(response.data);

Solicitud POST

const response = await api.post(
  "https://api.example.com/users",
  { name: "John", email: "john@example.com" },
  {
    name: "create-user",
    headers: { "Content-Type": "application/json" },
  }
);

Con Reintento y Tiempo de Espera

const response = await api.request({
  name: "important-request",
  url: "https://api.example.com/data",
  method: "GET",
  timeout: 10000, // 10 seconds
  retries: 5, // 5 attempts
  query: { page: 1, limit: 10 },
});

Todos los Métodos HTTP

await api.get(url, config);
await api.post(url, body, config);
await api.put(url, body, config);
await api.patch(url, body, config);
await api.delete(url, config);

Configuración

Variables de Entorno

Toda la configuración es opcional. Establece estas variables de entorno o pásalas en el código:

# MCP Server
MCP_SERVER_NAME=my-server
MCP_PORT=7777

# Logging
LOG_LEVEL=info  # debug | info | warn | error

# LLM API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
OLLAMA_HOST=http://localhost:11434

Usando Archivo .env

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LOG_LEVEL=debug

El paquete carga automáticamente archivos .env usando dotenv.

Ejemplos

Consulta el directorio /examples para ver ejemplos completos y funcionales:

basic-agent.ts - Uso simple de agente
smart-tool-calling.ts - Llamada inteligente de herramientas con reintento y caché
mcp-server.ts - Servidor MCP con herramientas y recursos
mcp-server-websocket.ts - Servidor MCP con WebSocket
llm-router.ts - Enrutamiento inteligente entre LLM
chatbot-basic.ts - Chatbot con memoria de conversación
chatbot-with-router.ts - Chatbot usando enrutador
api-requests.ts - Solicitudes HTTP con reintento

Ejecutando Ejemplos

# Install dependencies
npm install

# Run an example
npx ts-node examples/basic-agent.ts

Referencia de API

API de Agente

`createAgent(config: AgentConfig)`

Crea una nueva instancia de agente de IA.

Parámetros:

provider (requerido): Proveedor de LLM - "openai", "anthropic", "gemini" u "ollama"
model (opcional): Nombre del modelo (usa el predeterminado del proveedor)
temperature (opcional): Temperatura de muestreo 0-2 (predeterminado: 0.7)
maxTokens (opcional): Máximo de tokens en la respuesta (predeterminado: 2000)
apiKey (opcional): Clave de API (se lee del entorno si no se proporciona)
tools (opcional): Matriz de definiciones de herramientas
system (opcional): Prompt de sistema
toolConfig (opcional): Configuración de llamada inteligente de herramientas

Devuelve: Instancia de agente

Métodos:

chat(message: string): Promise<AgentResponse> - Enviar un mensaje y obtener respuesta
executeTool(name: string, params: any): Promise<any> - Ejecutar una herramienta directamente

`AgentResponse`

Objeto de respuesta de agent.chat():

{
  content: string;           // Response text
  toolCalls?: Array<{        // Tools that were called
    name: string;
    arguments: any;
  }>;
  usage?: {                  // Token usage
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
}

API de Servidor MCP

`createMCPServer(config: MCPServerConfig)`

Crea una nueva instancia de servidor MCP.

Parámetros:

name (opcional): Nombre del servidor (predeterminado: del entorno o "mcp-server")
port (opcional): Número de puerto (predeterminado: 7777)
logLevel (opcional): Nivel de registro - "debug", "info", "warn", "error"
tools (opcional): Matriz de definiciones de herramientas
resources (opcional): Matriz de definiciones de recursos

Devuelve: Instancia de servidor MCP

Métodos:

start(transport?: "stdio" | "websocket"): Promise<void> - Iniciar el servidor

API de Enrutador

`createLLMRouter(config: LLMRouterConfig)`

Crea una nueva instancia de enrutador LLM.

Parámetros:

rules (requerido): Matriz de reglas de enrutamiento
fallback (opcional): Configuración del proveedor de respaldo
retryAttempts (opcional): Número de intentos de reintento (predeterminado: 3)
logLevel (opcional): Nivel de registro

Devuelve: Instancia de enrutador

Métodos:

route(input: string): Promise<AgentResponse> - Enrutar entrada al LLM apropiado
getStats(): object - Obtener estadísticas del enrutador
listAgents(): string[] - Listar todos los agentes configurados

API de Chatbot

`createChatbot(config: ChatbotConfig)`

Crea una nueva instancia de chatbot con memoria de conversación.

Parámetros:

agent o router (requerido): Instancia de agente o enrutador
system (opcional): Prompt de sistema
maxHistory (opcional): Máximo de mensajes a conservar (predeterminado: 10)

Devuelve: Instancia de chatbot

Métodos:

chat(message: string): Promise<AgentResponse> - Enviar mensaje con contexto
getHistory(): ChatMessage[] - Obtener historial de conversación
getStats(): object - Obtener estadísticas de conversación
reset(): void - Borrar historial de conversación
setSystemPrompt(prompt: string): void - Actualizar prompt de sistema

Ayudantes de Solicitudes de API

`api.request(config: APIRequestConfig)`

Realiza solicitudes HTTP con reintento y tiempo de espera.

Parámetros:

name (opcional): Nombre de la solicitud para registro
url (requerido): URL de la solicitud
method (opcional): Método HTTP (predeterminado: "GET")
headers (opcional): Encabezados de la solicitud
query (opcional): Parámetros de consulta
body (opcional): Cuerpo de la solicitud
timeout (opcional): Tiempo de espera en ms (predeterminado: 30000)
retries (opcional): Intentos de reintento (predeterminado: 3)

Devuelve: Promise<APIResponse>

Métodos de Conveniencia:

api.get(url, config?) - Solicitud GET
api.post(url, body, config?) - Solicitud POST
api.put(url, body, config?) - Solicitud PUT
api.patch(url, body, config?) - Solicitud PATCH
api.delete(url, config?) - Solicitud DELETE

Uso Avanzado

Proveedor Personalizado

// Coming soon: Plugin system for custom providers

Middleware

// Coming soon: Middleware support for request/response processing

Respuestas en Streaming

// Coming soon: Streaming support for real-time responses

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción.

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Haz commit de tus cambios (git commit -m 'Add amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción

Licencia

Agradecimientos

Construido con TypeScript
Usa MCP SDK
Impulsado por OpenAI, Anthropic, Google y Ollama

Soporte

Correo electrónico: houessoudominique@gmail.com
Problemas: Problemas de GitHub
Discusiones: Discusiones de GitHub

Hecho por desarrolladores, para desarrolladores