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

npm install

2. ตั้งค่า Environment Variables

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

cp .env.example .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:

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

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

5. Build โปรเจกต์

npm run build

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

npm start

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

1. postiz_list_future_protected_media_ids

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

Input:

{
  "statuses": ["draft", "scheduled", "queued"]  // Optional
}

Output:

{
  "protectedMediaIds": ["media-id-1", "media-id-2", "media-id-3"],
  "count": 3
}

2. postiz_list_all_media

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

Input:

{
  "limit": 100  // Optional
}

Output:

{
  "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:

{
  "limit": 50  // Optional
}

Output:

{
  "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:

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

Output:

{
  "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:

{}

Output:

{
  "totalMedia": 1000,
  "protectedMedia": 750,
  "orphanMedia": 250
}

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

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

1. ดูสถิติก่อน:

   Tool: postiz_get_media_stats
   

2. ทดสอบด้วย dry-run:

   Tool: postiz_cleanup_orphan_media
   Input: { "dryRun": true, "limit": 10 }
   

3. ตรวจสอบรายการที่จะลบ:

   Tool: postiz_find_orphan_media
   Input: { "limit": 10 }
   

4. ลบจริง (เริ่มจากจำนวนน้อย):

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

{
  "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

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

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

# Clean build artifacts
npm run clean

ทดสอบ

1. ตรวจสอบว่า TypeScript compile ผ่าน:

   npm run build
   

2. ทดสอบรัน server:

   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 อย่างมีประสิทธิภาพ