❤
npm
Sign UpSign In

@cloudbase/mcp

1.0.0-beta.23 • Public • Published

@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 消息

Readme

Keywords

none

Package Sidebar

Install

npm i @cloudbase/mcp

Weekly Downloads

81

Version

1.0.0-beta.23

License

Apache-2.0

Unpacked Size

259 kB

Total Files

76

Last publish

Collaborators

  • wangjiachen
  • daniel-dx
  • starkwang
  • yhyang
  • binggg
  • fengkx
  • liuyanjie
  • justan
  • woodenstone
  • miusuncle
  • wedabot
  • areo-joe
Try on RunKit
Report malware