# Dify External Knowledge MCP Server
一個 Model Context Protocol (MCP) 伺服器，用於整合 Dify 外部知識庫 API，讓 AI Agent 能夠輕鬆查詢知識庫內容。
## 安裝
### 使用 npx (推薦)
```bash
npx @funtuantw/dify-external-knowledge-mcp
```
### 全域安裝
```bash
npm install -g @funtuantw/dify-external-knowledge-mcp
```
### 從源碼構建
```bash
git clone https://github.com/funtuantw/dify-external-knowledge-mcp.git
cd dify-external-knowledge-mcp
npm install
npm run build
```
## 功能特性
- 🔍 查詢 Dify 外部知識庫
- 📊 支援相關性分數閾值設定
- 🎯 支援元數據條件篩選
- 🔐 使用環境變數管理 API 憑證
- 📦 支援 npx 直接運行
- 🌐 知識庫 ID 透過環境變數配置，無需每次指定
## 配置
```json
{
"mcpServers": {
"dify-knowledge": {
"command": "npx",
"args": ["@funtuantw/dify-external-knowledge-mcp"],
"env": {
"DIFY_KNOWLEDGE_ENDPOINT": "https://your-endpoint.com",
"DIFY_API_KEY": "your-api-key-here",
"DIFY_KNOWLEDGE_ID": "your-knowledge-id-here"
}
}
}
}
```
或者使用本地路徑（開發時）：
```json
{
"mcpServers": {
"dify-knowledge": {
"command": "node",
"args": ["/absolute/path/to/dify-external-knowledge-mcp/dist/index.js"],
"env": {
"DIFY_KNOWLEDGE_ENDPOINT": "https://your-endpoint.com",
"DIFY_API_KEY": "your-api-key-here",
"DIFY_KNOWLEDGE_ID": "your-knowledge-id-here"
}
}
}
}
```
使用命令列參數：
```json
{
"mcpServers": {
"dify-knowledge": {
"command": "npx",
"args": [
"@funtuantw/dify-external-knowledge-mcp",
"--endpoint",
"https://your-endpoint.com",
"--api-key",
"your-api-key-here",
"--knowledge-id",
"your-knowledge-id-here"
]
}
}
}
```
## 使用方法
### 可用工具
#### `query_dify_knowledge`
查詢 Dify 外部知識庫以檢索相關資訊。
**參數：**
- `query` (必需, string): 用戶的搜尋查詢或問題
- `top_k` (可選, number): 返回的最大結果數量（預設：5）
- `score_threshold` (可選, number): 最小相關性分數閾值，範圍 0-1（預設：0.5）
- `metadata_condition` (可選, object): 元數據篩選條件
- `logical_operator` (可選, string): "and" 或 "or"（預設：and）
- `conditions` (必需, array): 條件列表
- `name` (必需, string[]): 要篩選的元數據欄位名稱
- `comparison_operator` (必需, string): 比較運算符（contains, is, not contains, etc.）
- `value` (可選, string): 比較值
**範例使用（通過 AI Agent）：**
```
請使用 query_dify_knowledge 工具查詢 "什麼是 Dify？"
```
**範例輸出：**
```
Found 2 result(s) for query: "什麼是 Dify？"
### Result 1 (Score: 0.980)
**Title**: knowledge.txt
**Content**:
Dify 是一個 LLMOps 平台，提供 GenAI 應用程序的創新引擎。
**Metadata**: {
"path": "s3://dify/knowledge.txt",
"description": "dify 知識文檔"
}
---
### Result 2 (Score: 0.660)
**Title**: introduce.txt
**Content**:
GenAI 應用程序的創新引擎
**Metadata**: {
"path": "s3://dify/introduce.txt",
"description": "dify 介紹"
}
---
```
## 開發
### 開發模式運行
```bash
npm run dev
```
### 構建專案
```bash
npm run build
```
### 運行構建版本
```bash
npm start
```
## API 參考
本專案使用 [Dify 外部知識庫 API](https://docs.dify.ai/zh-hans/guides/knowledge-base/api-documentation/external-knowledge-api-documentation)。
### 支援的比較運算符
- `contains`: 包含某個值
- `not contains`: 不包含某個值
- `start with`: 以某個值開頭
- `end with`: 以某個值結尾
- `is`: 等於某個值
- `is not`: 不等於某個值
- `empty`: 為空
- `not empty`: 不為空
- `=`: 等於
- `≠`: 不等於
- `>`: 大於
- `<`: 小於
- `≥`: 大於等於
- `≤`: 小於等於
- `before`: 在某個日期之前
- `after`: 在某個日期之後
## 錯誤處理
伺服器會處理以下錯誤情況：
- **1001**: 無效的 Authorization 頭格式
- **1002**: 授權失敗
- **2001**: 知識庫不存在
- **HTTP 403**: 訪問被拒絕
- **HTTP 500**: 內部伺服器錯誤
## 專案結構
```
dify-external-knowledge-mcp/
├── src/
│ └── index.ts # MCP 伺服器主程式
├── dist/ # 編譯後的輸出
├── .env.example # 環境變數範例
├── .gitignore
├── package.json
├── tsconfig.json
├── plan.md # 專案計畫文檔
└── README.md
```
## 授權
MIT
## 貢獻
歡迎提交 Issue 和 Pull Request！
## 相關連結
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Dify 文檔](https://docs.dify.ai/)
- [Dify 外部知識庫 API](https://docs.dify.ai/zh-hans/guides/knowledge-base/api-documentation/external-knowledge-api-documentation)
- [GitHub Repository](https://github.com/funtuantw/dify-external-knowledge-mcp)
- [npm Package](https://www.npmjs.com/package/@funtuantw/dify-external-knowledge-mcp)
