dify-knowledge-mcp-plus

v1.4.1

Published

8 days ago

MCP server for Dify knowledge base integration

0High
0Medium
0Low

yangxd66

dify mcp nodejs knowledge-base model-context-protocol

Dify Knowledge MCP Server

这是一个基于Model Context Protocol (MCP)的服务器,用于访问Dify知识库。它可以让AI助手(如Cursor)直接查询你的Dify知识库内容。

功能特性

🔍 查询Dify知识库内容
📊 支持多种搜索方法(语义搜索、全文搜索、混合搜索)
🔄 支持自循环检索流程(初始检索 -> 分析缺口 -> 补充检索 -> 整合输出)
🎯 支持重新排序结果
⚙️ 灵活的配置选项
🛠️ 标准MCP协议支持

安全警告

⚠️ 重要:保护你的API密钥

永远不要在代码中硬编码API密钥
不要将包含敏感信息的.env文件提交到版本控制
使用.env文件或环境变量来存储敏感配置
定期更新你的API密钥

快速开始

1. 一条命令安装到 Codex CLI 全局配置

如果你希望装完后所有 Codex CLI 会话都自动带上这个 MCP，可以直接执行：

npx -y dify-knowledge-mcp-plus install --api-url="http://ai.suixingpay.com/v1/datasets/YOUR_DATASET_ID/retrieve" --api-key="your_actual_api_key" --qwen-api-key="your_qwen_api_key"

这条命令会：

把 MCP 配置写入 ~/.codex/config.toml
自动注册一个全局可用的 dify-knowledge MCP server
启动命令固定为 npx -y dify-knowledge-mcp-plus
如果已有配置文件，会先备份到 ~/.codex/config.toml.bak

安装完成后，重启 Codex CLI 即可生效。

如果你不想把密钥留在 shell history 里，也可以先设置环境变量，再执行：

$env:DIFY_API_URL="http://ai.suixingpay.com/v1/datasets/YOUR_DATASET_ID/retrieve"; $env:DIFY_API_KEY="your_actual_api_key"; $env:QWEN_API_KEY="your_qwen_api_key"; npx -y dify-knowledge-mcp-plus install

2. 一条命令接入其他 MCP 客户端

当包发布到 npm 后，可以直接在 MCP 客户端里使用 npx 启动，无需先手动克隆仓库和安装依赖：

{
  "mcpServers": {
    "dify-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "dify-knowledge-mcp-plus"
      ],
      "env": {
        "DIFY_API_URL": "http://ai.suixingpay.com/v1/datasets/YOUR_DATASET_ID/retrieve",
        "DIFY_API_KEY": "your_actual_api_key",
        "QWEN_API_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
        "QWEN_API_KEY": "your_qwen_api_key",
        "QWEN_MODEL": "qwen-plus"
      }
    }
  }
}

如果你还没发到 npm，也可以在仓库根目录先做一次本地全局安装：

npm install -g .

安装后可直接执行：

dify-knowledge-mcp-plus --help

3. 配置API信息

你需要提供以下配置:

Dataset ID: 你的Dify知识库ID
API Key: 你的Dify API密钥
Qwen API Key: 用于“分析缺口”阶段的千问模型密钥(可选,但推荐)

4. 配置API密钥

方式1:使用.env文件(推荐)

# 复制配置模板
cp env.example .env

# 编辑.env文件,填入你的真实配置
# DIFY_API_URL=https://api.dify.ai/v1/datasets/YOUR_DATASET_ID/retrieve
# DIFY_API_KEY=your_actual_api_key
# QWEN_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
# QWEN_API_KEY=your_qwen_api_key
# QWEN_MODEL=qwen-plus

方式2:环境变量

# Linux/Mac
export DIFY_API_URL="https://api.dify.ai/v1/datasets/YOUR_DATASET_ID/retrieve"
export DIFY_API_KEY="your_actual_api_key"
export QWEN_API_URL="https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"
export QWEN_API_KEY="your_qwen_api_key"
export QWEN_MODEL="qwen-plus"

# Windows
set DIFY_API_URL=https://api.dify.ai/v1/datasets/YOUR_DATASET_ID/retrieve
set DIFY_API_KEY=your_actual_api_key
set QWEN_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
set QWEN_API_KEY=your_qwen_api_key
set QWEN_MODEL=qwen-plus

方式3:命令行参数

dify-knowledge-mcp-plus --api-url="https://api.dify.ai/v1/datasets/YOUR_DATASET_ID/retrieve" --api-key="your_actual_api_key"

5. 运行服务器

dify-knowledge-mcp-plus

在Cursor中使用

1. 配置MCP服务器

在Cursor中,你需要配置MCP服务器。创建或编辑你的MCP配置文件:

{
  "mcpServers": {
    "dify-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "dify-knowledge-mcp-plus"
      ],
      "env": {
        "DIFY_API_URL": "https://api.dify.ai/v1/datasets/YOUR_DATASET_ID/retrieve",
        "DIFY_API_KEY": "your_actual_api_key",
        "QWEN_API_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
        "QWEN_API_KEY": "your_qwen_api_key",
        "QWEN_MODEL": "qwen-plus"
      }
    }
  }
}

注意: 替换上面的占位符为你的实际值:

YOUR_DATASET_ID: 你的Dify知识库ID
your_actual_api_key: 你的Dify API密钥

如果你希望继续使用源码路径方式，也可以保留旧配置:

{
  "mcpServers": {
    "dify-knowledge": {
      "command": "node",
      "args": [
        "/path/to/your/dify-knowledge-mcp-server/index.js"
      ]
    }
  }
}

2. 可用的工具函数

配置完成后,Cursor可以使用以下工具:

`query_dify_knowledge`

查询Dify知识库内容

参数:

query (必需): 搜索查询词
top_k (可选): 最终返回结果数量,默认为3
search_method (可选): 首轮搜索方法,可选值:
- semantic_search: 语义搜索
- full_text_search: 全文搜索
- hybrid_search: 混合搜索(默认)
reranking_enable (可选): 启用重新排序,默认为true
iterative_search_enable (可选): 是否启用自循环检索,默认为true
llm_gap_analysis_enable (可选): 是否启用千问参与“分析缺口”,默认为true
qwen_model (可选): 覆盖默认千问模型
supplemental_top_k (可选): 每次补充检索返回的结果数量,默认与 top_k 一致

自循环检索流程:

初始检索
分析缺口
补充检索
整合输出

示例:

请查询关于"产品介绍"的相关内容

`get_dify_config`

检查当前Dify API配置状态

使用示例

在Cursor中的对话示例

用户: 请帮我查询知识库中关于"用户手册"的内容

AI助手: 我来为你查询Dify知识库中关于"用户手册"的内容...
[调用query_dify_knowledge工具]

找到了3个相关的知识条目:

1. (Score: 0.95)
用户手册第一章介绍了产品的基本功能和使用方法...

2. (Score: 0.87)
用户手册第二章详细说明了高级功能的配置步骤...

3. (Score: 0.82)
用户手册常见问题解答部分提供了问题解决方案...

配置说明

API URL格式

https://api.dify.ai/v1/datasets/{dataset_id}/retrieve

支持的搜索方法

semantic_search: 基于语义理解的搜索
full_text_search: 传统的全文搜索
hybrid_search: 结合语义和全文搜索的混合模式

重新排序

启用重新排序可以提高搜索结果的相关性,但可能会增加响应时间。

自循环检索

启用 iterative_search_enable 后,服务会先执行首轮检索,然后进入“分析缺口”阶段。

如果配置了 QWEN_API_KEY 且 llm_gap_analysis_enable=true, 则优先使用千问分析首轮结果覆盖度,生成补充检索词和建议检索方式
如果千问不可用或返回异常, 会自动回退到启发式规则分析,不会中断主流程
最后自动执行补充检索、去重、排序并输出整合结果

故障排除

常见问题

"Please configure DIFY_API_URL and DIFY_API_KEY"
- 确保API URL和API Key已正确配置
- 检查Dataset ID是否正确
"Failed to retrieve knowledge from Dify"
- 检查API Key是否有效
- 确认Dataset ID是否存在
- 验证网络连接
连接超时
- 检查网络连接
- 确认Dify API服务是否可访问

测试配置

运行以下命令测试配置:

# 测试配置状态
dify-knowledge-mcp-plus

如果看到"Ready to query knowledge base!"消息,说明配置正确。

清理敏感信息

如果你之前在配置文件中暴露了API密钥,请立即:

更新Cursor配置文件 (通常在 ~/.cursor/mcp.json 或类似路径)
删除或更换暴露的API密钥
检查版本控制历史 确保没有提交敏感信息
使用新的配置方法 通过.env文件或环境变量

开发信息

协议: Model Context Protocol (MCP)
传输方式: Standard I/O
API版本: Dify API v1
Node.js版本: 支持ES模块的版本

许可证

MIT License