企业官网建设流程全解析

做了几年的低代码和 AI Agent 相关工具，我发现一个非常普遍的困惑：很多人一打开 Workbuddy，看到“连接器”三个字，下意识以为它是类似“数据库驱动”或“API 封装”的东西；再看到“MCP”，又以为是某种协议层面的黑科技。这两者到底是不是一回事？为什么别人能做“设计稿一键变 APP”，而自己配置完连接器却总是用不了？

这篇文章就围绕 Workbuddy 入门阶段最容易被卡住的两个核心概念展开：连接器和 MCP。我会先讲清楚它们各自是什么、有什么关系，然后带着你从零配置一个本地数据库 MCP Server，再用同一套思路打通“设计稿 → APP 前端页面”的完整链路。内容偏实战，代码和配置可直接复制，新手可以照着做，有一定基础的开发者也可以重点看第 7 节的排错思路。

1. 背景：连接器与 MCP 到底在解决什么问题

1.1 从手动复制到 AI 自动取数

我们先看一个日常场景：假设你负责一个电商项目，需求是“统计今天已支付订单金额”。传统开发模式下，你需要写 SQL、连数据库、跑接口、把结果填到报表里。如果是 AI 来干这个活，它第一步要能访问数据库，第二步要知道表结构，第三步才能真正执行查询。

这里的第一步和第二步，就是连接器的职责范围。连接器负责把 Workbuddy 这个 AI Agent 工作平台和外部系统（数据库、API、设计稿平台、文件系统等）打通。打通之后，AI 才能“拿到数据”或者“调用能力”。

但问题来了：外部系统千千万万，数据库类型有 MySQL、PostgreSQL、Oracle、SQLite；设计稿平台有 Figma、蓝湖；企业内部还有各种自研系统。如果每接一个系统都要单独定制一套接入方案，成本会非常高。MCP 的出现，就是为了把这些“连接方式”统一成一套标准协议。

1.2 两个“连接器”不要混淆：硬件连接器 vs 软件连接器

在开始之前，先做一个概念澄清。搜索资料时，你可能会看到“VPX 背板连接器插损”“射频连接器接触电阻”“JST 连接器 3D 图”这些内容，它们属于硬件电气连接器领域，跟 Workbuddy 里的软件连接器完全不是一回事。本文讨论的连接器，特指软件集成层面的“连接器”，即把外部系统的能力和数据接入到 Workbuddy 工作流中的集成组件。

另外，在 Flink、低代码平台等场景中也会出现“JDBC 连接器”“FaaS 连接器”等术语。它们的本质思想一致，都是“把外部系统能力封装成主系统可调用的单元”，但落地的技术标准和适用场景并不相同。Workbuddy 中的连接器，是面向 AI Agent 使用的，强调的是“AI 能理解、可调用、能返回结构化结果”。这也是为什么 MCP 连接器会成为目前最受关注的一类连接器。

2. MCP 是什么：模型上下文协议

2.1 MCP 的核心角色

MCP 的全称是 Model Context Protocol，中文一般叫“模型上下文协议”。它是一个开放的、面向 AI 应用的协议，核心目标是让大模型可以以一种标准化的方式，访问外部工具、数据源和资源。

在 MCP 的体系里，主要有三个角色：

• MCP Client：运行在 AI 应用侧，比如 Workbuddy 就是客户端。它负责把模型请求转发给 MCP Server。
• MCP Server：运行在数据源或工具侧，是一段独立的程序。它负责把外部能力封装成一个一个的“工具”（Tool）或“资源”（Resource）暴露给客户端。
• 传输层：MCP 支持 stdio（标准输入输出）和 HTTP/SSE 两种主要传输方式。本地调试常用 stdio，跨机器通信常用 HTTP。

打个比方：MCP Server 像是一个“翻译员”，把数据库的 SQL、设计稿平台的 API、企业内部系统的接口，统一翻译成 AI 能理解的工具描述；AI 只需要知道“我可以调用哪些工具、每个工具需要什么参数、返回什么结果”，而不需要关心底层系统是什么。

Workbuddy (MCP Client) <-- JSON-RPC 消息 --> MCP Server <-- 内部SDK/API --> MySQL / Figma / 企业内部系统

2.2 MCP 的工作过程

一次完整的 MCP 调用通常是这样：

1. 初始化握手：客户端和 Server 建立连接，交换协议版本和能力声明。
2. 获取工具列表：客户端向 Server 询问“你暴露了哪些工具、参数是什么”。
3. 调用工具：客户端根据大模型的意图，携带参数调用指定工具。
4. 返回结果：Server 执行实际操作，把结果返回给客户端。
5. 模型理解结果：大模型把结构化的返回结果组织成自然语言回答给用户。

从效果上看，MCP 让 AI 从“只能聊”变成了“能干活”。这也是为什么很多人说“MCP 是 AI 应用的 USB-C 接口”——一个标准接口，可以连接各种不同的外设。

2.3 一个最简单的 JSON-RPC 消息

MCP 的消息基于 JSON-RPC 2.0 格式。下面是一段初始化请求和工具调用的示意（协议版本号请以你实际使用的 SDK 为准）：

// 初始化握手（示意） {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-03-26", "capabilities": {}}} // 获取工具列表（示意） {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}} // 调用工具（示意） {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "query_order_count", "arguments": {"status": "PAID"}}}

你不用手动去拼这些消息，MCP SDK 已经帮你封装好了。这里写出来是为了让你理解：MCP 不是魔法，它本质上就是客户端和 Server 之间约定好的一种“请求/响应”格式。

3. 连接器和 MCP 的关系

3.1 一句话总结

连接器是 Workbuddy 中“接入外部系统”的统称，而 MCP 是其中一种标准化的接入方式。当一个连接器采用 MCP 协议进行通信时，我们通常叫它“MCP 连接器”；这个连接器背后真正干活的程序，就是 MCP Server。

举个例子：你要在 Workbuddy 里连接数据库。你可以选择数据库直连连接器，在配置里填上 JDBC 地址和账号；也可以选择 MCP 连接器，在配置里指定一个 MCP Server 的启动命令，由这个 Server 负责和数据库交互。

两种方式的区别在于：数据库直连连接器只能做数据库连接，而 MCP 连接器可以通过不同的 MCP Server 做数据库查询、设计稿读取、文件搜索、API 调用等各种事情。换句话说，MCP 连接器是一个“通用容器”。

3.2 一张表看懂区别

注意这里有一个很容易踩的误区：不是所有连接器都必须改为 MCP。如果只是连接某个固定的 MySQL 数据库，数据库直连连接器可能更简单；但如果你的目标是让 AI 根据自然语言动态决定“查哪张表、调用哪个工具”，MCP 会灵活很多。

3.3 为什么“连接器均无法使用”多半和 MCP 配置有关

搜索“Workbuddy 连接器”相关问题时，经常能看到“连接器均无法使用了”的反馈。结合我的排查经验，这类问题十有八九不是 Workbuddy 本身坏了，而是连接器对应的 MCP Server 没有正常启动或协议握手失败。

典型原因包括：

• MCP Server 依赖的 Python/Node 环境不匹配，启动即报错。
• 使用 stdio 模式时，Server 端打印了日志，污染了标准输出，导致 JSON-RPC 消息解析失败。
• 配置文件里 command 的可执行文件路径写错，或者 args 参数不对。
• 网络权限限制，Server 无法访问外部 API。
• MCP SDK 版本升级后，协议版本号不兼容。

这些问题我都会在第 7 节给出排查清单。接下来我们先从环境准备开始，一步步把连接器跑起来。

4. 环境准备

4.1 安装 Workbuddy

Workbuddy 提供桌面端和网页端。桌面端通常在官网下载安装包，网页端直接在浏览器打开即可。本文以桌面端为参考环境，重点讲清配置思路，具体菜单位置以你安装的版本为准。

安装完成后，建议先完成基础登录和偏好设置。如果你是第一次接触，可以先在空工作区里试一下默认的对话功能，确认 AI 服务本身可以正常响应，再开始配置连接器。

4.2 准备 MCP Server 环境

由于后面要运行一个本地数据库 MCP Server，我们需要准备 Python 环境。建议使用 Python 3.10 及以上版本，并创建独立的虚拟环境，避免和系统 Python 环境互相干扰。

python3 -m venv workbuddy-mcp-env source workbuddy-mcp-env/bin/activate # Windows 下使用 workbuddy-mcp-env\Scripts\activate pip install mcp

如果下载速度较慢，可以临时使用国内镜像源：

pip install mcp -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，验证一下：

python -c "import mcp; print(mcp.__version__)"

能够输出版本号，说明 MCP SDK 已安装成功。这里的版本号会因安装时间不同而变化，如果后续代码写法有差异，以官方文档为准。

4.3 准备设计稿平台账号

如果要做“设计稿变 APP”的实验，你还需要一个设计稿平台账号。Figma 和蓝湖是当前比较常见的两种：

• Figma：需要准备个人访问令牌（Personal Access Token），并在设计稿中开启分享链接权限。
• 蓝湖：通常需要在团队项目中开启“开发者权限”，并获取对应的访问凭证。

不同平台的 MCP Server 配置方式不同，但整体链路是相通的：设计稿平台提供 API，MCP Server 封装 API，Workbuddy 调用 MCP Server。你不需要提前了解所有 API，只需要确保设计稿里的 Frame 命名规范清晰即可，这一点在后面的实战里会体现价值。

5. 实战一：通过 MCP 连接数据库

5.1 创建数据库和测试数据

先创建一个 SQLite 数据库，用来做演示。SQLite 是 Python 内置支持的数据库，不需要额外安装服务端。

mkdir workbuddy-db-demo cd workbuddy-db-demo python -c " import sqlite3 conn = sqlite3.connect('workbuddy_demo.db') cursor = conn.cursor() cursor.execute(''' CREATE TABLE IF NOT EXISTS orders ( id INTEGER PRIMARY KEY AUTOINCREMENT, status TEXT NOT NULL, amount REAL NOT NULL, created_at TEXT DEFAULT (datetime('now')) ) ''') cursor.executemany( 'INSERT INTO orders(status, amount) VALUES (?, ?)', [('PAID', 199.0), ('PAID', 299.0), ('SHIPPED', 399.0), ('REFUNDED', 99.0)] ) conn.commit() conn.close() print('数据库初始化完成') "

这段脚本会创建一张orders订单表，并写入 4 条测试数据。执行后，当前目录下会出现workbuddy_demo.db文件。

5.2 编写一个最简 MCP Server

在同一个目录下创建server.py。这是核心代码，作用是暴露一个get_order_count工具，AI 可以通过它查询不同状态的订单数量。

# 文件路径：workbuddy-db-demo/server.py import sqlite3 from mcp.server.fastmcp import FastMCP mcp = FastMCP("order-helper") @mcp.tool() def get_order_count(status: str) -> int: """根据订单状态统计订单数量。status 可选值：PAID、SHIPPED、REFUNDED。""" conn = sqlite3.connect("workbuddy_demo.db") try: cursor = conn.execute( "SELECT COUNT(*) FROM orders WHERE status = ?", (status,), ) row = cursor.fetchone() return row[0] if row else 0 finally: conn.close() if __name__ == "__main__": mcp.run()

代码说明：

• FastMCP是 MCP SDK 提供的高层封装，适合快速注册工具。
• @mcp.tool()装饰器把函数暴露成 MCP 工具，工具名默认是函数名get_order_count。
• 函数的第一段字符串是工具描述，AI 会根据这段描述判断什么时候调用该工具。
• 这里用了参数化 SQL，避免拼字符串产生注入风险。
• mcp.run()默认以 stdio 模式运行，这样 Workbuddy 可以通过标准输入输出和它通信。

5.3 在 Workbuddy 中添加 MCP 连接器

打开 Workbuddy 的连接器管理面板（通常在“连接器”或“Connectors”页面），点击“新增连接器”，选择 MCP 类型。然后填写启动配置：

{ "name": "order-db-mcp", "type": "mcp", "transport": "stdio", "command": "python", "args": ["server.py"], "env": { "PYTHONUNBUFFERED": "1" } }

如果你使用的是虚拟环境，command建议直接写虚拟环境里 python 的绝对路径，否则 Workbuddy 可能找不到mcp模块。例如：

# 查看 python 绝对路径 which python # 示例输出：/Users/你的用户名/workbuddy-mcp-env/bin/python

把输出路径填入command字段即可。PYTHONUNBUFFERED=1是为了避免 Python 缓冲日志，导致 MCP 消息延迟。

保存并启用这个连接器后，Workbuddy 会自动启动server.py，并完成 MCP 握手。你可以在连接器详情页看到“已连接”状态，以及该 Server 暴露的工具列表。

5.4 运行与验证

回到 Workbuddy 的对话界面，发送：

查询已支付订单数量

正常情况下，AI 会识别出需要调用get_order_count工具，并传入status=PAID。返回结果应该是 2。

你也可以直接调用工具测试：

调用 get_order_count 工具，参数 status 为 REFUNDED

预期返回 1。

这一步如果能跑通，说明你已经理解了 MCP 连接器的完整工作流程：Workbuddy 作为客户端，自动发现工具、携带参数调用、拿到结构化结果，再由 AI 组织成自然语言返回。

5.5 为什么推荐用 MCP 而不是直连数据库

有人可能会问：Workbuddy 不是自带数据库连接器吗，为什么还要自己写 MCP Server？

从工程角度看，MCP 方式有几个优势：

• 可以控制权限。MCP Server 里只暴露“统计数量”这类只读能力，AI 不需要拿到数据库账号密码，也没有机会执行 DROP 或 DELETE。
• 可以统一参数校验。在 Server 层过滤异常参数，避免 AI 生成错误 SQL。
• 可以接入审计。每次工具调用都可以记录到日志，方便追溯 AI 做了什么操作。
• 可以突破单库限制。一个 MCP Server 内部可以同时连接多个数据源，甚至做跨源聚合。

当然，如果只是临时调试、且确认账号权限可控，数据库直连连接器也很方便。但线上环境我更推荐“最小权限”原则，MCP Server 是所有方案里最容易审计的一种。

6. 实战二：一键设计稿变 APP

6.1 设计稿 MCP 的原理

“一键设计稿变 APP”并不是 AI 直接“看图片”猜界面，而是通过 MCP Server 读取设计稿的结构化数据，包括：

• 页面和 Frame 的名称、层级关系。
• 每个节点的类型、坐标、尺寸。
• 文字内容、字体、字号、颜色、间距。
• 切图资源、图标、图片链接。

拿到这些结构化数据后，大模型才能准确理解设计稿的布局和样式，再映射到前端组件（比如 uni-app、Flutter、H5 等）。

如果不用 MCP，传统流程是：前端用眼睛看设计稿，手动量间距、取色、切图，再手写界面代码。这个流程不仅慢，而且容易因为标注遗漏导致还原度不高。

使用 MCP 后，流程变成：

Workbuddy (Agent) -> 调用 design-mcp 的 list_frames 工具，拿到所有页面 -> 调用 get_frame 工具，拿到某个 Frame 的节点树 -> 调用 export_assets 工具，导出切图资源 -> 大模型根据节点树和样式数据生成前端代码

6.2 配置设计稿 MCP 连接器

以 Figma 为例，你可以使用社区提供的 figma-mcp-server，或根据 Figma API 封装自己的 MCP Server。整体思路如下：

# 文件路径：design-mcp-server/server.py（示意，工具名以实际 Server 为准） from mcp.server.fastmcp import FastMCP mcp = FastMCP("design-helper") @mcp.tool() def list_frames(page_name: str) -> list: """列出指定页面中所有 Frame 节点名称。""" # 调用设计稿平台 API，返回 Frame 名称列表 # 示例返回：[{"name": "首页", "id": "frame-home"}, {"name": "详情页", "id": "frame-detail"}] ... @mcp.tool() def get_frame(frame_name: str) -> dict: """获取指定 Frame 的节点树和样式数据。""" # 递归读取节点信息，输出 JSON 结构 ... @mcp.tool() def export_assets(frame_name: str) -> str: """导出指定 Frame 的切图资源到本地目录，返回目录路径。""" ...

这段代码里的...只是用来表示“需要根据你选择的设计稿平台 API 填充业务逻辑”。不同平台的 API 返回结构差异较大，我不建议在没拿到账号和授权信息时直接照抄。

配置连接器时，同样选择 MCP 类型：

{ "name": "figma-design-mcp", "type": "mcp", "transport": "stdio", "command": "python", "args": ["server.py"], "env": { "FIGMA_TOKEN": "这里填你的访问令牌" } }

需要注意的是，令牌属于敏感信息，不建议直接明文写在连接器配置里。如果 Workbuddy 支持读取系统环境变量或凭据管理，优先使用那类方式。

6.3 用工作流把设计稿变成 APP

连接器配置成功后，就可以在 Workbuddy 中新建一个工作流。下面是一个“设计稿 → APP 页面”的工作流定义示例：

{ "workflow": { "name": "design-to-app", "trigger": "根据首页设计稿生成 APP 首页", "steps": [ { "step": "read_design", "connector": "figma-design-mcp", "tool": "list_frames", "args": {"page_name": "APP 设计稿"} }, { "step": "extract_frame", "connector": "figma-design-mcp", "tool": "get_frame", "args": {"frame_name": "首页"} }, { "step": "export_assets", "connector": "figma-design-mcp", "tool": "export_assets", "args": {"frame_name": "首页"} }, { "step": "generate_code", "llm": "default", "prompt": "根据设计稿结构化数据生成 uni-app 首页代码，保持设计稿中的颜色、间距和层级" }, { "step": "preview", "output": "output/preview/index.html" } ] } }

这个 JSON 只是表达配置思路，具体字段以 Workbuddy 当前版本的工作流编排器为准。核心逻辑是：先取数据，再让大模型生成代码，最后输出预览。

6.4 结果验证与后续调整

工作流跑完后，你会得到：

• 一个包含生成代码的目录。
• 一个预览页面（如果配置了 preview 步骤）。

建议重点检查以下几点：

• 布局层级是否符合设计稿：容器、列表、导航是否一一对应。
• 颜色和字体字号是否与设计稿 token 一致。
• 图片资源是否正确导出并引用。
• 点击事件和跳转关系是否在生成代码中有体现（MCP 只能读取静态设计稿结构，交互逻辑通常需要模型根据经验补充，这一步尤其要人工评审）。

如果不满意，不要急着改代码。先回到设计稿，检查 Frame 命名是否清晰。比如“首页”这个 Frame 里，最好有“顶部导航”“Banner 区”“商品列表”等子节点命名。命名的语义越清晰，大模型生成的代码结构越合理。

7. 常见问题与排查思路

7.1 连接器无法使用

7.2 stdio 模式下的经典坑：日志污染协议

MCP 的 stdio 模式是依赖标准输入输出传输 JSON-RPC 消息的。如果 MCP Server 里写了print("server started")这样的日志输出，这行内容会被客户端当成协议消息去解析，导致连接失败或行为异常。

正确的做法是：

• 使用logging模块，并把日志输出到 stderr 或日志文件。
• 在环境变量里设置PYTHONUNBUFFERED=1避免缓冲问题，但不要用print打日志。

import logging logging.basicConfig(level=logging.INFO) logging.info("server started")

7.3 设计稿 MCP 读取不到数据

如果你配置好设计稿 MCP 后，发现 AI 说“没有找到 Frame”，可以从这几个方向排查：

• 访问令牌是否过期，是否具备对应设计稿的查看权限。
• 页面名称或 Frame 名称是否与设计稿里的节点一致。
• 设计稿是否使用了组件库，组件实例能否正常展开读取。
• 图片导出是否受团队权限限制。

尤其要注意：很多团队的设计稿里，Frame 名称、页面名称会带前后缀或者版本号，AI 调用工具时传入的字符串需要精确匹配。建议在工具描述里写明“先调用 list_frames 查看可用名称，再传入查询”。

7.4 排查清单

如果你遇到问题，按这个顺序排查效率最高：

1. 确认 MCP Server 能否独立运行，手动执行启动命令并观察输出。
2. 确认 Workbuddy 连接器配置里的 command、args、env 是否与手动运行一致。
3. 确认协议版本和 SDK 版本兼容，必要时打印握手日志。
4. 确认日志没有输出到 stdout。
5. 确认网络权限、令牌权限是否满足。
6. 清空 Workbuddy 连接器缓存，重新保存启用。
7. 查看 Workbuddy 日志，定位是握手失败、工具列表为空还是调用超时。

8. 最佳实践与工程建议

8.1 连接器命名规范

连接器数量一多，命名就会混乱。建议采用“类型-环境-用途”的格式：

mysql-prod-order mysql-test-user figma-design-main http-oms-internal

这样在 Workbuddy 里选择连接器时，一眼就能看出是什么系统、什么环境、干什么用。

8.2 密钥与权限管理

MCP Server 本质上是一个能替 AI 执行操作的进程，权限边界非常重要。

• 数据库 MCP：使用只读账号，禁止 DDL 和 DELETE 权限。
• 设计稿 MCP：使用最小权限令牌，只开放需要读取的团队或项目。
• HTTP MCP：对目标服务实施白名单，避免 AI 任意调用内部接口。
• 敏感配置：优先使用环境变量、凭据管理服务，不要明文写进连接器配置。

这里还要强调一个原则：哪怕只是个人开发环境，也要养成最小权限习惯。因为你不知道 AI 在某个上下文里会生成什么参数，万一它调用了一个未加限制的删除工具，结果会很糟糕。

8.3 保证 MCP Server 的稳定性

MCP Server 是一个独立进程，它可能因为依赖缺失、内存不足、网络超时而挂掉。生产环境建议：

• 使用 systemd、supervisor 或容器化方式托管长期运行的 HTTP 模式 MCP Server。
• 在 Server 入口增加异常捕获，避免未处理异常导致进程退出。
• 定期检查连接器日志，关注超时和重试次数。
• 升级 MCP SDK 前，先在一个测试连接器上验证，不要直接动生产环境。

8.4 设计稿转 APP 的落地建议

“一键设计稿变 APP”在小型项目、原型验证、内部管理后台中非常好用，但如果要上线 C 端正式产品，还是需要人工评审和手写优化。几点建议：

• 设计稿命名规范是投入产出比最高的地方。Frame 名、图层名越语义化，AI 生成的代码越接近真实结构。
• 建立样式 token 约定。颜色、间距、字号最好在设计稿里就统一，避免 AI 从多个取色节点中“猜测”主色。
• 切图资源单独管理。设计稿里的大图、图标尽量集中放在一个资源目录，MCP 导出后统一走 CDN 或本地静态资源。
• 生成代码后要过一遍“代码评审”。重点看数据请求、状态处理、边界条件，这些是 AI 最容易忽略的部分。

8.5 用连接器思维重看 AI Agent

最后想分享一个工程视角：连接器和 MCP 的流行，本质上是把 AI Agent 从“聊天机器人”推向“能操作真实系统的执行器”。当你的 Workbuddy 里接入了数据库、设计稿、接口、文档库，一个普通的需求描述就能拆成多步工具调用来完成。

这也意味着，你不再需要把每个功能都写成固定按钮。更像是搭了一套“能力插件系统”，AI 根据用户意图动态选择工具。这种架构的好处是解耦：新增一个外部系统，不需要改动主流程，只需要新增一个 MCP Server 和一个连接器即可。

所以在配置连接器时，不要只把它当成一个“填 IP、填账号”的流程。多想一想：这个 Server 暴露了哪些工具？AI 会用这些工具做什么？如果 AI 用错了参数，会造成什么后果？把这些想清楚，你的 Workbuddy 工作流才会真正变得稳定、可靠、可维护。

如果你在配置连接器时也遇到过诡异的问题，或者这篇文章里的某个示例在你本地跑出了不同的结果，欢迎在评论区和我讨论。动手把第一个 MCP 连接器跑通，你就已经迈过了 Workbuddy 入门阶段最重要的一道坎。