Dify Knowledge API 를 활용해 매주 지식 파일이 바뀌는 챗봇 만들기 (with 클로드 코드)

# Dify MCP 연결 가이드

Claude Code와 로컬 Dify 서버를 MCP(Model Context Protocol)로 연결하는 방법을 설명합니다.

## 📋 목차
- [사전 요구사항](#사전-요구사항)
- [앱 유형별 설정](#앱-유형별-설정)
- [MCP 서버 등록](#mcp-서버-등록)
- [연결 테스트](#연결-테스트)
- [문제 해결](#문제-해결)

## 🔧 사전 요구사항

### 1. Dify 서버 실행
```bash
# Dify 도커 컨테이너들이 실행되어 있어야 함
docker ps | grep dify
```

### 2. Claude Code 설치
- Claude Code CLI가 설치되어 있어야 함

### 3. 필수 도구
```bash
# uvx 설치 확인
uvx --version

# 또는 uv 설치
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## 📱 앱 유형별 설정

### 🤖 챗봇 앱 (Chatbot)

#### 1. 앱 생성 및 설정
1. Dify 대시보드에서 **챗봇** 유형으로 앱 생성
2. LLM 모델 설정 (GPT-4, Claude 등)
3. 프롬프트 및 대화 설정 구성
4. **게시(Publish)** 버튼 클릭

#### 2. API 키 생성
1. 앱 설정 → **API 액세스** 탭
2. **Service API** 키 생성 및 복사
3. 키 형식: `app-xxxxxxxxxxxxxxxxx`

#### 3. API 엔드포인트
```bash
POST http://localhost/v1/chat-messages
Content-Type: application/json
Authorization: Bearer app-xxxxxxxxxxxxxxxxx

{
  "inputs": {},
  "query": "사용자 메시지",
  "response_mode": "streaming",  # 또는 "blocking"
  "conversation_id": "",         # 대화 연속성을 위한 ID
  "user": "user-123"
}
```

#### 4. MCP 설정 (챗봇)
```json
{
  "mcpServers": {
    "dify-chatbot": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/YanxingLiu/dify-mcp-server",
        "dify_mcp_server"
      ],
      "env": {
        "DIFY_BASE_URL": "http://localhost/v1",
        "DIFY_APP_SKS": "app-YOUR_CHATBOT_API_KEY"
      }
    }
  }
}
```

### 🔄 워크플로우 앱 (Workflow)

#### 1. 앱 생성 및 설정
1. Dify 대시보드에서 **워크플로우** 유형으로 앱 생성
2. 워크플로우 노드 구성:
   - **Start 노드**: 입력 변수 정의
   - **LLM 노드**: AI 모델 설정
   - **End 노드**: 출력 변수 정의
3. 워크플로우 테스트 및 **게시(Publish)**

#### 2. API 키 생성
1. 앱 설정 → **API 액세스** 탭
2. **Service API** 키 생성 및 복사
3. 키 형식: `app-xxxxxxxxxxxxxxxxx`

#### 3. API 엔드포인트
```bash
POST http://localhost/v1/workflows/run
Content-Type: application/json
Authorization: Bearer app-xxxxxxxxxxxxxxxxx

{
  "inputs": {
    "input_variable": "입력 값",    # 워크플로우에서 정의한 변수들
    "another_var": "다른 값"
  },
  "response_mode": "blocking",      # 워크플로우는 주로 blocking 모드
  "user": "user-123"
}
```

#### 4. MCP 설정 (워크플로우)
```json
{
  "mcpServers": {
    "dify-workflow": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/YanxingLiu/dify-mcp-server",
        "dify_mcp_server"
      ],
      "env": {
        "DIFY_BASE_URL": "http://localhost/v1",
        "DIFY_APP_SKS": "app-YOUR_WORKFLOW_API_KEY"
      }
    }
  }
}
```

### 📝 텍스트 생성 앱 (Text Generator)

#### 1. 앱 생성 및 설정
1. Dify 대시보드에서 **텍스트 생성** 유형으로 앱 생성
2. 프롬프트 템플릿 작성 (변수 포함 가능)
3. LLM 모델 설정
4. **게시(Publish)** 버튼 클릭

#### 2. API 엔드포인트
```bash
POST http://localhost/v1/completion-messages
Content-Type: application/json
Authorization: Bearer app-xxxxxxxxxxxxxxxxx

{
  "inputs": {
    "variable1": "값1",    # 프롬프트에서 정의한 변수들
    "variable2": "값2"
  },
  "response_mode": "blocking",
  "user": "user-123"
}
```

## ⚙️ MCP 서버 등록

### 1. 설정 파일 위치
```bash
~/.config/claude-code/mcp_settings.json
```

### 2. 완전한 설정 예시
```json
{
  "mcpServers": {
    "dify-chatbot": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/YanxingLiu/dify-mcp-server",
        "dify_mcp_server"
      ],
      "env": {
        "DIFY_BASE_URL": "http://localhost/v1",
        "DIFY_APP_SKS": "app-chatbot-api-key"
      }
    },
    "dify-workflow": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/YanxingLiu/dify-mcp-server",
        "dify_mcp_server"
      ],
      "env": {
        "DIFY_BASE_URL": "http://localhost/v1",
        "DIFY_APP_SKS": "app-workflow-api-key"
      }
    }
  }
}
```

### 3. 여러 앱 동시 사용
```json
{
  "mcpServers": {
    "dify-assistant": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/YanxingLiu/dify-mcp-server",
        "dify_mcp_server"
      ],
      "env": {
        "DIFY_BASE_URL": "http://localhost/v1",
        "DIFY_APP_SKS": "app-chatbot-key,app-workflow-key,app-completion-key"
      }
    }
  }
}
```

## 🧪 연결 테스트

### 1. MCP 서버 상태 확인
```bash
claude mcp list
```

### 2. API 직접 테스트
```bash
# 챗봇 테스트
curl -X POST "http://localhost/v1/chat-messages" \
  -H "Authorization: Bearer app-YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "안녕하세요",
    "response_mode": "blocking",
    "user": "test-user"
  }'

# 워크플로우 테스트  
curl -X POST "http://localhost/v1/workflows/run" \
  -H "Authorization: Bearer app-YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"input": "테스트 입력"},
    "response_mode": "blocking",
    "user": "test-user"
  }'
```

### 3. MCP 프로토콜 테스트
```python
import json
import subprocess
import os

os.environ['DIFY_BASE_URL'] = 'http://localhost/v1'
os.environ['DIFY_APP_SKS'] = 'app-YOUR-API-KEY'

mcp_request = {
    'jsonrpc': '2.0',
    'id': 1,
    'method': 'initialize',
    'params': {
        'protocolVersion': '2024-11-05',
        'capabilities': {},
        'clientInfo': {'name': 'test-client', 'version': '1.0.0'}
    }
}

proc = subprocess.Popen([
    'uvx', '--from', 'git+https://github.com/YanxingLiu/dify-mcp-server', 'dify_mcp_server'
], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)

request_line = json.dumps(mcp_request) + '\n'
stdout, stderr = proc.communicate(input=request_line, timeout=10)
print('Response:', stdout)
```

## 🔧 문제 해결

### 1. 연결 실패 시 체크리스트

#### ❌ "App unavailable" 오류
- [ ] 앱이 게시(Published) 되었는지 확인
- [ ] API 키가 올바른지 확인
- [ ] 앱 유형과 API 엔드포인트가 일치하는지 확인

#### ❌ "Bad Request" 오류  
- [ ] 요청 JSON 형식이 올바른지 확인
- [ ] 필수 필드가 누락되지 않았는지 확인
- [ ] Authorization 헤더가 올바른지 확인

#### ❌ "Not chat app" 오류
- [ ] 챗봇 앱이 아닌데 `/chat-messages` 엔드포인트 사용
- [ ] 올바른 앱 유형의 API 엔드포인트 사용 필요

#### ❌ "Workflow not published" 오류
- [ ] 워크플로우를 게시했는지 확인
- [ ] 워크플로우에 오류가 없는지 확인

### 2. 로그 확인
```bash
# Dify 컨테이너 로그 확인
docker logs docker-api-1

# MCP 서버 수동 실행으로 디버깅
DIFY_BASE_URL="http://localhost/v1" DIFY_APP_SKS="app-YOUR-KEY" \
uvx --from "git+https://github.com/YanxingLiu/dify-mcp-server" dify_mcp_server
```

### 3. 자주 발생하는 문제

| 문제 | 원인 | 해결책 |
|------|------|--------|
| MCP 서버 연결 실패 | 서버가 on-demand로 실행됨 | 정상 동작, 실제 사용 시 자동 시작 |
| API 키 오류 | 잘못된 키 또는 만료 | 새 API 키 생성 및 교체 |
| 앱 유형 불일치 | 잘못된 엔드포인트 사용 | 앱 유형에 맞는 API 사용 |
| 게시 안됨 | 앱이 초안 상태 | Dify에서 앱 게시 필요 |

## 💡 사용 팁

### 1. 효율적인 MCP 활용
- 챗봇: 대화형 AI 서비스, 고객 상담
- 워크플로우: 복잡한 데이터 처리, 자동화
- 텍스트 생성: 콘텐츠 생성, 번역

### 2. 성능 최적화
```json
{
  "env": {
    "DIFY_BASE_URL": "http://localhost/v1",
    "DIFY_APP_SKS": "app-key1,app-key2",
    "DIFY_TIMEOUT": "30",
    "DIFY_MAX_RETRIES": "3"
  }
}
```

### 3. 보안 고려사항
- API 키를 환경 변수로 관리
- 로컬 네트워크에서만 사용 권장
- 정기적인 API 키 로테이션

## 📚 참고 자료

- [Dify 공식 문서](https://docs.dify.ai/)
- [MCP 프로토콜 규격](https://modelcontextprotocol.io/)
- [Dify MCP 서버 GitHub](https://github.com/YanxingLiu/dify-mcp-server)
- [Claude Code 문서](https://docs.anthropic.com/en/docs/claude-code)

---

**작성일**: 2025-09-10  
**버전**: 1.0  
**테스트 환경**: Dify 1.8.1, Claude Code latest