Dify 知识库 MCP 服务器 v2.0

基于官方 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 部署说明请参考 DOCKER.md。

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 部署指南请参考 DOCKER.md。

📋 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 或有功能建议，请在 GitHub Issues 提交。

📄 开源许可

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

🔗 相关链接

• 模型上下文协议 (MCP)
• MCP TypeScript SDK
• Dify API 文档
• Docker 部署指南

💬 技术支持

• 📖 查看 文档 和 Docker 指南
• 🐛 提交问题 报告 Bug
• 💡 功能建议 请求新功能
• 📧 技术交流：通过 GitHub Issues 讨论

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