# Postiz Media Manager - MCP Server

MCP (Model Context Protocol) Server สำหรับจัดการและเคลียร์ media ที่ไม่ถูกใช้งานใน Postiz

## คุณสมบัติหลัก

- **ดึงรายการ Media IDs ที่ถูกป้องกัน** - media ที่ถูกใช้ในโพสต์สถานะ draft, scheduled, หรือ queued
- **ค้นหา Orphan Media** - media ที่ไม่ได้ถูกใช้ในโพสต์อนาคตใด ๆ
- **ลบ Media อัตโนมัติ** - พร้อม dry-run mode เพื่อดูผลลัพธ์ก่อนลบจริง
- **สถิติการใช้งาน Media** - แสดงจำนวน media ทั้งหมด, ที่ถูกป้องกัน, และ orphan

## โครงสร้างโปรเจกต์

```
mcp-postiz/
├── src/
│   ├── types.ts          # TypeScript type definitions
│   ├── config.ts         # Configuration management
│   ├── postizClient.ts   # Postiz API client (PLACEHOLDER endpoints)
│   ├── mediaService.ts   # Business logic for media management
│   └── mcpServer.ts      # MCP server implementation
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

## การติดตั้ง

### 1. Clone และติดตั้ง dependencies

```bash
npm install
```

### 2. ตั้งค่า Environment Variables

สร้างไฟล์ `.env` จาก `.env.example`:

```bash
cp .env.example .env
```

แก้ไขไฟล์ `.env`:

```env
# Base URL ของ Postiz API
POSTIZ_BASE_URL=https://api.postiz.app

# API Token สำหรับ authentication
POSTIZ_API_TOKEN=your_actual_api_token_here

# Log level (debug, info, warn, error)
LOG_LEVEL=info
```

### 3. ปรับแต่ง API Endpoints (สำคัญ!)

**⚠️ สำคัญมาก:** ไฟล์ `src/postizClient.ts` ใช้ **PLACEHOLDER endpoints**

คุณต้องแก้ไข endpoints ให้ตรงกับ Postiz API จริงของคุณ:

- `GET /v1/posts` → แก้เป็น endpoint จริงสำหรับดึงรายการโพสต์
- `GET /v1/media` → แก้เป็น endpoint จริงสำหรับดึงรายการ media
- `DELETE /v1/media/:id` → แก้เป็น endpoint จริงสำหรับลบ media

ตรวจสอบเอกสาร API ของ Postiz และแก้ไขใน `src/postizClient.ts`

### 4. ปรับแต่ง Media Field Extraction (สำคัญ!)

ใน `src/mediaService.ts` ฟังก์ชัน `extractMediaIds()` ตรวจสอบหลายฟิลด์ที่อาจมี media IDs:

```typescript
// ปรับแต่งตามโครงสร้าง API จริงของคุณ
- post.mediaIds
- post.files
- post.attachments
- post.media
```

แก้ไขให้ตรงกับฟิลด์ที่ Postiz API ของคุณใช้จริง

### 5. Build โปรเจกต์

```bash
npm run build
```

### 6. เริ่มใช้งาน MCP Server

```bash
npm start
```

## MCP Tools ที่มีให้ใช้งาน

### 1. `postiz_list_future_protected_media_ids`

ดึงรายการ media IDs ที่ห้ามลบ (ถูกใช้ในโพสต์อนาคต)

**Input:**
```json
{
  "statuses": ["draft", "scheduled", "queued"]  // Optional
}
```

**Output:**
```json
{
  "protectedMediaIds": ["media-id-1", "media-id-2", "media-id-3"],
  "count": 3
}
```

### 2. `postiz_list_all_media`

ดึงรายการ media ทั้งหมด

**Input:**
```json
{
  "limit": 100  // Optional
}
```

**Output:**
```json
{
  "items": [
    {
      "id": "media-id-1",
      "url": "https://example.com/media1.jpg",
      "createdAt": "2025-01-01T00:00:00Z",
      "deleted": false,
      "deletedAt": null
    }
  ],
  "total": 150,
  "returned": 100
}
```

### 3. `postiz_find_orphan_media`

ค้นหา media ที่ไม่ถูกใช้ในโพสต์อนาคต (orphan media)

**Input:**
```json
{
  "limit": 50  // Optional
}
```

**Output:**
```json
{
  "items": [
    {
      "id": "orphan-media-1",
      "url": "https://example.com/orphan1.jpg",
      "createdAt": "2024-12-01T00:00:00Z"
    }
  ],
  "totalCandidates": 25
}
```

### 4. `postiz_cleanup_orphan_media`

ลบ orphan media (พร้อม dry-run mode)

**Input:**
```json
{
  "dryRun": true,   // true = ไม่ลบจริง, false = ลบจริง (default: false)
  "limit": 10       // Optional: จำกัดจำนวนที่จะลบ
}
```

**Output:**
```json
{
  "totalCandidates": 10,
  "deletedCount": 8,
  "failedCount": 2,
  "deletedIds": ["media-1", "media-2", "media-3"],
  "failedIds": [
    {
      "id": "media-4",
      "reason": "Permission denied"
    }
  ]
}
```

### 5. `postiz_get_media_stats`

ดูสถิติการใช้งาน media

**Input:**
```json
{}
```

**Output:**
```json
{
  "totalMedia": 1000,
  "protectedMedia": 750,
  "orphanMedia": 250
}
```

## การใช้งานแนะนำ

### ขั้นตอนการเคลียร์ media ที่ปลอดภัย:

1. **ดูสถิติก่อน:**
   ```json
   Tool: postiz_get_media_stats
   ```

2. **ทดสอบด้วย dry-run:**
   ```json
   Tool: postiz_cleanup_orphan_media
   Input: { "dryRun": true, "limit": 10 }
   ```

3. **ตรวจสอบรายการที่จะลบ:**
   ```json
   Tool: postiz_find_orphan_media
   Input: { "limit": 10 }
   ```

4. **ลบจริง (เริ่มจากจำนวนน้อย):**
   ```json
   Tool: postiz_cleanup_orphan_media
   Input: { "dryRun": false, "limit": 10 }
   ```

5. **ตรวจสอบผลลัพธ์และทำซ้ำ**

## Logic การทำงาน

### Orphan Media คืออะไร?

Media จะถือว่าเป็น "orphan" (ไม่ถูกใช้งาน) เมื่อ:

1. **ไม่ได้ถูกอ้างอิงในโพสต์ใด ๆ** ที่มีสถานะเป็น:
   - `draft` (แบบร่าง)
   - `scheduled` (กำหนดเวลาไว้)
   - `queued` (อยู่ในคิว)

2. **ยังไม่ถูกลบ** (`deleted = false` หรือ `deletedAt = null`)

### ทำไมไม่ใช้วันที่เป็นเกณฑ์?

โปรแกรมนี้ **ไม่ได้ใช้วันที่** เป็นเกณฑ์ในการลบ เพราะ:

- Media ที่เก่าแต่ยังถูกใช้ในโพสต์ scheduled ไว้ → **ไม่ลบ**
- Media ที่ใหม่แต่ไม่ถูกใช้ในโพสต์ใด ๆ → **ลบได้**

วิธีนี้ปลอดภัยกว่าและแม่นยำกว่าการใช้วันที่

## การ Config MCP Client

เพิ่ม server นี้ใน MCP client configuration (เช่น Claude Desktop):

```json
{
  "mcpServers": {
    "postiz-media-manager": {
      "command": "node",
      "args": ["/path/to/mcp-postiz/dist/mcpServer.js"],
      "env": {
        "POSTIZ_BASE_URL": "https://api.postiz.app",
        "POSTIZ_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

## Development

### Build และ Watch Mode

```bash
# Build แบบปกติ
npm run build

# Watch mode (auto-rebuild on change)
npm run dev

# Clean build artifacts
npm run clean
```

### ทดสอบ

1. ตรวจสอบว่า TypeScript compile ผ่าน:
   ```bash
   npm run build
   ```

2. ทดสอบรัน server:
   ```bash
   npm start
   ```

3. ทดสอบเชื่อมต่อกับ MCP client

## Error Handling

- ทุก API call มี try-catch และ error logging
- การลบ media ที่ล้มเหลวจะถูกบันทึกใน `failedIds` ไม่ทำให้กระบวนการทั้งหมดหยุด
- Axios interceptor จัดการ HTTP errors โดยอัตโนมัติ

## คำเตือนและข้อควรระวัง

⚠️ **สำคัญมาก:**

1. **ทดสอบด้วย `dryRun: true` เสมอก่อนลบจริง**
2. **สำรองข้อมูลก่อนรัน cleanup ครั้งแรก**
3. **ตรวจสอบ endpoint URLs ให้ถูกต้อง** - ตัวอย่างใน code เป็น placeholder เท่านั้น
4. **ตรวจสอบฟิลด์ media ให้ตรงกับ API** - แก้ `extractMediaIds()` ให้เหมาะสม
5. **เริ่มต้นด้วย `limit` น้อย ๆ** เพื่อทดสอบการทำงาน

## License

MIT

## ผู้พัฒนา

สร้างด้วย TypeScript + MCP SDK สำหรับจัดการ media ใน Postiz อย่างมีประสิทธิภาพ