🔌用 FastMCP 在 TypeScript 里构建你自己的 MCP 服务器

# En una carpeta nueva para tu servidor
mkdir mi-mcp && cd mi-mcp
npm init -y

# FastMCP + Zod (para los esquemas de entrada) + tsx (para correr TS sin compilar)
npm install fastmcp zod
npm install -D tsx typescript

// server.ts
import { FastMCP } from "fastmcp";
import { z } from "zod";

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

server.addTool({
  name: "add",
  description: "Suma dos números",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async (args) => {
    return String(args.a + args.b);
  },
});

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

# Arranca tu servidor en modo desarrollo (interactúas con los tools)
npx fastmcp dev server.ts

# Ábrelo en el MCP Inspector (interfaz visual para inspeccionar tools/resources/prompts)
npx fastmcp inspect server.ts

{
  "mcpServers": {
    "mi-servidor": {
      "command": "npx",
      "args": ["tsx", "/ruta/absoluta/a/mi-mcp/server.ts"]
    }
  }
}

server.addTool({
  name: "crear_usuario",
  description: "Crea un usuario en el sistema con validación completa",
  parameters: z.object({
    nombre: z.string().min(2),
    email: z.string().email(),
    edad: z.number().int().positive().optional(),
    rol: z.enum(["admin", "editor", "lector"]),
  }),
  execute: async (args) => {
    // Si llegaste aquí, args YA está validado: email es email, rol es válido.
    const usuario = await miBaseDeDatos.insertar(args);
    return `Usuario ${usuario.id} creado con rol ${args.rol}`;
  },
});

server.addResource({
  uri: "file:///logs/app.log",
  name: "Logs de la Aplicación",
  mimeType: "text/plain",
  async load() {
    const contenido = await fs.readFile("/var/log/app.log", "utf-8");
    return { text: contenido };
  },
});

server.addPrompt({
  name: "git-commit",
  description: "Genera un mensaje de commit a partir de un diff",
  arguments: [
    {
      name: "changes",
      description: "El diff de git o una descripción de los cambios",
      required: true,
    },
  ],
  load: async (args) => {
    return `Genera un mensaje de commit conciso para estos cambios:\n${args.changes}`;
  },
});

server.start({
  transportType: "httpStream",
  httpStream: {
    port: 8080,
    endpoint: "/mcp", // opcional, por defecto es /mcp
  },
});

const server = new FastMCP({
  name: "Mi Servidor",
  version: "1.0.0",
  authenticate: (request) => {
    const apiKey = request.headers["x-api-key"];
    if (apiKey !== process.env.MCP_API_KEY) {
      throw new Response(null, { status: 401, statusText: "Unauthorized" });
    }
    return { id: 1, role: "user" }; // esto se vuelve la sesión
  },
});

server.addTool({
  name: "sayHello",
  execute: async (args, { session }) => {
    return `Hola, usuario ${session.id}!`; // session viene de authenticate
  },
});

server.addTool({
  name: "procesar_lote",
  description: "Procesa un lote reportando progreso en vivo",
  parameters: z.object({ total: z.number() }),
  annotations: { streamingHint: true },
  execute: async (args, { streamContent, reportProgress, log, session }) => {
    log.info(`Iniciando lote para ${session.id}`);
    await streamContent({ type: "text", text: "Empezando..." });
    await reportProgress({ progress: 50, total: 100 });
    // ... trabajo real ...
    return "Completado";
  },
});

扮演一名资深 MCP 工程师。我们要用 FastMCP(那个包裹官方 MCP SDK、Anthropic 开源的那个框架;用 `npm install fastmcp zod` 安装)在 TypeScript 里构建一个 MCP 服务器。

我的服务器:
- 名称:[你服务器的名称,例如 "CRM Interno"]
- 它暴露什么:[用 2 行描述你想让 AI 碰的工具/数据]

我需要的 TOOLS(AI 会执行的动作):
1. [nombre_tool] — [做什么] — 输入:[字段及其类型/规则]
2. [nombre_tool] — [做什么] — 输入:[字段及其类型/规则]

RESOURCES(AI 会读取的数据,如适用):
- [nombre] — [暴露什么数据,例如日志、配置]

模式:[开发时从 "stdio local" 开始 | 之后为了生产迁移到 "httpStream con autenticación por API key"]

请构建:
1. 完整的 server.ts:带名称和版本的 `new FastMCP`,每个工具用 `addTool`(name、清晰的、面向让 AI 知道何时使用它的 description、作为真正会校验的 Zod schema 的 parameters——该用的地方用 .email()、.int().positive()、.enum(),可选项用 .optional(),以及带类型的 execute)。
2. 如果我要了,用 `addResource` 写 resources(uri、name、mimeType、返回 {text} 或 {blob} 的惰性 load)。
3. 用我选的传输方式写 `server.start`(stdio,或带 port/endpoint 的 httpStream)。
4. 如果我要了生产:`authenticate` 选项,从 `process.env` 读 API key(绝不硬编码),不匹配时抛 `new Response(null, {status: 401})` 并返回会话,外加一个使用 `session` 的工具。
5. 用来把它连到 Claude Code 的 `mcpServers` JSON 块,用 `npx tsx` 和绝对路径。
6. 确切的命令:安装、用 `npx fastmcp dev server.ts` 测试、用 `npx fastmcp inspect server.ts` 检视。

约束:代码里零密钥;工具的描述要写成 让 AI 能很好地决定何时调用它们;用 Zod 校验所有输入,不要手写 if。在代码前用一行向我解释每个工具。