做了几年的低代码和 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 调用通常是这样初始化握手客户端和 Server 建立连接交换协议版本和能力声明。获取工具列表客户端向 Server 询问“你暴露了哪些工具、参数是什么”。调用工具客户端根据大模型的意图携带参数调用指定工具。返回结果Server 执行实际操作把结果返回给客户端。模型理解结果大模型把结构化的返回结果组织成自然语言回答给用户。从效果上看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 连接器本质针对特定系统的集成组件基于统一协议的工具调用通道接入范围通常只针对一类系统任何实现了 MCP Server 的外部能力协议多样化随系统不同而不同统一的 JSON-RPC 2.0 协议扩展性新增系统需开发新连接器新增系统只需配置 MCP Server灵活性参数相对固定工具列表和参数可动态发现适用场景数据库直连、固定 API 集成AI Agent 需要动态调用多种外部能力注意这里有一个很容易踩的误区不是所有连接器都必须改为 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 安装 WorkbuddyWorkbuddy 提供桌面端和网页端。桌面端通常在官网下载安装包网页端直接在浏览器打开即可。本文以桌面端为参考环境重点讲清配置思路具体菜单位置以你安装的版本为准。安装完成后建议先完成基础登录和偏好设置。如果你是第一次接触可以先在空工作区里试一下默认的对话功能确认 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 配置方式不同但整体链路是相通的设计稿平台提供 APIMCP Server 封装 APIWorkbuddy 调用 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字段即可。PYTHONUNBUFFERED1是为了避免 Python 缓冲日志导致 MCP 消息延迟。保存并启用这个连接器后Workbuddy 会自动启动server.py并完成 MCP 握手。你可以在连接器详情页看到“已连接”状态以及该 Server 暴露的工具列表。5.4 运行与验证回到 Workbuddy 的对话界面发送查询已支付订单数量正常情况下AI 会识别出需要调用get_order_count工具并传入statusPAID。返回结果应该是 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. 实战二一键设计稿变 APP6.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 连接器无法使用问题现象常见原因解决思路连接器一直显示未连接MCP Server 进程启动失败手动执行 command args 看报错首次能做数据库查询重启后连不上stdio 模式进程没有随 Workbuddy 启动检查连接器启动命令改用可执行文件绝对路径工具列表为空Server 没有注册任何工具检查代码中是否有mcp.tool()确认文件保存连接器配置无法保存参数格式不正确按 JSON 格式检查字段注意缺少逗号或多余引号需要联网的 MCP Server 超时网络权限受限检查代理、防火墙、白名单调用工具返回乱码文件编码或环境变量编码不对统一使用 UTF-8设置PYTHONUTF817.2 stdio 模式下的经典坑日志污染协议MCP 的 stdio 模式是依赖标准输入输出传输 JSON-RPC 消息的。如果 MCP Server 里写了print(server started)这样的日志输出这行内容会被客户端当成协议消息去解析导致连接失败或行为异常。正确的做法是使用logging模块并把日志输出到 stderr 或日志文件。在环境变量里设置PYTHONUNBUFFERED1避免缓冲问题但不要用print打日志。import logging logging.basicConfig(levellogging.INFO) logging.info(server started)7.3 设计稿 MCP 读取不到数据如果你配置好设计稿 MCP 后发现 AI 说“没有找到 Frame”可以从这几个方向排查访问令牌是否过期是否具备对应设计稿的查看权限。页面名称或 Frame 名称是否与设计稿里的节点一致。设计稿是否使用了组件库组件实例能否正常展开读取。图片导出是否受团队权限限制。尤其要注意很多团队的设计稿里Frame 名称、页面名称会带前后缀或者版本号AI 调用工具时传入的字符串需要精确匹配。建议在工具描述里写明“先调用 list_frames 查看可用名称再传入查询”。7.4 排查清单如果你遇到问题按这个顺序排查效率最高确认 MCP Server 能否独立运行手动执行启动命令并观察输出。确认 Workbuddy 连接器配置里的 command、args、env 是否与手动运行一致。确认协议版本和 SDK 版本兼容必要时打印握手日志。确认日志没有输出到 stdout。确认网络权限、令牌权限是否满足。清空 Workbuddy 连接器缓存重新保存启用。查看 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 入门阶段最重要的一道坎。
连接器与MCP是什么关系？从数据库到设计稿转APP的实战指南
做了几年的低代码和 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 调用通常是这样初始化握手客户端和 Server 建立连接交换协议版本和能力声明。获取工具列表客户端向 Server 询问“你暴露了哪些工具、参数是什么”。调用工具客户端根据大模型的意图携带参数调用指定工具。返回结果Server 执行实际操作把结果返回给客户端。模型理解结果大模型把结构化的返回结果组织成自然语言回答给用户。从效果上看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 连接器本质针对特定系统的集成组件基于统一协议的工具调用通道接入范围通常只针对一类系统任何实现了 MCP Server 的外部能力协议多样化随系统不同而不同统一的 JSON-RPC 2.0 协议扩展性新增系统需开发新连接器新增系统只需配置 MCP Server灵活性参数相对固定工具列表和参数可动态发现适用场景数据库直连、固定 API 集成AI Agent 需要动态调用多种外部能力注意这里有一个很容易踩的误区不是所有连接器都必须改为 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 安装 WorkbuddyWorkbuddy 提供桌面端和网页端。桌面端通常在官网下载安装包网页端直接在浏览器打开即可。本文以桌面端为参考环境重点讲清配置思路具体菜单位置以你安装的版本为准。安装完成后建议先完成基础登录和偏好设置。如果你是第一次接触可以先在空工作区里试一下默认的对话功能确认 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 配置方式不同但整体链路是相通的设计稿平台提供 APIMCP Server 封装 APIWorkbuddy 调用 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字段即可。PYTHONUNBUFFERED1是为了避免 Python 缓冲日志导致 MCP 消息延迟。保存并启用这个连接器后Workbuddy 会自动启动server.py并完成 MCP 握手。你可以在连接器详情页看到“已连接”状态以及该 Server 暴露的工具列表。5.4 运行与验证回到 Workbuddy 的对话界面发送查询已支付订单数量正常情况下AI 会识别出需要调用get_order_count工具并传入statusPAID。返回结果应该是 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. 实战二一键设计稿变 APP6.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 连接器无法使用问题现象常见原因解决思路连接器一直显示未连接MCP Server 进程启动失败手动执行 command args 看报错首次能做数据库查询重启后连不上stdio 模式进程没有随 Workbuddy 启动检查连接器启动命令改用可执行文件绝对路径工具列表为空Server 没有注册任何工具检查代码中是否有mcp.tool()确认文件保存连接器配置无法保存参数格式不正确按 JSON 格式检查字段注意缺少逗号或多余引号需要联网的 MCP Server 超时网络权限受限检查代理、防火墙、白名单调用工具返回乱码文件编码或环境变量编码不对统一使用 UTF-8设置PYTHONUTF817.2 stdio 模式下的经典坑日志污染协议MCP 的 stdio 模式是依赖标准输入输出传输 JSON-RPC 消息的。如果 MCP Server 里写了print(server started)这样的日志输出这行内容会被客户端当成协议消息去解析导致连接失败或行为异常。正确的做法是使用logging模块并把日志输出到 stderr 或日志文件。在环境变量里设置PYTHONUNBUFFERED1避免缓冲问题但不要用print打日志。import logging logging.basicConfig(levellogging.INFO) logging.info(server started)7.3 设计稿 MCP 读取不到数据如果你配置好设计稿 MCP 后发现 AI 说“没有找到 Frame”可以从这几个方向排查访问令牌是否过期是否具备对应设计稿的查看权限。页面名称或 Frame 名称是否与设计稿里的节点一致。设计稿是否使用了组件库组件实例能否正常展开读取。图片导出是否受团队权限限制。尤其要注意很多团队的设计稿里Frame 名称、页面名称会带前后缀或者版本号AI 调用工具时传入的字符串需要精确匹配。建议在工具描述里写明“先调用 list_frames 查看可用名称再传入查询”。7.4 排查清单如果你遇到问题按这个顺序排查效率最高确认 MCP Server 能否独立运行手动执行启动命令并观察输出。确认 Workbuddy 连接器配置里的 command、args、env 是否与手动运行一致。确认协议版本和 SDK 版本兼容必要时打印握手日志。确认日志没有输出到 stdout。确认网络权限、令牌权限是否满足。清空 Workbuddy 连接器缓存重新保存启用。查看 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 入门阶段最重要的一道坎。
