@cloudbase/mcp

@cloudbase/mcp 提供了一系列构建 MCP 的工具。包括

Post Transport 支持。目前 MCP 官方的远程链接基于 SSE，需要长链接且对 Serverless 不友好。无状态的 MCP Server 能够满足大多数场景，使用 Post Transport 在无状态的 Serverless 云函数上构建无状态的 MCP Server
Cloudbase 云函数 2.0 支持。提供了针对云函数 2.0 的框架，专注 MCP Server 开发，快速接入部署至云函数 2.0

安装

npm i @cloudbase/mcp

使用示例

在云函数 2.0 上构建 MCP Server

此代码会默认在 /messages 提供 MCP Server 服务。

import { MCPServerRunner } from "@cloudbase/mcp/cloudrun";
import { CloudbaseMcpServer } from "@cloudbase/mcp/server";
import { z } from "zod";

const createServer = () => {
  const server = new CloudbaseMcpServer({
    name: "hello-world",
    version: "1.0.0",
  });

  server
    .tool("getUserAge")
    .description("查询用户的年龄")
    .inputSchema({
      userName: z.string().describe("用户名"),
    })
    .outputSchema({
      age: z.number().describe("年龄"),
    })
    .formatter(({ userName }, { age }) => {
      return {
        content: [
          {
            type: "text",
            text: `${userName} 的年龄是 ${age}`,
          },
        ],
      };
    })
    .create(({ userName }) => {
      if (userName === "张三") {
        return {
          age: 18,
        };
      } else if (userName === "李四") {
        return {
          age: 20,
        };
      } else {
        throw new Error("未找到该用户的年龄");
      }
    });

  return { server };
};

export const main = async function (event, context) {
  const runner = new MCPServerRunner(createServer, { verifyAccess: false });
  return runner.run(event, context);
};

使用 PostClientTransport 连接至 MCP Server

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { PostClientTransport } from '@cloudbase/mcp/transport/client/post';

const transport = new PostClientTransport(
  new URL(
    "https://your-service-url/messages",
  ),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer your-token`,
      },
    },
  },
)

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

await client.connect(transport);

API Reference

MCPServerRunner

在云函数 2.0 中运行 MCP Server 的工具类，提供了以下功能：

路由判断
鉴权
自动处理 HTTP 请求/响应

可以用几行代码在云函数 2.0 上运行 MCP Server：

// 云函数 2.0
// ...省略 createServer 函数实现
export const main = (event, context) => MCPServerRunner.run(event, context, createServer) 

上述代码会在 /messages 提供 MCP Server 服务，默认根据从 HTTP Header 中读取的云开发 accessToken 进行拦截，只允许来自 apiKey 和管理员身份的调用。可以传入特定参数，修改默认行为:

// 云函数 2.0
// ...省略 createServer 函数实现
const runner = new MCPServerRunner(createServer,
  { 
    verifyAccess: false // 控制是否进行鉴权拦截
  });
export const main = (event, context) => runner.run(event, context); 

导入

import { MCPServerRunner } from '@cloudbase/mcp/cloudrun';

`static run()`

MCPServerRunner 上的静态方法，按默认配置在云函数 2.0 上运行 MCP Server。

// 云函数 2.0
// ...省略 createServer 函数实现
export const main = (event, context) => MCPServerRunner.run(event, context, createServer) 

参数

名称	必需	描述
event	是	将云函数 2.0 接收的 event 参数传入即可
context	是	将云函数 2.0 接收的 context 参数传入即可
createServer	是	返回 MCP Server 的实例的函数

`new()`

创建一个 MCPServerRunner 实例，可传入参数控制 run() 方法的行为。

// ...省略 createServer 函数实现
const runner = new MCPServerRunner(createServer,
  { 
    verifyAccess: true // 控制是否进行鉴权拦截
  });

参数

名称	类型	必需	描述
createServer	function	是	创建并返回MCP Server实例的函数
prop	`object`	否	控制 `MCPServerRunner` 的行为
prop.verifyAccess	`boolean`	否	控制是否进行鉴权拦截，若为 `true`，则只允许来自 apiKey 和管理员身份的调用

`run()`

根据 MCPServerRunner 实例上的参数配置在云函数 2.0 上运行 MCP Server。

// 云函数 2.0
// ...省略创建 MCP Server 实例过程 
const runner = new MCPServerRunner(createServer,
  { 
    verifyAccess: true // 控制是否进行鉴权拦截
  });
export const main = (event, context) => runner.run(event, context); 

参数

名称	类型	必需	描述
event		是	将云函数 2.0 接收的 event 参数传入即可
context		是	将云函数 2.0 接收的 context 参数传入即可

CloudbaseMcpServer

Cloudbase 扩展的 MCP Server。使用此类可以快速构建一个 MCP Server 实例。此类基于 Claude MCP SDK 中的 McpServer 进行扩展，为 tool() 方法新增了链式调用的使用形式，其他能力保持不变

导入

import { CloudbaseMcpServer } from "@cloudbase/mcp/server";

tool()

在此 server 上创建一个工具。此方法有多种方式调用。

推荐用法：链式调用

我们推荐使用链式调用：通过调用 tool() 且只传入 1 个 name 参数触发链式调用。可连续调用 description()、inputSchema()、outputSchema()、formatter() 来为工具添加不同的属性，最后通过调用 .create() 传入该工具对应的函数实现，完成该工具的创建。

在 tool() 和 create() 之间出现的 description()、inputSchema()、outputSchema()、formatter() 均为可选，可以省略任一调用
description()、inputSchema()、outputSchema()、formatter() 的出现顺序是任意的，可按任意的顺序进行调用
需要保证链式调用以 tool() 开始、以 create() 结束

// ...省略创建 server 实例的过程
server
  // 只传入一个 `name` 参数触发链式调用
  .tool('add')
  // 为工具添加参数
  .description('将两个数字相加')
  // 为工具添加入参 schema 说明
  .inputSchema({
    a: z.number({
      description: '被加数',
    }),
    b: z.number({
      description: '加数',
    }),
  })
  // 为工具添加出参 schema 说明
  .outputSchema({
    result: z.number({
      description: '两个数字相加的结果',
    }),
  })
  // 为工具添加出参 formatter
  .formatter(({ a, b }, { result }) => {
    return {
      content: [
        {
          type: 'text',
          text: `${a} + ${b} = ${result}`,
        },
      ],
    };
  })
  // 最终传入实现函数，完成工具创建
  .create(({ a, b }) => ({ result: a + b }));

其他用法

注册一个无参数工具:

// 注册一个无参数工具
server.tool('sayHello', () => {
  return { content: [{ type: 'text', text: 'Hello World' }] }
})

注册一个带描述的无参数工具:

// 注册一个带描述的无参数工具
server.tool('sayHello', '返回一个简单的问候语', () => {
  return { content: [{ type: 'text', text: 'Hello World' }] }
})

注册一个带参数的工具:

// 注册一个带参数的工具
server.tool('add', {
  a: z.number(),
  b: z.number()
}, ({ a, b }) => {
  return { result: a + b }
})

注册一个带描述和参数的工具:

// 注册一个带描述和参数的工具
server.tool('add', '将两个数字相加', {
  a: z.number(),
  b: z.number()
}, ({ a, b }) => {
  return { result: a + b }
})

PostClientTransport

MCP Client 使用的 Post Transport。

导入

import { PostClientTransport } from '@cloudbase/mcp/transport/client/post';

`new()`

创建 PostClientTransport 实例，可传入第二个参数 opts 控制网络请求行为。

const transport = new PostClientTransport(new URL("https://your-url"), {
  requestInit: {
    headers: {
      Authorization: "Bearer <your-token>",
    }
  }
})

// 省略创建 MCP Client 过程
await client.connect(transport);

参数

名称	类型	必需	描述
url	`URL`	是	指向 MCP Server 的 url
opts	`PostClientTransportOptions`	否
opts.requestInit	`RequestInit`	否	发起网络请求时携带的参数，当 PostClientTransport 发送网络请求时，会携带上传入的参数。可用来传入鉴权请求头等。

PostServerTransport

MCP Server 使用的 Post Transport。

在云函数 2.0 场景下，无需直接使用 PostServerTransport，推荐直接使用 CloudbaseMcpServer，只需要关注 MCP Server 的实现。

在其他平台/环境下，可按需使用此类构建基于 Post Transport 的 MCP Server。

导入

import { PostServerTransport } from '@cloudbase/mcp/transport/server/post';

`new()`

创建 PostServerTransport 实例。

const transport  = new PostServerTransport();

`handleMessage(message: JSONRPCMessage)`

处理客户端发送过来的 JSON RPC 消息。当服务器接收到客户端用 HTTP 请求发送的 JSON RPC 消息时，需要调用此方法进行处理。该方法可能会返回一个 JSON RPC 消息，此时调用者需要将结果作为 HTTP 响应体返回给客户端。

// 云函数 2.0
export const main = async (context, event) => {
  // ...省略判断路由、HTTP Method 等过程

  const transport = new PostServerTransport();
  // ...省略创建 MCP Server 实例过程
  server.connect(transport);

  // ...省略判断 event 是否为合法 JSON RPC 消息过程
  return server.handleMessage(event);
}

参数

名称	类型	必需	描述
message	`JSONRPCMessage`	是	接收到的 JSON RPC 消息

@cloudbase/mcp

安装​

使用示例​

在云函数 2.0 上构建 MCP Server​

使用 PostClientTransport 连接至 MCP Server​

API Reference​

MCPServerRunner​

导入​

static run()​

参数​

new()​

参数​

run()​

参数​

CloudbaseMcpServer​

导入​

tool()​

推荐用法：链式调用​

其他用法​

PostClientTransport​

导入​

new()​

参数​

PostServerTransport​

导入​

new()​

handleMessage(message: JSONRPCMessage)​

参数​

安装

使用示例

在云函数 2.0 上构建 MCP Server

使用 PostClientTransport 连接至 MCP Server

API Reference

MCPServerRunner

导入

`static run()`

参数

`new()`

参数

`run()`

参数

CloudbaseMcpServer

导入

tool()

推荐用法：链式调用

其他用法

PostClientTransport

导入

`new()`

参数

PostServerTransport

导入

`new()`

`handleMessage(message: JSONRPCMessage)`

参数