FastMCP 速查手册

快速开始

安装

通过 npm 安装：

npm install fastmcp

或者使用 yarn：

yarn add fastmcp

创建 MCP 服务

创建一个新的 TypeScript 文件（例如 index.ts）并添加以下代码：

import { createMCPServer } from 'fastmcp';

async function main() {
    const server = await createMCPServer();

    // 定义一个简单的能力：返回当前目录的内容
    server.addCapability('ls', async () => {
        return {
            type: 'text',
            text: process.cwd()
        };
    });

    await server.start();
}

main().catch(console.error);

运行

使用以下命令运行您的服务：

node index.ts

核心概念

MCP 服务器

MCPServer 是 FastMCP 的核心，用于管理能力和处理客户端请求。

创建 MCP 服务器

import { createMCPServer } from 'fastmcp';

async function main() {
    const server = await createMCPServer();
    // ...
}

定义能力

使用 addCapability 方法定义服务器的能力：

server.addCapability('my_capability', async () => {
    return { type: 'text', text: 'Hello, World!' };
});

启动服务器

调用 start 方法启动 MCP 服务器：

await server.start();

会话管理

每个连接的客户端都会创建一个 MCPSession 实例。

获取当前会话

可以通过以下方式获取当前会话：

const session = await server.currentSession;

发送消息

使用 sendMessage 方法向客户端发送消息：

await session.sendMessage({
    role: 'assistant',
    content: { type: 'text', text: 'Hello, World!' }
});

采样请求

MCP 提供了 requestSampling 方法来进行采样请求。

示例代码

await session.requestSampling({
    messages: [
        {
            role: 'user',
            content: { type: 'text', text: 'What files are in the current directory?' }
        }
    ],
    systemPrompt: 'You are a helpful file system assistant.',
    includeContext: 'thisServer'
});

高级功能

定义能力

通过 addCapability 方法，您可以在服务器上添加自定义的能力。

示例代码

server.addCapability('searchFiles', async (query) => {
    // 在此处实现文件搜索逻辑
    return { type: 'text', text: `Searching for files matching ${query}` };
});

事件监听

MCP 提供了丰富的事件监听功能，您可以监听页面上的各种事件。

监听服务器事件

server.on('connection', () => {
    console.log('New client connected');
});

server.on('disconnection', () => {
    console.log('Client disconnected');
});

监听会话事件

session.on('message', (message) => {
    console.log('Received message:', message);
});

session.on('error', (error) => {
    console.error('Session error:', error);
});

配置选项

启动配置

可以通过传递一个配置对象来自定义服务器的启动行为。

示例代码

await createMCPServer({
    port: 3000,
    host: 'localhost',
    capabilities: {
        my_capability: () => ({
            type: 'text',
            text: 'Hello, World!'
        })
    }
});

会话配置

您可以通过会话配置来调整客户端的某些行为。

示例代码

session.setClientCapabilities({
    experimentalFeatures: true,
    loggingLevel: 'debug'
});

工具和资源

MCP CLI

使用 fastmcp dev 命令快速启动开发服务器：

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

MCP 监控器

使用官方的 MCP 监控器 通过 Web UI 检查您的服务器：

npx fastmcp inspect server.ts

常见问题解答

如何与 Claude Desktop 配合使用？

请按照指南 此处 进行操作，并添加以下配置：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["index.js"]
    }
  }
}

如何处理自定义协议？

FastMCP 目前支持标准的 MCP 协议，暂不支持自定义协议。请关注后续版本更新。

教程和示例

简单的文件管理器

创建一个基本的文件管理能力：

server.addCapability('listFiles', async () => {
    const files = await fs.promises.readdir('.');
    return {
        type: 'text',
        text: files.join('\n')
    };
});

参考文档

MCP 服务器 API

• createMCPServer([config]): Promise<MCPServer>
• MCPServer.start(): Promise<void>
• MCPServer.addCapability(name, callback): void
• MCPServer.on(event, listener): void

MCP 会话 API

• `M