星战科技xingzhan.cloud
返回市场
差异知识MCP服务器

差异知识MCP服务器

作者：Mocha-s2 星标更新：2025-08-23
安装使用来源：spider==github.com

项目介绍

Dify 知识库 MCP 服务器 v2.0

MCP 兼容 TypeScript 官方 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 部署支持准备好的容器化部署解决方案

📦 快速开始

方法 1：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 检查服务状态。

方法 2：本地开发

# 安装依赖
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 DDIFY_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(可选) - 分段状态（如“已完成”）
    • 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 迁移指南

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

新增功能

  • ✅ 集成官方 @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 文件。

🔗 相关链接

💬 技术支持

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