当前位置：首页 > news >正文

Dify MCP 接入踩坑实录：notifications/initialized 的终极解法

news 2026/6/15 8:33:54

处理下面文章的MD错误格式，返回整个MD文章

关键词：Dify · MCP · JSON-RPC · notifications/initialized · invalid_param
结论先行：Dify 的 MCP 实现与 JSON-RPC / MCP 规范存在关键差异

一、问题背景

在将一个 MCP Server（HTTP 方式）接入 Dify MCP Tool 时，服务端实现了：

initialize
notifications/initialized
tools/list
tools/call

但在 Dify 初始化阶段 cleanup 时，持续报错：

{"code": "invalid_param","message": "Error during cleanup: ... validation errors for JSONRPCMessage","status": 400
}

错误会随着返回内容变化而变化，极难定位。

二、问题现象汇总（所有失败尝试）

在 notifications/initialized 阶段，以下返回方式全部失败：

❌ 1. 不返回内容（204 No Content）

204 No Content
Content-Type: text/html

失败原因：

Flask 默认返回 text/html
Dify cleanup 阶段强制校验 Content-Type

❌ 2. 返回空 JSON

{}

失败原因：

虽然是 object
但不符合任何 JSON-RPC Message 类型

❌ 3. 返回 null

null

失败原因：

null → NoneType
Pydantic 要求 object

❌ 4. 返回空字符串

<empty body>

失败原因：

JSON 解析直接 EOF
报 Invalid JSON: EOF while parsing

❌ 5. 返回 JSON-RPC Response（伪造）

{"jsonrpc": "2.0","id": 0,"result": {}
}

失败原因：

Dify cleanup 阶段明确不允许 Response
即使格式完全正确也会报错

三、关键发现：Dify 的真实校验逻辑

通过多轮错误信息反推，Dify 在 cleanup 阶段做了如下逻辑：

parsed = json.loads(response_body)
JSONRPCMessage.model_validate(parsed)

其中 JSONRPCMessage 是一个 Union：

JSONRPCRequest
JSONRPCNotification
JSONRPCResponse
JSONRPCError

结论：
Dify 要求：每一个 HTTP 响应体都必须是一个合法的 JSON-RPC Message

四、最终正确答案（唯一解）

✅ notifications/initialized 必须返回「Notification 本身」

即：返回一个 JSON-RPC Notification 对象，而不是 Response，也不是空

✅ 正确返回内容

{"jsonrpc": "2.0","method": "notifications/initialized"
}

满足：

✔ 是合法 JSON
✔ 是 object
✔ 能匹配 JSONRPCNotification
✔ 没有 id（符合 Notification 语义）
✔ cleanup 阶段不会当成 Response

五、Flask 最终正确代码示例

from flask import Response as FlaskResponse
import jsonif method == 'notifications/initialized':logger.info("MCP Notification initialized received")response_data = {"jsonrpc": "2.0","method": "notifications/initialized"}return FlaskResponse(response=json.dumps(response_data),status=200,content_type="application/json")

⚠️ 注意事项：

必须有 jsonrpc
必须有 method
绝对不能有 id
Content-Type 必须是 application/json

六、最终可用的完整 MCP 交互时序

initialize
→ 200 application/json
→ JSONRPCResponsenotifications/initialized
→ 200 application/json
→ JSONRPCNotificationtools/list
→ 200 application/json
→ JSONRPCResponsetools/call
→ 200 application/json
→ JSONRPCResponse

至此，Dify MCP Tool 可以稳定进入可用状态。