dify-knowledge-mcp-server

Mocha-s/dify-knowledge-mcp-server

3.3

If you are the rightful owner of dify-knowledge-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Dify Knowledge Base MCP Server v2.0 is an enterprise-grade server built on the official TypeScript SDK for integrating Dify knowledge bases, fully compliant with the MCP 2025-06-18 standard.

Tools
5
Resources
0
Prompts
0

Dify 知识库 MCP 服务器 v2.0

MCP Compatible TypeScript Official SDK Docker

基于官方 TypeScript SDK 构建的企业级 MCP 服务器，用于 Dify 知识库集成，遵循 MCP 2025-06-18 标准。

🚀 核心特性

  • 官方 SDK 集成：基于 @modelcontextprotocol/sdk v1.17.4 构建
  • 完全兼容 MCP 2025-06-18：标准 JSON-RPC 2.0 和工具结果格式
  • Dify 知识库访问：支持知识库和文档的完整 CRUD 操作
  • 多传输协议支持：stdio、HTTP（流式 HTTP 协议）
  • 类型安全：完整 TypeScript 实现，集成 Zod 模式验证
  • 生产就绪：全面的错误处理和日志记录
  • Docker 部署支持：开箱即用的容器化部署方案

📦 快速开始

方式一：Docker 部署（推荐）

# 1. 克隆项目
git clone <repository-url>
cd dify-knowledge-mcp-server

# 2. 设置环境变量
export DIFY_API_KEY="your-dify-api-key"

# 3. 启动服务
docker-compose up -d

# 4. 查看服务状态
docker-compose logs -f

服务将在 http://localhost:3000 启动，访问 http://localhost:3000/health 检查服务状态。

方式二：本地开发

# 安装依赖
npm install

# 构建项目
npm run build

# 启动开发服务器
npm run dev

🔧 环境配置

创建 .env 文件或设置以下环境变量：

# 必需配置
export DIFY_API_KEY="your-dify-api-key"              # Dify API 密钥

# 可选配置
export DIFY_API_BASE_URL="https://api.dify.ai/v1"    # Dify API 端点（默认）
export DIFY_TIMEOUT="30000"                           # API 超时时间（毫秒）
export DIFY_MAX_RETRIES="3"                          # 最大重试次数

# 服务器配置
export MCP_HOST="127.0.0.1"                          # 服务器主机
export MCP_PORT="3000"                               # 服务器端口
export MCP_LOG_LEVEL="INFO"                          # 日志级别
export MCP_ALLOWED_ORIGINS="*"                       # CORS 来源

💡 提示：可以复制 .env.example 文件并修改其中的值。

🎯 可用工具

知识库管理

dify_list_knowledge_bases

列出所有可用的知识库

  • 参数：limit（可选）- 返回结果的最大数量
  • 返回：包含元数据的知识库数组
dify_show_knowledge_base

获取特定知识库的详细信息

  • 参数：knowledge_base_id（必需）- 知识库 ID
  • 返回：知识库详情和统计信息

文档管理

dify_list_documents_bases

列出知识库中的文档

  • 参数：
    • knowledge_base_id（必需）- 知识库 ID
    • limit（可选）- 返回结果的最大数量
  • 返回：包含元数据的文档数组
dify_show_document_details

获取特定文档的详细信息

  • 参数：
    • knowledge_base_id（必需）- 知识库 ID
    • document_id（必需）- 文档 ID
  • 返回：文档详情和统计信息

文档分段管理

dify_get_document_segments

查询文档分段列表

  • 参数：
    • dataset_id（必需）- 知识库 ID
    • document_id（必需）- 文档 ID
    • keyword（可选）- 搜索关键词
    • status（可选）- 分段状态（如 "completed"）
    • page（可选）- 页码
    • limit（可选）- 每页返回数量（默认20，最大100）
  • 返回：文档分段列表及分页信息
dify_get_child_segments

查询文档子分段列表

  • 参数：
    • dataset_id（必需）- 知识库 ID
    • document_id（必需）- 文档 ID
    • segment_id（必需）- 分段 ID
    • keyword（可选）- 搜索关键词
    • page（可选）- 页码（默认1）
    • limit（可选）- 每页返回数量（默认20，最大100）
  • 返回：子分段列表及分页信息
dify_get_segment_detail

查询文档分段详细信息

  • 参数：
    • dataset_id（必需）- 知识库 ID
    • document_id（必需）- 文档 ID
    • segment_id（必需）- 分段 ID
  • 返回：分段详细信息，包含内容、关键词、子分段等

搜索和检索

dify_search_knowledge_base

在知识库中进行智能搜索，支持多种搜索方法和高级参数

  • 参数：
    • knowledge_base_id（必需）- 知识库 ID
    • query（必需）- 搜索查询内容
    • top_k（可选）- 返回结果数量（默认3）
    • search_method（可选）- 搜索方法：
      • semantic_search（默认）- 语义搜索
      • keyword_search - 关键词搜索
      • full_text_search - 全文搜索
      • hybrid_search - 混合搜索
    • score_threshold（可选）- 最小相关性分数阈值
    • score_threshold_enabled（可选）- 是否启用分数过滤
    • reranking_enable（可选）- 是否启用重排序（默认true）
  • 返回：包含分段内容、相关性分数、关键词、位置等详细信息的搜索结果

🚦 使用方式

stdio 传输（默认）

# 使用 stdio 传输启动服务器
npm start

# 或直接使用 Node.js
node dist/index.js

HTTP 传输

# 在默认主机启动 HTTP 服务器（127.0.0.1:3000）
npm run start:http

# 启动外部访问服务器（0.0.0.0:8080）
npm run start:http:external

# 或使用 Node.js 直接启动并自定义参数
node dist/index.js --http --host 0.0.0.0 --port 8080

# 使用 npm 传递参数的替代方法
npm start -- --http --host 0.0.0.0 --port 8080

Docker 部署

# 使用 Docker Compose（推荐）
docker-compose up -d

# 或手动构建和运行
docker build -t dify-mcp-server .
docker run -d \
  -p 3000:3000 \
  -e DIFY_API_KEY=your-api-key \
  -v $(pwd)/logs:/app/logs \
  --name dify-mcp-server \
  dify-mcp-server

详细的 Docker 部署说明请参考 。

MCP 客户端集成示例

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({
  name: 'dify-knowledge-client',
  version: '1.0.0'
});

const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js']
});

await client.connect(transport);

// 列出知识库
const knowledgeBases = await client.callTool({
  name: 'dify_list_knowledge_bases',
  arguments: { limit: 10 }
});

// 搜索知识库
const searchResults = await client.callTool({
  name: 'dify_search_knowledge_base',
  arguments: {
    knowledge_base_id: 'kb-123',
    query: '机器学习基础',
    top_k: 5
  }
});

🏗️ 架构设计

本服务器遵循官方 MCP TypeScript SDK 架构：

McpServer（官方 SDK）
├── 工具注册（registerTool）
├── 传输层（stdio/HTTP）
├── 业务逻辑（DifyKnowledgeTools）
└── API 客户端（DifyApiClient）

核心组件

  • McpServer：官方 SDK 服务器实例，负责工具注册
  • DifyKnowledgeTools：业务逻辑和工具实现
  • DifyApiClient：用于 Dify API 集成的 HTTP 客户端
  • 传输层：支持多种传输协议

🧪 测试和质量保证

# 运行测试
npm test

# 运行代码检查
npm run lint

# 代码格式化
npm run format

# 构建验证
npm run build

🐳 Docker 部署

快速启动

# 使用 Docker Compose
export DIFY_API_KEY="your-api-key"
docker-compose up -d

手动构建

# 构建镜像
docker build -t dify-mcp-server .

# 运行容器
docker run -d \
  -p 3000:3000 \
  -e DIFY_API_KEY=your-api-key \
  -e DIFY_API_BASE_URL=https://api.dify.ai/v1 \
  -v $(pwd)/logs:/app/logs \
  --name dify-mcp-server \
  dify-mcp-server

健康检查

# 检查容器状态
docker ps

# 检查服务健康
curl http://localhost:3000/health

# 查看日志
docker-compose logs -f dify-mcp-server

📖 详细说明：完整的 Docker 部署指南请参考 。

📋 v1.x 迁移指南

v2.0 版本从自定义 Python 实现迁移到官方 TypeScript SDK：

新增特性

  • ✅ 集成官方 @modelcontextprotocol/sdk
  • ✅ TypeScript 完全类型安全
  • ✅ Zod 模式验证
  • ✅ 标准 MCP 工具结果格式
  • ✅ 流式 HTTP 传输支持
  • ✅ Docker 容器化部署
  • ✅ 生产级错误处理和日志

破坏性变更

  • 🔄 从 Python 更改为 TypeScript/Node.js
  • 🔄 工具名称保持不变，但遵循驼峰命名约定
  • 🔄 配置从 JSON 文件迁移到环境变量
  • 🔄 响应格式标准化为 MCP 规范

迁移步骤

  1. 安装 Node.js 18+
  2. 更新环境变量配置
  3. 重新构建客户端集成
  4. 测试工具调用兼容性

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

  1. Fork 仓库并创建分支
  2. 安装依赖：npm install
  3. 进行更改并确保测试通过
  4. 提交 Pull Request并描述变更内容

开发规范

  • 遵循 TypeScript 严格模式
  • 使用 ESLint 和 Prettier 格式化代码
  • 编写单元测试覆盖新功能
  • 更新相关文档

问题反馈

如发现 Bug 或有功能建议，请在 提交。

📄 开源许可

本项目采用 MIT 许可证 - 详见 文件。

🔗 相关链接

💬 技术支持

  • 📖 查看 和
  • 🐛 报告 Bug
  • 💡 请求新功能
  • 📧 技术交流：通过 GitHub Issues 讨论

⭐ 如果这个项目对您有帮助，请给我们一个 Star！