跳到主要内容

开发第一个 MCP Server

本文将逐步说明如何在云开发平台上开发一个 MCP Server，包含以下几个步骤：

  1. 用模板创建出 MCP Server 云托管服务
  2. 使用云开发 MCP 框架开发 MCP Server
  3. 使用图形界面本地调试 MCP Server
  4. 部署至线上，覆盖原有云托管服务
  5. 在 Agent 中使用 MCP Server

准备工作​

前往 云开发平台 创建一个 MCP Server，设置标识为 first-mcp。

该步骤会自动创建一个云托管服务承载 MCP Server，在后文中我们将会自己开发一个 MCP Server 并覆盖该云托管服务。

在本地新建一个 Node.js 项目:

mkdir my-mcp-server && cd my-mcp-server && npm init -y

安装依赖:

npm i @cloudbase/mcp zod
npm i -D @cloudbase/cli @dotenvx/dotenvx

为 MCP Server 添加第一个工具​

创建 index.js 并填入以下代码。这段代码创建了一个查询用户年龄的工具:

const { MCPServerRunner } = require("@cloudbase/mcp/cloudrun");
const { CloudbaseMcpServer } = require("@cloudbase/mcp/server");
const { z } = require("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 };
};

exports.main = async function (event, context) {
  const runner = new MCPServerRunner(createServer, {
    // 默认开启了访问验证，此处通过环境变量控制是否开启
    // 如果开启了访问验证，将会校验用户的 token，只允许 API Key 和超管身份的 token 调用
    verifyAccess: process.env.SKIP_VERIFY_ACCESS === "true" ? false : true,
  });
  return runner.run(event, context);
};

本地调试 MCP Server​

添加环境变量文件​

新建一个 .env.development 文件，填入以下内容:

MCP_SSE_ROUTE=LOCAL
SKIP_VERIFY_ACCESS=true

该文件定义了环境变量：

  • MCP_SSE_ROUTE=LOCAL：设置后可启用本地 SSE 服务，将 MCP Inspector/MCP Host（如 Cursor）连接至本地 MCP Server
  • SKIP_VERIFY_ACCESS=true：设置后可跳过 token 校验。原有 token 校验将只允许来自 API Key 和超管身份的 token 调用
提示

设置 MCP_SSE_ROUTE、SKIP_VERIFY_ACCESS 这两个环境变量有助于我们在本地进行调试，但不建议在线上生产环境设置。

添加本地开发、部署的 npm scripts​

修改 package.json 填入 scripts:

{ 
  // ...
 "scripts": {
    "login": "tcb login",
    "dev": "dotenvx run -f .env.development -- tcb cloudrunfunction run --port=3003 --enableCors=true -w",
    "deploy": "tcb cloudrunfunction deploy"
  },
  // ...
}

@cloudbase/cli 需要登录后才能使用，修改完 package.json 后，使用云开发账号登录:

npm run login

启动本地 MCP Server​

启动本地调试，会在 http://127.0.0.1:3003/messages 提供服务:

npm run dev

启动图形界面调试​

开启另一个终端，启动 @cloudbase/mcp-inspector:

npx -y @cloudbase/mcp-inspector

访问 http://127.0.0.1:5173 即可看到调试页面了。

配置左侧菜单:

点击 Connect 即可连接到 MCP Server 了。在 Tools Tab 下可获取 MCP Server 的工具列表，并在右侧表单进行调用。

部署​

测试无误后即可部署到云函数 2.0 了:

npm run deploy

选择环境后，服务名称输入 first-mcp。

使用线上的 MCP Server​

部署后，即可阅读以下文档使用 MCP Server 了: