FastMCP - Framework de Servidor MCP en TypeScript

Resumen del Proyecto

FastMCP es un framework en TypeScript diseñado específicamente para construir servidores Model Context Protocol (MCP). Proporciona un conjunto completo de herramientas y funcionalidades, permitiendo a los desarrolladores crear rápidamente servidores MCP de alto rendimiento capaces de manejar sesiones de cliente.

Dirección del Proyecto: https://github.com/punkpeye/fastmcp

Características Principales

Funcionalidades Básicas

• Definición sencilla de herramientas, recursos y prompts: Proporciona una API intuitiva para definir las funcionalidades del servidor.
• Soporte de autenticación: Mecanismo de autenticación incorporado para asegurar el acceso.
• Gestión de sesiones: Soporte para el manejo de sesiones de cliente y gestión de estado.
• Soporte de contenido multimedia: Soporte para el retorno de contenido de imagen y audio.
• Registro de logs: Sistema de logs completo para depuración y monitorización.
• Manejo de errores: Mecanismo unificado de manejo de errores.
• Server-Sent Events (SSE): Soporte para el envío de datos en tiempo real.
• Soporte CORS: Habilitación por defecto del Intercambio de Recursos de Origen Cruzado.

Características Avanzadas

• Notificaciones de progreso: Retroalimentación en tiempo real del progreso de la ejecución de herramientas.
• Eventos de servidor tipados: Sistema de eventos con seguridad de tipos en TypeScript.
• Autocompletado de parámetros de prompts: Funcionalidad de autocompletado inteligente de parámetros.
• Solicitudes de muestreo: Soporte para solicitudes de muestreo de modelos de IA.
• Heartbeat SSE automatizado: Mantiene la estabilidad de la conexión.
• Gestión del directorio raíz: Configuración del directorio raíz del sistema de archivos.
• Herramientas CLI: Proporciona herramientas de línea de comandos para pruebas y depuración.

Instalación y Uso

Instalación

npm install fastmcp

Ejemplo Básico

import { FastMCP } from "fastmcp";
import { z } from "zod"; 

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
});

server.addTool({
  name: "add",
  description: "Add two numbers",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
});

server.start({
  transportType: "stdio",
});

Módulos Principales

1. Definición de Herramientas (Tools)

Las herramientas permiten al servidor exponer funciones ejecutables a los clientes, las cuales pueden ser invocadas por el cliente y utilizadas por LLM para ejecutar operaciones.

Librerías de Validación de Esquemas Soportadas

• Zod: La librería de validación de esquemas en TypeScript más popular.
• ArkType: Librería de validación de tipos moderna.
• Valibot: Librería de validación de esquemas ligera.

Ejemplo con Zod

import { z } from "zod";

server.addTool({
  name: "fetch-zod",
  description: "Fetch the content of a url (using Zod)",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Anotaciones de Herramientas

Las herramientas pueden incluir anotaciones, proporcionando un contexto más rico e información de control:

server.addTool({
  name: "fetch-content",
  description: "Fetch content from a URL",
  parameters: z.object({
    url: z.string(),
  }),
  annotations: {
    title: "Web Content Fetcher", 
    readOnlyHint: true, 
    openWorldHint: true,
  },
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

2. Gestión de Recursos (Resources)

Los recursos representan cualquier tipo de dato que el servidor MCP desea proporcionar al cliente, incluyendo:

• Contenido de archivos
• Capturas de pantalla e imágenes
• Archivos de logs
• Otros datos

server.addResource({
  uri: "file:///logs/app.log",
  name: "Application Logs",
  mimeType: "text/plain",
  async load() {
    return {
      text: await readLogFile(),
    };
  },
});

Plantillas de Recursos

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "Application Logs",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "Name of the log",
      required: true,
    },
  ],
  async load({ name }) {
    return {
      text: `Example log content for ${name}`,
    };
  },
});

3. Gestión de Prompts (Prompts)

Los prompts permiten al servidor definir plantillas de prompts y flujos de trabajo reutilizables:

server.addPrompt({
  name: "git-commit",
  description: "Generate a Git commit message",
  arguments: [
    {
      name: "changes",
      description: "Git diff or description of changes",
      required: true,
    },
  ],
  load: async (args) => {
    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
  },
});

4. Autenticación

FastMCP soporta funcionalidades de autenticación personalizadas:

import { AuthError } from "fastmcp";

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
  authenticate: ({ request }) => {
    const apiKey = request.headers["x-api-key"];
    if (apiKey !== "123") {
      throw new Response(null, {
        status: 401,
        statusText: "Unauthorized",
      });
    }
    return {
      id: 1,
    };
  },
});

5. Server-Sent Events (SSE)

Soporte para la funcionalidad SSE para comunicación en tiempo real:

server.start({
  transportType: "sse",
  sse: {
    endpoint: "/sse",
    port: 8080,
  },
});

6. Gestión de Sesiones

FastMCP asigna una nueva instancia de servidor a cada conexión de cliente, implementando comunicación 1:1:

server.on("connect", (event) => {
  console.log("Client connected:", event.session);
});

server.on("disconnect", (event) => {
  console.log("Client disconnected:", event.session);
});

Herramientas de Desarrollo

Pruebas y Depuración

npx fastmcp dev src/examples/addition.ts


npx fastmcp inspect src/examples/addition.ts

Integración con Claude Desktop

Añade la configuración en Claude Desktop:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/PATH/TO/YOUR_PROJECT/src/index.ts"],
      "env": {
        "YOUR_ENV_VAR": "value"
      }
    }
  }
}

Casos de Uso Reales

FastMCP ha sido adoptado por varios proyectos, incluyendo:

• apinetwork/piapi-mcp-server: Utiliza Midjourney/Flux/Kling para generar contenido multimedia.
• domdomegg/computer-use-mcp: Herramientas de control de computadora.
• Meeting-Baas/meeting-mcp: Robot de reuniones y gestión de transcripciones.
• drumnation/unsplash-smart-mcp-server: Integración de búsqueda de imágenes de Unsplash.
• aiamblichus/mcp-chat-adapter: Interfaz de finalización de chat LLM.

Ventajas Técnicas

1. Seguridad de tipos: Soporte completo de TypeScript que asegura la calidad del código.
2. Esquemas flexibles: Soporte para múltiples librerías de validación, satisfaciendo diferentes necesidades.
3. Arquitectura moderna: Basado en los últimos estándares web y mejores prácticas.
4. Funcionalidades ricas: Soporte completo desde funcionalidades básicas hasta características avanzadas.
5. Fácil de extender: Diseño modular que facilita la extensión de funcionalidades.
6. Amigable para el desarrollo: Herramientas CLI completas y soporte de depuración.

Resumen

FastMCP es un framework en TypeScript potente y fácil de usar, que proporciona una solución completa para construir servidores MCP. Ya sea para una simple integración de herramientas o la construcción de servicios de IA complejos, FastMCP puede proporcionar la funcionalidad y flexibilidad necesarias. Su rico conjunto de características y su buena experiencia de desarrollador lo convierten en una herramienta importante en el ecosistema MCP.