@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

安装

1npm i @cloudbase/mcp

使用示例

在云函数 2.0 上构建 MCP Server

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

1import { MCPServerRunner } from "@cloudbase/mcp/cloudrun";
2import { CloudbaseMcpServer } from "@cloudbase/mcp/server";
3import { z } from "zod";
4
5const createServer = () => {
6  const server = new CloudbaseMcpServer({
7    name: "hello-world",
8    version: "1.0.0",
9  });
10
11  server
12    .tool("getUserAge")
13    .description("查询用户的年龄")
14    .inputSchema({
15      userName: z.string().describe("用户名"),
16    })
17    .outputSchema({
18      age: z.number().describe("年龄"),
19    })
20    .formatter(({ userName }, { age }) => {
21      return {
22        content: [
23          {
24            type: "text",
25            text: `${userName} 的年龄是 ${age}`,
26          },
27        ],
28      };
29    })
30    .create(({ userName }) => {
31      if (userName === "张三") {
32        return {
33          age: 18,
34        };
35      } else if (userName === "李四") {
36        return {
37          age: 20,
38        };
39      } else {
40        throw new Error("未找到该用户的年龄");
41      }
42    });
43
44  return { server };
45};
46
47export const main = async function (event, context) {
48  const runner = new MCPServerRunner(createServer, { verifyAccess: false });
49  return runner.run(event, context);
50};

使用 PostClientTransport 连接至 MCP Server

1import { Client } from "@modelcontextprotocol/sdk/client/index.js";
2import { PostClientTransport } from '@cloudbase/mcp/transport/client/post';
3
4const transport = new PostClientTransport(
5  new URL(
6    "https://your-service-url/messages",
7  ),
8  {
9    requestInit: {
10      headers: {
11        Authorization: `Bearer your-token`,
12      },
13    },
14  },
15)
16
17const client = new Client(
18  {
19    name: "example-client",
20    version: "1.0.0"
21  },
22  {
23    capabilities: {
24      tools: {}
25    }
26  }
27);
28
29await client.connect(transport);

API Reference

MCPServerRunner

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

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

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

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

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

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

导入

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

static run()

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

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

参数

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

new()

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

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

参数

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

run()

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

1// 云函数 2.0
2// ...省略创建 MCP Server 实例过程 
3const runner = new MCPServerRunner(createServer,
4  { 
5    verifyAccess: true // 控制是否进行鉴权拦截
6  });
7export 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() 方法新增了链式调用的使用形式，其他能力保持不变

导入

1import { 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() 结束

1// ...省略创建 server 实例的过程
2server
3  // 只传入一个 `name` 参数触发链式调用
4  .tool('add')
5  // 为工具添加参数
6  .description('将两个数字相加')
7  // 为工具添加入参 schema 说明
8  .inputSchema({
9    a: z.number({
10      description: '被加数',
11    }),
12    b: z.number({
13      description: '加数',
14    }),
15  })
16  // 为工具添加出参 schema 说明
17  .outputSchema({
18    result: z.number({
19      description: '两个数字相加的结果',
20    }),
21  })
22  // 为工具添加出参 formatter
23  .formatter(({ a, b }, { result }) => {
24    return {
25      content: [
26        {
27          type: 'text',
28          text: `${a} + ${b} = ${result}`,
29        },
30      ],
31    };
32  })
33  // 最终传入实现函数，完成工具创建
34  .create(({ a, b }) => ({ result: a + b }));

其他用法

注册一个无参数工具:

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

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

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

注册一个带参数的工具:

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

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

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

PostClientTransport

MCP Client 使用的 Post Transport。

导入

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

new()

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

1const transport = new PostClientTransport(new URL("https://your-url"), {
2  requestInit: {
3    headers: {
4      Authorization: "Bearer <your-token>",
5    }
6  }
7})
8
9// 省略创建 MCP Client 过程
10await 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。

导入

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

new()

创建 PostServerTransport 实例。

1const transport  = new PostServerTransport();

handleMessage(message: JSONRPCMessage)

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

1// 云函数 2.0
2export const main = async (context, event) => {
3  // ...省略判断路由、HTTP Method 等过程
4
5  const transport = new PostServerTransport();
6  // ...省略创建 MCP Server 实例过程
7  server.connect(transport);
8
9  // ...省略判断 event 是否为合法 JSON RPC 消息过程
10  return server.handleMessage(event);
11}

参数

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