# 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)