@cloudbase/mcp

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

Cloudbase 函数型云托管支持。提供了针对函数型云托管的框架，专注 MCP Server 开发，快速接入部署至函数型云托管

安装

npm i @cloudbase/mcp

使用示例

在函数型云托管上构建 MCP Server

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

import { StreamableHTTPMCPServerRunner } from "@cloudbase/mcp/cloudrun";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

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

  server.registerTool("getUserAge", {
    description: "查询用户的年龄",
    inputSchema: {
      userName: z.string().describe("用户名"),
    },
    outputSchema: {
      age: z.number().describe("年龄"),
    },
  }, ({userName}) => {
    let structuredContent
    if (userName === "张三") {
      structuredContent = {
        age: 18,
      };
    } else if (userName === "李四") {
      structuredContent = {
        age: 20,
      };
    } else {
      throw new Error("未找到该用户的年龄");
    }

    return {
      structuredContent,
      content: [
        {
          type: "text",
          text: JSON.stringify(structuredContent),
        }
      ]
    }
  })

  return { server };
}

export const main = (event, context) => {
  return StreamableHTTPMCPServerRunner.run(event, context,createServer)
}

API Reference

StreamableHTTPMCPServerRunner

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

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

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

// 函数型云托管
// ...省略 createServer 函数实现
export const main = (event, context) => StreamableHTTPMCPServerRunner.run(event, context, createServer) 

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

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

导入

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

`static run()`

StreamableHTTPMCPServerRunner 上的静态方法，按默认配置在函数型云托管上运行 MCP Server。

// 函数型云托管
// ...省略 createServer 函数实现
export const main = (event, context) => StreamableHTTPMCPServerRunner.run(event, context, createServer) 

参数

名称	必需	描述
event	是	将函数型云托管接收的 event 参数传入即可
context	是	将函数型云托管接收的 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 和管理员身份的调用
prop.sessionIdGenerator	`() => string`	否	sessionId 生成函数，若传入则会建立有状态的服务
prop.sessionTimeout	`number`	否	sessionId 过期时间（ms），此参数仅在有状态的服务中生效

`run()`

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

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

参数

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

MCPServerRunner

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

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

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

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

// 函数型云托管
// ...省略 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 上的静态方法，按默认配置在函数型云托管上运行 MCP Server。

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

参数

名称	必需	描述
event	是	将函数型云托管接收的 event 参数传入即可
context	是	将函数型云托管接收的 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 实例上的参数配置在函数型云托管上运行 MCP Server。

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

参数

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

CloudbaseMcpServer 【deprecated】

危险

【重要】该类已废弃。 CloudbaseMcpServer 相比于早期的 MCP 官方 SDK ，额外提供了 outputSchema 的支持。目前 MCP 官方 SDK 已经提供了对 outputSchema 的支持，我们推荐直接使用 MCP 官方 SDK。

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 【deprecated】

危险

【重要】该类已废弃。 PostClientTransport 相比于早期的 MCP 官方 SDK ，对无状态 MCP Server 的支持更为友好。目前 MCP 官方 SDK 已经提供了 Streamable HTTP Transport ，无状态和有状态的 MCP Server 都能使用该 Transport 类型进行构建。对于无状态的服务，我们推荐直接使用 Streamable HTTP Transport 。

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 【deprecated】

危险

【重要】该类已废弃。 PostServerTransport 相比于早期的 MCP 官方 SDK ，对无状态 MCP Server 的支持更为友好。目前 MCP 官方 SDK 已经提供了 Streamable HTTP Transport ，无状态和有状态的 MCP Server 都能使用该 Transport 类型进行构建。对于无状态的服务，我们推荐直接使用 Streamable HTTP Transport 。

MCP Server 使用的 Post Transport。

在函数型云托管场景下，无需直接使用 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 响应体返回给客户端。

// 函数型云托管
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

安装​

使用示例​

在函数型云托管上构建 MCP Server​

API Reference​

StreamableHTTPMCPServerRunner​

导入​

static run()​

参数​

new()​

参数​

run()​

参数​

MCPServerRunner​

导入​

static run()​

参数​

new()​

参数​

run()​

参数​

CloudbaseMcpServer 【deprecated】​

导入​

tool()​

推荐用法：链式调用​

其他用法​

PostClientTransport 【deprecated】​

导入​

new()​

参数​

PostServerTransport 【deprecated】​

导入​

new()​

handleMessage(message: JSONRPCMessage)​

参数​

安装

使用示例

在函数型云托管上构建 MCP Server

API Reference

StreamableHTTPMCPServerRunner

导入

`static run()`

参数

`new()`

参数

`run()`

参数

MCPServerRunner

导入

`static run()`

参数

`new()`

参数

`run()`

参数

CloudbaseMcpServer 【deprecated】

导入

tool()

推荐用法：链式调用

其他用法

PostClientTransport 【deprecated】

导入

`new()`

参数

PostServerTransport 【deprecated】

导入

`new()`

`handleMessage(message: JSONRPCMessage)`

参数