# socialmag — Social Media MCP Server

**One tool, all platforms.** Post to Threads, Facebook, Instagram, TikTok (and YouTube when eligible) through a single MCP call. Built on CDP — no API keys, no rate limits, no approval process. Just a browser and a logged-in account.

## What It Does

- **`create_post`** — Post text/media to one or more platforms in one call
- **`check_login`** — Verify which platforms are logged in
- **`get_status`** — Last post results + open browser tabs

## Architecture

```
Claude/MCP Client
    ↓ stdio (JSON-RPC)
socialmag server.py
    ↓ CDP WebSocket
Brave Browser (dedicated instance, port 9336)
    ↓ real browser sessions
Threads · Facebook · Instagram · TikTok · YouTube
```

- **Tab reuse** — attaches to existing tabs, no cold loads
- **Per-platform modules** — each platform has its own flow + selectors
- **Sequential queue** — one platform at a time, no race conditions
- **Error screenshots** — failed flows capture the page state to `/tmp/socialmag/`

## Platform Status

| Platform | Text | Media | Tab Reuse | Status |
|----------|:----:|:-----:|:---------:|--------|
| Threads | ✅ | 🔲 | ✅ | **Live** — inline composer |
| Facebook | ✅ | 🔲 | ✅ | **Live** — dialog flow |
| Instagram | — | ✅ | ✅ | **Live** — media required |
| TikTok | — | ✅ | ✅ | **Live** — video/photo upload |
| YouTube | 🔲 | 🔲 | ✅ | **Parked** — needs 500 subs |

✅ = tested live · 🔲 = coded but untested · — = not applicable

## Stack

- Python 3 (stdlib + websockets)
- Chrome DevTools Protocol (CDP)
- MCP stdio transport
- Brave Browser with `--remote-debugging-port`

## Browser Setup

```bash
# Dedicated Brave instance (separate profile, no interference)
brave --remote-debugging-port=9336 \
      --user-data-dir=$HOME/.local/share/brave-socialmag \
      --disable-features=BeforeUnloadDialog \
      --mute-audio --no-first-run
```

Log into each platform manually once. socialmag reuses those sessions.

## Future Roadmap

### v0.2 — Read Side
- [ ] `get_notifications(platform)` — pull notifications via CDP scraping
- [ ] `get_comments(platform, post_id?)` — read comments on recent posts
- [ ] `get_engagement(platform)` — likes, shares, reach per post

### v0.3 — Monitoring
- [ ] Cron/loop polling — periodic checks, dump to JSON
- [ ] Unified notification feed across all platforms
- [ ] Alert on new comments/DMs

### v0.4 — Dashboard
- [ ] Web dashboard — one view for all platform activity
- [ ] Post scheduler — queue posts for specific times
- [ ] Analytics — engagement trends, best posting times

### v0.5 — Media Pipeline
- [ ] Threads media posting (image + video)
- [ ] Facebook media posting
- [ ] YouTube video upload (separate from community posts)
- [ ] Auto-resize/format media per platform requirements

### Later
- [ ] Multi-account support
- [ ] Platform API integration (where available + worthwhile)
- [ ] Content calendar
- [ ] AI-assisted caption generation

## File Structure

```
socialmag/
├── __init__.py       # package marker
├── __main__.py       # python -m socialmag entry
├── server.py         # MCP stdio server + tool handlers
├── cdp.py            # CDP WebSocket client
├── selectors.py      # all platform selectors in one file
├── queue.py          # sequential post queue
├── platforms/
│   ├── __init__.py   # shared helpers (guard, require_media, etc.)
│   ├── threads.py
│   ├── facebook.py
│   ├── instagram.py
│   ├── tiktok.py
│   └── youtube.py
└── MANIFEST.md       # this file
```

## License

Private. Shared among collaborators by invitation.

---

*Born 2026-09-10. Built by the household — Celeste architected, Umbra built the skeleton, abang drove the FAFO.*