WorkBuddy 自定义 MCP 连接器开发实战：把企业系统接进你的 AI 助手

WorkBuddy 自定义 MCP 连接器开发实战：把企业系统接进你的 AI 助手

摘要

WorkBuddy 内置了一大批开箱即用的连接器（腾讯文档、IMA 知识库、GitHub 等），但真实工作里，你往往还想让 AI 直接连上公司的 OA、ERP、CRM 或私有知识库。好消息是：只要目标系统有 API 接口，你就能通过自定义 MCP 连接器把它接进 WorkBuddy，实现「对话即操作」。本文用 Python FastMCP 手搓一个企业内部知识库查询连接器，从环境准备、代码、注册到对话调用全流程跑通，并给出安全与踩坑清单。

目录

• 一、什么是 MCP 连接器，为什么需要它
• 二、两种开发路径：Python FastMCP 与 Node.js
• 三、环境准备
• 四、Python FastMCP 实战：企业内部知识库查询
• 五、在 WorkBuddy 注册连接器并启用
• 六、对话中直接调用
• 七、安全三铁律
• 八、常见坑复盘
• 九、总结

一、什么是 MCP 连接器，为什么需要它

所谓 MCP（Model Context Protocol，模型上下文协议）连接器，本质上就是 AI 助手和外部系统之间的一座标准化通信桥。它把企业内部 API 封装成 AI 能理解和调用的「标准工具」，让大模型不仅能「看到」业务数据，还能「操作」它们。

实际场景比比皆是：在 AI 助手里直接查 OA 审批进度、看 ERP 里的库存、调 CRM 的客户信息。没有连接器时，这些事得人肉去各个系统翻；有了 MCP 连接器，一句「帮我查一下内部知识库关于 XXX 的文档」，AI 就会自动调用你配置的服务。

可以把它理解成 AI 的 USB 接口：插上工具就能用，不用懂底层原理。

二、两种开发路径：Python FastMCP 与 Node.js

WorkBuddy 原生支持 MCP 协议，自定义连接器有两种主流开发路径：

下文以 Python FastMCP 为主线演示，因为它代码量最小、最易读。

三、环境准备

自定义连接器需要本地运行时（内置连接器不需要）。以 Python 路径为例：

# 安装 FastMCP 框架（推荐）
pip install fastmcp

# 或安装官方 MCP SDK
pip install mcp

# 安装 uvx（Python MCP Server 快速运行工具）
pip install uv

# 验证安装
python -c "from fastmcp import FastMCP; print('FastMCP OK')"
uvx –version

环境要求：Python >= 3.10，Node.js >= 18（仅 Node 路径需要）。

四、Python FastMCP 实战：企业内部知识库查询

下面用一个最小可运行的例子，演示如何把「企业内部知识库搜索 API」封装成 MCP 工具。代码里的地址、Token 用占位符，实际部署替换成你自己的配置即可。

# knowledge_server.py
from fastmcp import FastMCP
import httpx

mcp = FastMCP("enterprise-knowledge")

# 企业内部知识库配置（实际部署时替换为真实地址与令牌）
KB_API_BASE = "https://kb.example.com/api/v1"
KB_API_TOKEN = "your_api_token_here"

@mcp.tool()
def search_docs(query: str, limit: int = 5) –> str:
"""搜索企业内部知识库文档。

Args:
query: 检索关键词
limit: 返回条数上限
"""
headers = {
"Authorization": f"Bearer {KB_API_TOKEN}",
"Content-Type": "application/json",
}
resp = httpx.get(
f"{KB_API_BASE}/search",
params={"q": query, "limit": limit},
headers=headers,
timeout=10,
)
resp.raise_for_status()
return resp.text

if __name__ == "__main__":
mcp.run()

要点说明：

• 用 @mcp.tool() 装饰一个普通函数，它就变成 AI 可调用工具；
• 函数的 docstring 和三引号参数说明非常关键——WorkBuddy 靠它们理解这个工具「能干什么、要什么参数」；
• 工具内部就是你熟悉的业务 HTTP 调用，和写普通后端没区别。

五、在 WorkBuddy 注册连接器并启用

代码写好之后，要在 WorkBuddy 里把它「登记」上，AI 才能调用。

方式一：图形化添加（推荐）

打开「连接器管理」页 → 右上角「自定义连接器」→ 填写配置。本质就是写一段 mcpServers 配置：

{
"mcpServers": {
"my-knowledge-base": {
"command": "python",
"args": ["-m", "knowledge_server"],
"env": {
"API_KEY": "your-api-key"
}
}
}
}

方式二：直接编辑配置文件

• 用户级（全局生效）：~/.workbuddy/mcp.json
• 项目级（仅当前项目）：<项目>/.workbuddy/mcp.json

把上面的 JSON 写进去，保存即可生效。

关键一步：Trust 信任。 添加后，连接器管理页会出现新条目，必须点击「Trust」启用——未信任的连接器是灰点状态，AI 调不动。

六、对话中直接调用

配置并 Trust 之后，不需要任何额外操作，直接在对话里用自然语言提需求即可：

「帮我查一下内部知识库里关于『报销流程』的文档，返回前五条。」

WorkBuddy 会识别意图，自动调用你注册的 search_docs 工具，把企业内部知识库的检索结果带回到对话里。你还可以继续说「把第一条整理成周报摘要」，让 AI 基于返回数据继续干活。

七、安全三铁律

连接器是 AI 访问企业系统的通道，安全是首位：

生产环境还应启用 TLS 加密通信、对每个工具设置独立调用权限，并为连接器加上调用日志，便于排查与审计。

八、常见坑复盘

• 坑 1：连接器显示灰点。 原因通常是授权页面权限范围没勾全，或手机端没点「同意」就关了页面。解决：断开重连，授权时逐项看清。
• 坑 2：AI 说「我无法访问该文档」。 原因多为文档不在授权范围内，例如连接器只授权了「读取」你却让它「编辑」。解决：去管理页重新授权，补上对应权限。
• 坑 3：自定义 MCP 加了但用不了。 最常见是 JSON 配置格式错了（少逗号、多引号、中文引号），或 Python 环境没装 FastMCP。解决：先在终端 python -m knowledge_server 确认服务能启动，再填配置。
• 坑 4：工具没被识别。 确认函数的 docstring 写清楚了用途与参数，WorkBuddy 靠它做工具路由。

九、总结

自定义 MCP 连接器把 WorkBuddy 从「会用内置工具」升级成「能接你公司任何系统」：

• 协议标准化：MCP 让 AI 与外部系统的对接变成「填配置」而非「写对接代码」；
• 开发极简：Python FastMCP 一个 @mcp.tool() 就封装一个能力，几十行代码搞定；
• 安全可控：Trust 启用 + 权限最小化 + 环境变量托管密钥，企业也能放心用。

把企业系统接进来之后，你的 WorkBuddy 就不再只是聊天机器人，而是真正能「办事」的 AI 员工。

参考资料

• WorkBuddy 官方文档：连接器（Connector）与自定义 MCP 配置章节
• WorkBuddy 官方更新日志 5.3.x（Python 类连接器运行时支持等条目）
• MCP（Model Context Protocol）官方规范与 FastMCP 框架文档
• 社区实战教程：WorkBuddy MCP 连接器开发（OA 审批 / ERP 库存查询示例）