socialmag v0.1 — 4/5 platforms live (Threads, FB, IG, TikTok)

2026-09-10 21:10:55 +08:00
commit a4f33f456e
28 changed files with 2053 additions and 0 deletions
@@ -0,0 +1,114 @@
+# 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.*