从 Python 函数到 MCP 工具：接入 Dify 的完整路径

Agent 能“调用 Python”不等于系统已经工程化。真正需要设计的是工具契约：模型能看见什么、参数如何校验、错误怎样返回、哪些副作用必须由人确认。MCP 为这些边界提供了统一协议。

01. 先理解三个角色

Host 是承载模型和对话的应用，Dify 属于这一层；Client 负责建立 MCP 会话、发现和调用能力；Server 暴露工具、资源和提示。对于业务动作，最常用的是 Tool：它由模型选择调用，参数使用 JSON Schema 描述。

一个好的 Tool 应该小而明确。manage_everything(action, payload) 看似灵活，却让权限、验证和审计都变得困难。更合适的拆分是 get_asset、compare_config 和 create_change_request，并让写操作显式区分于读操作。

02. 从纯函数开始

先写不依赖协议的业务函数，再加 MCP 装饰器。下面的示例只比较期望配置与实际配置，不修改任何系统：

from fastmcp import FastMCP

mcp = FastMCP("config-audit")

@mcp.tool
def compare_config(
    asset_id: str,
    expected: dict[str, str],
    actual: dict[str, str],
) -> dict:
    """Compare an asset's expected and actual configuration."""
    keys = sorted(set(expected) | set(actual))
    differences = [
        {"field": key, "expected": expected.get(key), "actual": actual.get(key)}
        for key in keys
        if expected.get(key) != actual.get(key)
    ]
    return {
        "asset_id": asset_id,
        "status": "different" if differences else "matched",
        "differences": differences,
    }

if __name__ == "__main__":
    mcp.run(transport="http", host="127.0.0.1", port=8001)

类型注解和 docstring 会影响模型看到的工具描述与参数模式。名称使用动词开头；说明要写清用途、限制和返回值，不要把关键规则藏在函数内部。

03. 先脱离 Dify 验证服务

启动前为纯函数写单元测试，覆盖配置一致、字段缺失、字段新增和空输入。启动后再检查三层：

1. 连通性：端口可访问，MCP 客户端能完成握手。
2. 协议层：工具能被列出，输入模式与预期一致。
3. 业务层：相同输入稳定得到相同结构，异常以可读错误返回。

MCP Server 可以暴露 Tools、Resources 和 Prompts；三者的控制方式不同，设计时可对照 MCP Server 规范概览。

04. 接入 Dify

在 Dify 的工具配置中添加 MCP 服务地址。FastMCP 使用 HTTP 传输时，端点通常位于：

http://127.0.0.1:8001/mcp

若 Dify 在 Docker 中，应使用宿主机可达地址，而不是容器内的 127.0.0.1。接入后确认 compare_config 出现在工具列表，再用固定参数做一次手动调用，最后才让 Agent 自主选择。

系统提示中不要只写“必要时调用工具”，应给出触发边界：当用户提供期望配置和实际配置并要求核对时调用；信息不完整时先询问；不得用它推断未提供的资产状态。

05. 上线前补齐安全边界

本地演示可以绑定环回地址；跨机器部署则必须增加身份验证、TLS、速率限制和审计日志。密钥通过环境变量或密钥管理服务注入，不写入代码、文档和返回值。

对于创建、删除、发送等有副作用的工具，再增加三道防线：最小权限、幂等键和人工确认。日志记录调用者、工具名、参数摘要、结果状态和耗时，但要脱敏凭据与个人信息。

最后准备一组对抗测试：缺少参数、超长文本、未知字段、重复请求、超时依赖和越权目标。MCP 统一了协议，却不会自动替你完成业务校验和安全设计。