🚀 FastMCP 速查手册

FastMCP 是一个强大的工具，可用于创建和管理 MCP 服务，能高效处理客户端请求，提供丰富的功能和灵活的配置选项。

🚀 快速开始

📦 安装

你可以通过以下两种方式安装 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 的核心，用于管理能力和处理客户端请求。

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'
});

💻 使用示例

基础用法

创建一个简单的 MCP 服务并定义一个能力：

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);

高级用法

定义自定义能力

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

事件监听

// 监听服务器事件
server.on('connection', () => {
    console.log('New client connected');
});

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

// 监听会话事件
const session = await server.currentSession;
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

📚 详细文档

MCP 服务器 API

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

MCP 会话 API

• MCPSession.sendMessage(message): Promise<void>
• MCPSession.requestSampling(options): Promise<void>
• MCPSession.currentSession: Promise<MCPSession>

🤔 常见问题解答

如何与 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')
    };
});

📄 许可证

文档中未提及相关许可证信息。