FastMCP

FastMCP es un marco de TypeScript para crear servidores MCP con gestión de sesiones de cliente.

[!NOTA]
Para una implementación de Python, consulte FastMCP Python .

Características principales

FastMCP ofrece las siguientes características:

Herramientas sencillas, recursos y definiciones rápidas
Función de autenticación
Gestión de sesiones
Compatibilidad con contenido de imágenes
Explotación florestal
Manejo de errores
SSE (Eventos enviados por el servidor)
CORS (habilitado por defecto)
Notificaciones de progreso
Eventos de servidor tipificados
Completado automático de argumentos de solicitud
Solicitud de muestreo
Ping SSE automático
Gestión de rutas
CLI para pruebas y depuración

Cómo instalar

npm install fastmcp

Inicio rápido

[!NOTA]
Hay muchos casos de uso reales para FastMCP. Por favor vea el estudio de caso .

import { FastMCP } from "fastmcp";
import { z } from "zod"; // または他の検証ライブラリ（Standard Schemaをサポートしているもの）

const server = new FastMCP({
  name: "マイサーバー",
  version: "1.0.0",
});

server.addTool({
  name: "add",
  description: "2つの数値を足し算します",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
});

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

¡Ahora tienes un servidor MCP en funcionamiento!

Puedes probarlo en la terminal con:

git clone https://github.com/punkpeye/fastmcp.git
cd fastmcp

pnpm install
pnpm build

# CLIを使った足し算サーバーの例をテスト：
npx fastmcp dev src/examples/addition.ts
# MCP Inspectorを使った足し算サーバーの例を検査：
npx fastmcp inspect src/examples/addition.ts

SSE

Los eventos enviados por el servidor (SSE) son un mecanismo mediante el cual un servidor envía actualizaciones en tiempo real a un cliente a través de una conexión HTTPS. En MCP, SSE se utiliza principalmente para habilitar la comunicación remota de MCP, lo que permite acceder a un MCP alojado en una máquina remota y transmitir actualizaciones a través de la red.

También puedes ejecutar el servidor con soporte SSE:

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

Esto iniciará un servidor que escuchará conexiones SSE en http://localhost:8080/sse .

Luego puedes conectarte al servidor usando SSEClientTransport :

import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));

await client.connect(transport);

Conceptos básicos

herramienta

En las herramientas MCP, los servidores exponen funciones ejecutables que los clientes y LLM pueden llamar para realizar acciones.

FastMCP utiliza la especificación del esquema estándar para definir los parámetros de la herramienta. Esto le permite utilizar su biblioteca de validación de esquema favorita que implementa la especificación, como Zod, ArkType o Valibot.

Ejemplo de Zod:

import { z } from "zod";

server.addTool({
  name: "fetch-zod",
  description: "URLのコンテンツを取得します（Zodを使用）",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Ejemplo de ArkType:

import { type } from "arktype";

server.addTool({
  name: "fetch-arktype",
  description: "URLのコンテンツを取得します（ArkTypeを使用）",
  parameters: type({
    url: "string",
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Ejemplo de Valibot:

Valibot requiere una dependencia de pares: @valibot/to-json-schema.

import * as v from "valibot";

server.addTool({
  name: "fetch-valibot",
  description: "URLのコンテンツを取得します（Valibotを使用）",
  parameters: v.object({
    url: v.string(),
  }),
  execute: async (args) => {
    return await fetchWebpageContent(args.url);
  },
});

Devolviendo una cadena

execute puede devolver una cadena:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return "こんにちは、世界！";
  },
});

Esto es equivalente a:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "text",
          text: "こんにちは、世界！",
        },
      ],
    };
  },
});

Devolver una lista

Si desea devolver una lista de mensajes, puede devolver un objeto con content :

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        { type: "text", text: "1つ目のメッセージ" },
        { type: "text", text: "2つ目のメッセージ" },
      ],
    };
  },
});

Devolviendo las imágenes

Para crear un objeto de contenido de imagen, utilice imageContent :

import { imageContent } from "fastmcp";

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return imageContent({
      url: "https://example.com/image.png",
    });

    // または...
    // return imageContent({
    //   path: "/path/to/image.png",
    // });

    // または...
    // return imageContent({
    //   buffer: Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64"),
    // });

    // または...
    // return {
    //   content: [
    //     await imageContent(...)
    //   ],
    // };
  },
});

La función imageContent acepta las siguientes opciones:

url : URL de la imagen
path : Ruta al archivo de imagen
buffer : Datos de imagen como buffer

Se debe especificar exactamente uno de los siguientes: url , path o buffer .

El ejemplo anterior es equivalente a:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    return {
      content: [
        {
          type: "image",
          data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
          mimeType: "image/png",
        },
      ],
    };
  },
});

Explotación florestal

Las herramientas pueden registrar mensajes al cliente utilizando el log del objeto de contexto:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { log }) => {
    log.info("ファイルをダウンロード中...", {
      url: args.url,
    });

    // ...

    log.info("ファイルをダウンロードしました");

    return "完了";
  },
});

log tiene los siguientes métodos:

debug(message: string, data?: SerializableValue)
error(message: string, data?: SerializableValue)
info(message: string, data?: SerializableValue)
warn(message: string, data?: SerializableValue)

error

Los errores que deben mostrarse al usuario deben generarse como instancias UserError :

import { UserError } from "fastmcp";

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args) => {
    if (args.url.startsWith("https://example.com")) {
      throw new UserError("このURLは許可されていません");
    }

    return "完了";
  },
});

Notificaciones de progreso

Una herramienta puede informar su progreso llamando reportProgress en el objeto de contexto:

server.addTool({
  name: "download",
  description: "ファイルをダウンロードします",
  parameters: z.object({
    url: z.string(),
  }),
  execute: async (args, { reportProgress }) => {
    reportProgress({
      progress: 0,
      total: 100,
    });

    // ...

    reportProgress({
      progress: 100,
      total: 100,
    });

    return "完了";
  },
});

recurso

Un recurso representa cualquier tipo de datos que un servidor MCP desea poner a disposición de sus clientes. Esto incluye:

Contenido del archivo
Capturas de pantalla e imágenes
Archivos de registro
Y muchos más

Cada recurso se identifica mediante un URI único y puede contener texto o datos binarios.

server.addResource({
  uri: "file:///logs/app.log",
  name: "アプリケーションログ",
  mimeType: "text/plain",
  async load() {
    return {
      text: await readLogFile(),
    };
  },
});

[!NOTA]
load puede devolver múltiples recursos. Esto se puede utilizar, por ejemplo, para devolver una lista de los archivos de un directorio cuando se lee dicho directorio.
async load() { return [ { text: "1つ目のファイルの内容", }, { text: "2つ目のファイルの内容", }, ]; }

También puedes devolver contenido binario con load :

async load() {
  return {
    blob: 'base64でエンコードされたデータ'
  };
}

Plantillas de recursos

También puedes definir plantillas de recursos:

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "アプリケーションログ",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "ログの名前",
      required: true,
    },
  ],
  async load({ name }) {
    return {
      text: `${name}のサンプルログ内容`,
    };
  },
});

Completado automático de argumentos de plantillas de recursos

Para habilitar el autocompletado de los argumentos de la plantilla de recursos, proporcionamos una función complete :

server.addResourceTemplate({
  uriTemplate: "file:///logs/{name}.log",
  name: "アプリケーションログ",
  mimeType: "text/plain",
  arguments: [
    {
      name: "name",
      description: "ログの名前",
      required: true,
      complete: async (value) => {
        if (value === "サンプル") {
          return {
            values: ["サンプルログ"],
          };
        }

        return {
          values: [],
        };
      },
    },
  ],
  async load({ name }) {
    return {
      text: `${name}のサンプルログ内容`,
    };
  },
});

inmediato

Prompts permite que el servidor defina plantillas de prompts y flujos de trabajo reutilizables que los clientes pueden presentar fácilmente a sus usuarios y LLM. Esto proporciona una forma poderosa de estandarizar y compartir interacciones LLM comunes.

server.addPrompt({
  name: "git-commit",
  description: "Gitコミットメッセージを生成します",
  arguments: [
    {
      name: "changes",
      description: "Gitの差分または変更の説明",
      required: true,
    },
  ],
  load: async (args) => {
    return `これらの変更に対する簡潔かつ説明的なコミットメッセージを生成してください：\n\n${args.changes}`;
  },
});

Completado automático de argumentos de solicitud

El mensaje puede proporcionar autocompletado de argumentos:

server.addPrompt({
  name: "countryPoem",
  description: "国についての詩を書きます",
  load: async ({ name }) => {
    return `こんにちは、${name}さん！`;
  },
  arguments: [
    {
      name: "name",
      description: "国の名前",
      required: true,
      complete: async (value) => {
        if (value === "日") {
          return {
            values: ["日本"],
          };
        }

        return {
          values: [],
        };
      },
    },
  ],
});

Completado automático de argumentos de solicitud mediante `enum`

Si proporciona una matriz enum para los argumentos, el servidor completará automáticamente los argumentos.

server.addPrompt({
  name: "countryPoem",
  description: "国についての詩を書きます",
  load: async ({ name }) => {
    return `こんにちは、${name}さん！`;
  },
  arguments: [
    {
      name: "name",
      description: "国の名前",
      required: true,
      enum: ["日本", "フランス", "イタリア"],
    },
  ],
});

proceso de dar un título

FastMCP le permite authenticate clientes mediante una función personalizada:

import { AuthError } from "fastmcp";

const server = new FastMCP({
  name: "マイサーバー",
  version: "1.0.0",
  authenticate: ({request}) => {
    const apiKey = request.headers["x-api-key"];

    if (apiKey !== '123') {
      throw new Response(null, {
        status: 401,
        statusText: "Unauthorized",
      });
    }

    // ここで返すものは`context.session`オブジェクトでアクセスできます
    return {
      id: 1,
    }
  },
});

Ahora puedes acceder a los datos de la sesión autenticada en tus herramientas:

server.addTool({
  name: "sayHello",
  execute: async (args, { session }) => {
    return `こんにちは、${session.id}さん！`;
  },
});

sesión

session es una instancia de FastMCPSession y describe una sesión de cliente activa.

server.sessions;

Para permitir la comunicación uno a uno entre el cliente y el servidor, se asigna una nueva instancia de servidor para cada conexión de cliente.

Eventos de servidor tipificados

Puedes escuchar los eventos emitidos por el servidor utilizando el método on :

server.on("connect", (event) => {
  console.log("クライアント接続:", event.session);
});

server.on("disconnect", (event) => {
  console.log("クライアント切断:", event.session);
});

`FastMCPSession`

FastMCPSession representa una sesión de cliente y proporciona métodos para interactuar con el cliente.

Consulte el ejemplo de sesión para saber cómo obtener FastMCPSession .

`requestSampling`

requestSampling realiza una solicitud de muestreo y devuelve la respuesta.

await session.requestSampling({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: "現在のディレクトリにはどのファイルがありますか？",
      },
    },
  ],
  systemPrompt: "あなたは役立つファイルシステムアシスタントです。",
  includeContext: "thisServer",
  maxTokens: 100,
});

`clientCapabilities`

clientCapabilities contiene las capacidades del cliente.

session.clientCapabilities;

`loggingLevel`

loggingLevel describe el nivel de registro establecido por el cliente.

session.loggingLevel;

`roots`

roots contiene las rutas establecidas por el cliente.

session.roots;

`server`

server contiene la instancia del servidor MCP asociado con la sesión.

session.server;

Eventos de sesión tipificados

Puedes escuchar los eventos emitidos por la sesión utilizando on :

session.on("rootsChanged", (event) => {
  console.log("ルート変更:", event.roots);
});

session.on("error", (event) => {
  console.error("エラー:", event.error);
});

Ejecución del servidor

Prueba con MCP-CLI

La forma más rápida de probar y depurar su servidor es usar fastmcp dev :

npx fastmcp dev server.js
npx fastmcp dev server.ts

Esto ejecutará un servidor para probar y depurar su servidor MCP en la terminal usando mcp-cli .

Inspeccionar con MCP Inspector

Otra opción es inspeccionar su servidor en la interfaz web utilizando el MCP Inspector :

npx fastmcp inspect server.ts

Preguntas frecuentes

¿Cómo utilizar con Claude Desktop?

Siga la guía https://modelcontextprotocol.io/quickstart/user y agregue la siguiente configuración:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "tsx",
        "/プロジェクトへのパス/src/index.ts"
      ],
      "env": {
        "環境変数名": "値"
      }
    }
  }
}

Estudio de caso

[!NOTA]
Si ha desarrollado un servidor utilizando FastMCP, envíe una solicitud de colaboración y preséntela como caso de estudio.

apinetwork/piapi-mcp-server - Genera medios usando Midjourney/Flux/Kling/LumaLabs/Udio/Chrip/Trellis
domdomegg/computer-use-mcp - Controlar una computadora
LiterallyBlah/Dradis-MCP - Gestión de proyectos y vulnerabilidades con Dradis
Meeting-Baas/meeting-mcp : crea bots de reuniones, busca actas de reuniones y administra datos de grabación.
drumnation/unsplash-smart-mcp-server : permite que un agente de IA busque, recomiende y distribuya sin problemas fotos profesionales desde Unsplash.
ssmanji89/halopsa-workflows-mcp - Integración de flujos de trabajo de HaloPSA con asistentes de IA
aiamblichus/mcp-chat-adapter : proporciona una interfaz limpia para que LLM utilice la finalización del chat.

Expresiones de gratitud

FastMCP está inspirado en una implementación de Python de Jonathan Lowin .
Partes del código base fueron adoptadas de LiteMCP .
Parte del código base se adoptó de nuestro experimento con SSE sobre el protocolo Model Context .

Integrations