@mcp-it/fastify

🤖 从您的 Fastify API 路由自动生成 MCP 工具。

这是一个用于 Model Context Protocol (MCP) 的 Fastify 插件 (@mcp-it/fastify)，它允许您将 Fastify 路由作为 MCP 工具暴露出来。这使得 AI 助手能够通过 MCP 协议直接与您的 API 进行交互。

概述

此插件会自动发现您的 Fastify 路由，并将它们作为工具暴露给像 Cursor 或 Claude 这样的 MCP 客户端使用。它利用了 Fastify 的模式系统来生成完整的工具定义。

[!NOTE]
尽管这个包特别针对 Fastify，但 @mcp-it 命名空间未来可能会托管其他 Node.js 框架（如 Express、NestJS 等）的适配器。

安装

npm install @mcp-it/fastify
# or
yarn add @mcp-it/fastify
# or
pnpm add @mcp-it/fastify

使用

import Fastify from "fastify";
import mcpPlugin from "@mcp-it/fastify";

const fastify = Fastify();

// Register the MCP plugin
await fastify.register(mcpPlugin, {
  name: "My API",
  description: "My API with MCP support",
});

// Define your routes with schemas and operation IDs
fastify.get(
  "/users/:id",
  {
    schema: {
      operationId: "get_user", // Used as the tool name
      summary: "Get user by ID",
      description: "Returns a user by their ID",
      params: {
        type: "object",
        required: ["id"],
        properties: {
          id: { type: "number", description: "User ID" },
        },
      },
      response: {
        200: {
          description: "Successful response",
          type: "object",
          properties: {
            id: { type: "number" },
            name: { type: "string" },
            email: { type: "string" },
          },
        },
      },
    },
    // Add MCP-specific config if needed, e.g.:
    // config: {
    //   mcp: { hidden: true }
    // }
  },
  async (request) => {
    // Implementation...
    const userId = (request.params as any).id;
    // ... fetch user
    return { id: userId, name: "Example User", email: "user@example.com" };
  }
);

await fastify.listen({ port: 3000 });

console.log("MCP SSE server running at http://localhost:3000/mcp/sse");

特性

• 自动路由发现：利用 Fastify 钩子识别所有已注册的路由。
• 模式利用：使用 Fastify 路由模式进行全面的工具生成。
• 每路由配置：允许对每个路由进行定制化设置。
• 多种传输方式：支持 Server-Sent Events 和 Streamable HTTP 传输。
• 调试端点：一个可选端点，用于独立于传输查看生成的工具。

配置选项

选项	类型	默认值	描述
name	string	"Fastify MCP"	显示给客户端的 MCP 服务器名称。
description	string	"MCP server for Fastify"	MCP 服务器的描述。
transportType	string	"sse"	使用的传输协议："sse" 或 "streamableHttp"。
describeFullSchema	boolean	false	在描述中包含详细的输入/输出模式和示例。
skipHeadRoutes	boolean	true	从生成的 MCP 工具中排除 HEAD 路由。
skipOptionsRoutes	boolean	true	从生成的 MCP 工具中排除 OPTIONS 路由。
mountPath	string	"/mcp"	MCP SSE 和消息端点挂载的基础路径前缀。
filter	Function	undefined	自定义过滤函数 (route: Route) => boolean。
addDebugEndpoint	boolean	false	添加一个 GET /<mountPath>/tools 端点列出生成的工具。

路由配置 (config.mcp)

您可以在路由的 config 对象中直接添加特定的 MCP 配置。可用的选项如下：

选项	类型	默认值	描述
hidden	boolean	false	从 MCP 服务器隐藏此路由
name	string	operationId 或 method_url	覆盖默认工具名称
description	string	路由的 schema 描述	覆盖工具描述

示例用法：

fastify.get(
  "/some-route",
  {
    config: {
      mcp: {
        name: "custom_tool_name", // Override the default tool name
        description: "Custom description for this tool", // Override the default description
      },
    },
    // ... other route options
  },
  async (request, reply) => {
    /* ... */
  }
);

访问 MCP 服务器实例

此插件通过 @modelcontextprotocol/sdk 中的基础 MCP Server 实例来装饰 Fastify 实例。在插件注册后，您可以通过 fastify.mcpServer 访问它。

这在以下高级场景中可能有用：

• 直接与 MCP 服务器的生命周期或方法交互。
• 添加自定义请求处理器或超出基本工具暴露的功能。

import Fastify from "fastify";
import mcpPlugin from "@mcp-it/fastify";
import type { Server } from "@modelcontextprotocol/sdk/server/index.js";

const fastify = Fastify();

await fastify.register(mcpPlugin, {
  /* options */
});

// Now you can access the MCP server instance
console.log("MCP Server:", fastify.mcpServer);

// Example: Add a custom handler (use with caution)
// fastify.mcpServer.setRequestHandler(...);

// ... rest of your application setup

await fastify.listen({ port: 3000 });

示例

请参阅 examples 目录中的完整工作示例，以了解各种功能的演示。

客户端配置

Cursor

在 Cursor 设置（设置 -> MCP）中，使用 URL 添加一个新的 SSE 连接：

http://localhost:3000/mcp/sse

（将 localhost:3000 替换为您的服务器地址，并根据需要将 mcp 替换为您的 mountPath）。

Claude Desktop

使用 mcp-proxy 在期望 stdio 的 Claude Desktop 和 SSE 端点之间进行桥接。

在您的 Claude Desktop MCP 配置文件 (claude_desktop_config.json) 中添加以下内容：

{
  "mcpServers": {
    "my-fastify-api": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp/sse"]
    }
  }
}

（将 localhost:3000 替换为您的服务器地址，并根据需要将 mcp 替换为您的 mountPath）。

或者，如果您的客户端支持，您可以使用可流式传输的 HTTP 端点（Cursor 可能需要针对非 SSE 端点进行配置或代理）。