burmddit/mcp-server/MCP-SETUP-GUIDE.md

# Burmddit MCP Server Setup Guide

**Model Context Protocol (MCP)** enables AI assistants (like Modo, Claude Desktop, etc.) to connect directly to Burmddit for autonomous management.

## What MCP Provides

**10 Powerful Tools:**

1. ✅ `get_site_stats` - Real-time analytics (articles, views, categories)
2. 📚 `get_articles` - Query articles by category, tag, status
3. 📄 `get_article_by_slug` - Get full article details
4. ✏️ `update_article` - Update article fields
5. 🗑️ `delete_article` - Delete or archive articles
6. 🔍 `get_broken_articles` - Find quality issues
7. 🚀 `check_deployment_status` - Coolify deployment status
8. 🔄 `trigger_deployment` - Force new deployment
9. 📋 `get_deployment_logs` - View deployment logs
10. ⚡ `run_pipeline` - Trigger content pipeline

## Installation

### 1. Install MCP SDK

```bash
cd /home/ubuntu/.openclaw/workspace/burmddit/mcp-server
pip3 install mcp psycopg2-binary requests
```

### 2. Set Database Credentials

Add to `/home/ubuntu/.openclaw/workspace/.credentials`:

```bash
DATABASE_URL=postgresql://user:password@host:port/burmddit
```

Or configure in the server directly (see `load_db_config()`).

### 3. Test MCP Server

```bash
python3 burmddit-mcp-server.py
```

Server should start and listen on stdio.

## OpenClaw Integration

### Add to OpenClaw MCP Config

Edit `~/.openclaw/config.json` or your OpenClaw MCP config:

```json
{
  "mcpServers": {
    "burmddit": {
      "command": "python3",
      "args": ["/home/ubuntu/.openclaw/workspace/burmddit/mcp-server/burmddit-mcp-server.py"],
      "env": {
        "PYTHONPATH": "/home/ubuntu/.openclaw/workspace/burmddit"
      }
    }
  }
}
```

### Restart OpenClaw

```bash
openclaw gateway restart
```

## Usage Examples

### Via OpenClaw (Modo)

Once connected, Modo can autonomously:

**Check site health:**
```
Modo, check Burmddit stats for the past 7 days
```

**Find broken articles:**
```
Modo, find articles with translation errors
```

**Update article status:**
```
Modo, archive the article with slug "ai-news-2026-02-15"
```

**Trigger deployment:**
```
Modo, deploy the latest changes to burmddit.com
```

**Run content pipeline:**
```
Modo, run the content pipeline to publish 30 new articles
```

### Via Claude Desktop

Add to Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "burmddit": {
      "command": "python3",
      "args": ["/home/ubuntu/.openclaw/workspace/burmddit/mcp-server/burmddit-mcp-server.py"]
    }
  }
}
```

Then restart Claude Desktop and it will have access to Burmddit tools.

## Tool Details

### get_site_stats

**Input:**
```json
{
  "days": 7
}
```

**Output:**
```json
{
  "total_articles": 120,
  "recent_articles": 30,
  "recent_days": 7,
  "total_views": 15420,
  "avg_views_per_article": 128.5,
  "categories": [
    {"name": "AI သတင်းများ", "count": 80},
    {"name": "သင်ခန်းစာများ", "count": 25}
  ]
}
```

### get_articles

**Input:**
```json
{
  "category": "ai-news",
  "status": "published",
  "limit": 10
}
```

**Output:**
```json
[
  {
    "slug": "chatgpt-5-release",
    "title": "ChatGPT-5 ထွက်ရှိမည်",
    "published_at": "2026-02-19 14:30:00",
    "view_count": 543,
    "status": "published",
    "category": "AI သတင်းများ"
  }
]
```

### get_broken_articles

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

**Output:**
```json
[
  {
    "slug": "broken-article-slug",
    "title": "Translation error article",
    "content_length": 234
  }
]
```

Finds articles with:
- Content length < 500 characters
- Repeated text patterns
- Translation errors

### update_article

**Input:**
```json
{
  "slug": "article-slug",
  "updates": {
    "status": "archived",
    "excerpt_burmese": "New excerpt..."
  }
}
```

**Output:**
```
✅ Updated article: ဆောင်းပါးခေါင်းစဉ် (ID: 123)
```

### trigger_deployment

**Input:**
```json
{
  "force": true
}
```

**Output:**
```
✅ Deployment triggered: 200
```

Triggers Coolify to rebuild and redeploy Burmddit.

## Security

⚠️ **Important:**
- MCP server has FULL database and deployment access
- Only expose to trusted AI assistants
- Store credentials securely in `.credentials` file (chmod 600)
- Audit MCP tool usage regularly

## Troubleshooting

### "MCP SDK not installed"

```bash
pip3 install mcp
```

### "Database connection failed"

Check `.credentials` file has correct `DATABASE_URL`.

### "Coolify API error"

Verify `COOLIFY_TOKEN` in `.credentials` is valid.

### MCP server not starting

```bash
python3 burmddit-mcp-server.py
# Should print MCP initialization messages
```

## Next Steps

1. ✅ Install MCP SDK
2. ✅ Configure database credentials
3. ✅ Add to OpenClaw config
4. ✅ Restart OpenClaw
5. ✅ Test with: "Modo, check Burmddit stats"

**Modo will now have autonomous management capabilities!** 🚀