摘要

MCP（ModelContextProtocol，模型上下文协议）可以理解为AIAgent的USB扩展接口，能够把外部HTTPAPI封装成本地工具，让WorkBuddy通过自然语言直接调用第三方接口。很多商业开放API不只是简单Token鉴权，需要运行时动态计算签名（MD5、SHA），WorkBuddy内置HTTP节点无法完成动态签名逻辑。本文以企业模糊搜索API为案例，演示如何基于FastMCP编写MCPServer、处理自定义MD5签名、本地调试、接入WorkBuddy，同时解决IP白名单、密钥安全、配置等实际问题。

MCP服务运行在本机，网络出口为你的电脑公网IP，密钥保存在本地，不会上传到第三方平台，适配接口服务商IP白名单限制。

一、需求与接口分析

本次案例接口：五度易链-企业模糊搜索API

五度易链API

接口地址https://gateway.qyxqk.com/wdyl/openapi/fuzzy_query/ ​

· 请求方式：POST，返回JSON

· 鉴权规则（重点）：请求头携带APPID、TIMESTAMP、SIGN

· TIMESTAMP：时间字符串，格式yyyy‑MM‑dd HH:mm:ss

· SIGN签名算法：MD5(APPID + TIMESTAMP + APP_SECRET + 拼接STR)，输出32位小写md5

· 拼接STR：业务请求JSON的key按照字母升序，取出value直接拼接，无任何分隔符

· 业务入参：key搜索关键词，page_index页码，page_size每页条数

· 返回字段：企业名称、曾用名、注册资本、成立日期、法人、经营状态、注册地址、经营范围等工商信息。

痛点：WorkBuddy自带HTTP连接器只能写固定Header，无法实时动态计算MD5签名，所以自建MCPServer，在本地Python代码内部完成签名计算和HTTP调用。

二、项目初始化与依赖安装

新建项目文件夹，打开终端执行安装命令：

pip install "mcp[cli]" python‑dotenv requests

mcp[cli]：FastMCP 核心 SDK，提供 MCP 服务能力以及调试工具mcp dev

python‑dotenv：读取本地.env环境变量文件，避免密钥硬编码到代码

requests：HTTP 请求库，调用第三方 API

在项目目录新建两个文件：

enterprise_mcp.py：MCP 服务主程序

.env：密钥配置文件，切记不要上传到 Git，不要分享给其他人

.env文件内容，填入你自己接口凭证

APPID=你的接口APPID

APP_SECRET=你的接口密钥Secret

API_URL=https://gateway.qyxqk.com/wdyl/openapi/fuzzy_query/

三、完整 MCP Server 代码实现 enterprise_mcp.py

import os
import hashlib
import time
import json
import requests
from dotenv import load_dotenv
from mcp.server.fastmcp import FastMCP

# 加载本地.env环境变量
load_dotenv()
APPID = os.getenv("APPID")
APP_SECRET = os.getenv("APP_SECRET")
API_URL = os.getenv("API_URL")

# 初始化MCP服务，服务名称enterprise‑search
mcp = FastMCP("enterprise‑search")

@mcp.tool()
def fuzzy_search_enterprise(key: str, page_index: int = 1, page_size: int = 20) -> dict:
    """
    企业模糊搜索工具，WorkBuddy可通过自然语言调用
    支持企业名称、注册地址、经营范围模糊搜索；统一社会信用代码、注册号精准查询
    Args:
        key: 搜索关键词，企业名称/注册地址/经营范围/统一社会信用代码/注册号
        page_index: 页码索引，默认第1页
        page_size: 每页返回条数，默认20，建议不超过50
    Returns:
        dict: 返回接口原始JSON，包含code、msg、total总数、企业列表data
    """
    # 业务请求体
    body_dict = {
        "key": key,
        "page_index": page_index,
        "page_size": page_size
    }
    # 生成接口要求格式的时间戳字符串 yyyy‑MM‑dd HH:mm:ss
    TIMESTAMP = time.strftime("%Y‑%m‑%d %H:%M:%S", time.localtime())

    # 【核心签名逻辑】业务参数key按字母升序，拼接所有value，无分隔符
    sorted_items = sorted(body_dict.items(), key=lambda x: x[0])
    concat_str = "".join(str(v) for _, v in sorted_items)

    # 组装签名原始串，计算32位小写MD5
    sign_source = APPID + TIMESTAMP + APP_SECRET + concat_str
    SIGN = hashlib.md5(sign_source.encode("utf‑8")).hexdigest().lower()

    headers = {
        "APPID": APPID,
        "SIGN": SIGN,
        "TIMESTAMP": TIMESTAMP,
        "Content‑Type": "application/json"
    }
    try:
        resp = requests.post(API_URL, headers=headers, json=body_dict, timeout=15)
        resp.raise_for_status()
        return resp.json()
    except requests.exceptions.RequestException as e:
        return {"error": f"接口调用异常：{str(e)}"}


if __name__ == "__main__":
    # stdio标准输入输出模式，WorkBuddy通过子进程调用此MCP服务
    mcp.run(transport="stdio")

关键点说明

@mcp.tool()装饰器：把普通 Python 函数注册成 MCP 工具，函数文档字符串会被 WorkBuddy 读取，用于 AI 自动识别入参、理解工具用途。

transport="stdio"：标准 IO 通信模式，WorkBuddy 本地 MCP 使用该模式，不要用 http 模式。

所有密钥从.env读取，禁止硬编码写死在代码中，防止密钥泄露。

完整复现接口文档签名规则：参数 key 升序拼接 value、时间字符串格式、md5 小写输出。

四、本地调试 MCP 服务

FastMCP 自带调试工具，可以在接入 WorkBuddy 之前验证工具是否正常工作。
终端执行命令。

mcp dev enterprise_mcp.py

自动打开本地调试网页 UI，你可以直接调用工具fuzzy_search_enterprise，输入关键词如“宇树科技”测试。

常见报错：

返回 401：签名错误、APPID/Secret 错误、时间格式不对、本机 IP 未加入服务商白名单

读取不到密钥：确认.env文件和 py 文件放在同一个目录

调试确认接口返回数据正常之后，关闭调试窗口。

五、WorkBuddy 配置 MCP 服务

5.1 找到正确的 mcp.json 配置文件路径

注意不要编辑.mcp.json（带点前缀，系统自动生成，修改会被覆盖）

系统	mcp.json 路径（用户级全局配置）
Windows	%USERPROFILE%\.workbuddy\mcp.json
Mac / Linux	~/.workbuddy/mcp.json

如果文件夹内没有mcp.json，手动新建该 JSON 文件。

5.2 编写 mcp.json 配置

command、args 必须填写绝对路径，不能写相对路径！

command 是你的 python 解释器完整路径；args 数组第一个参数是enterprise_mcp.py完整文件路径。

Windows 示例配置：

{
  "mcpServers": {
    "enterprise‑search": {
      "command": "C:/Python311/python.exe",
      "args": [
        "D:/mcp_project/enterprise_mcp.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "description": "企业模糊搜索MCP工具，查询工商企业信息"
    }
  }
}

Mac/Linux 示例：

{
  "mcpServers": {
    "enterprise‑search": {
      "command": "/usr/bin/python3",
      "args": [
        "/Users/xxx/mcp_project/enterprise_mcp.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "description": "企业模糊搜索MCP工具，查询工商企业信息"
    }
  }
}

5.3 WorkBuddy 界面操作步骤

保存mcp.json文件，完全重启 WorkBuddy 客户端。

打开侧边栏【连接器】→【自定义连接器】，可以看到enterprise‑search服务。

启用 MCP 服务（未信任不会被 Agent 调用），状态指示灯变为绿色代表加载成功。

如果指示灯红色：检查 python 路径、脚本路径是否为绝对路径，终端手动运行python enterprise_mcp.py看是否报错。

六、使用效果

直接在 WorkBuddy 对话窗口用自然语言提问，Agent 会自动识别、调用 MCP 工具：

帮我搜索关键词“宇树科技”的企业，第一页，返回 10 条数据

内部自动调用fuzzy_search_enterprise(key="宇树科技",page_index=1,page_size=10)拿到接口 JSON，整理成可读文本输出。

七、重要安全提示

1、.env文件严禁分享、上传代码仓库，Secret 泄露会导致他人消耗你的接口配额。

2、调用第三方 API 遵循服务商 QPS 限流，不要高频批量调用。

3、不要随意导入来源不明的 MCP 脚本，本地 MCP 拥有本机进程权限。

八、常见问题排查清单

1. WorkBuddy 看不到 MCP 服务

是否修改错文件，确认编辑的是不带点前缀的 mcp.json。

command、args 全部使用绝对路径，不要写python、./xxx.py相对路径。

修改配置后必须完全重启 WorkBuddy，刷新会话无效。

2. MCP 状态绿灯，但对话不会调用工具

确认 MCP 服务已经勾选【信任】。

函数内部文档字符串"""说明"""不要删除，WorkBuddy 靠这段描述理解工具能力。

重启对话会话。

3. 接口返回 401 网关验证失败（鉴权失败）

核对TIMESTAMP时间格式，必须yyyy‑MM‑dd HH:mm:ss字符串，不能是时间戳数字。

签名拼接逻辑：业务参数 key 严格按字母升序，value 直接拼接无分隔符，md5 输出小写。

APPID、APP_SECRET 复制无多余空格换行。

确认本机公网 IP 已经添加到接口服务商 IP 白名单，这个是高频踩坑点。

4. mcp dev 调试正常，WorkBuddy 调用报错

大概率是环境读取差异：WorkBuddy 启动子进程时，工作目录不是脚本所在目录，.env无法被加载。

解决方案：可以把环境变量写到 mcp.json 的env节点，但是不建议存放 Secret；或者在代码中指定 dotenv 加载.env的绝对路径。

九、扩展：如何把其他自定义 API 封装 MCP

通用步骤总结：

分析接口鉴权逻辑（Token / MD5 / SHA 签名）。

使用 FastMCP 编写 MCP Server，@mcp.tool()装饰器注册工具，内部完成签名计算和 HTTP 请求。

本地使用mcp dev调试，保证接口调用正常。

编写mcp.json，填写 python 解释器、脚本绝对路径。

WorkBuddy 重启、信任 MCP 服务，自然语言调用。

如果你要封装其他 API，只需要修改工具函数内部的 HTTP 请求、签名逻辑，MCP 框架部分代码可以复用。

总结

针对需要动态计算签名的商业第三方 API，WorkBuddy 官方内置连接器能力有限，自建本地 MCP Server 是最优方案。MCP 运行在本机，密钥保存在本地，网络出口为本机 IP，完美适配大部分企业开放 API 的 IP 白名单安全策略。通过 FastMCP 可以快速把任意 HTTP 接口变成 AI Agent 可调用工具，极大扩展 WorkBuddy 能力边界。

本文案例代码仅供学习，使用第三方 API 请遵守服务商协议与合规要求。