Social-ops

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #golang #go #machine-learning #rust #linux #kubernetes #vue #security #ios #mcp #openai

(★ 18)

Open-source MCP + SaaS console for social-media topic-aggregation reports across Reddit / Instagram / Facebook / X / App Store / Google Play. No LLM required, localhost-only by default. 开源社交媒体情报 MCP 服务 + SaaS 控制台，主题聚合报告覆盖 Reddit / Instagram / Facebook / X / App Store / Google Play，无需 LLM，默认仅本机可访问。

Social-ops Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Social-Ops

Open-source social-media intelligence platform for AI agents. Wire it into
Claude Code / Cursor / Continue / any MCP-compatible client and your agent
gains topic-aggregation reports across Reddit, Instagram, Facebook, X, App
Store and Google Play — backed by a SaaS-style web console for browsing
reports, tracking jobs, and managing credentials.

**Two services, two ports:**

| Service                | Purpose                                              | Port (localhost) |
|------------------------|------------------------------------------------------|------------------|
| `mcp` (MCP server)     | Streamable-HTTP MCP tools + REST API for the console | `8097`           |
| `console` (Web UI)     | Reports browser, task tracker, settings wizard       | `8088`           |

No LLM is required. Reports are produced by a deterministic NLP pipeline
(TF-IDF / sentence-transformers clustering + lexicon / XLM-RoBERTa sentiment).

---

## Quickstart

```bash
git clone <this repo>
cd social-ops
cp .env.example .env
docker compose up -d
open http://localhost:8088
```

The console will detect that no required keys are configured and walk you
through a 5-step wizard to enter Reddit + Apify credentials (free / freemium),
then optionally Instagram + X session cookies. After `docker compose restart
mcp` the MCP server picks up the new env, and you can wire your agent into
the endpoint shown on the **Connect** tab.

For Claude Code:

```bash
claude mcp add --transport http social-ops http://localhost:8097/mcp
```

Then in any session: *"Analyze the r/python subreddit and tell me what people
are discussing this month."*

---

## What it does

The MCP server exposes 16 tools, organized in three groups:

### Collection / analysis (async — return a `task_id`)

| Tool                        | What it does                                           |
|-----------------------------|--------------------------------------------------------|
| `analyze_reddit`            | Cluster a list of subreddits with sentiment + evidence |
| `analyze_instagram`         | Same, for IG accounts and/or hashtags (Apify)          |
| `analyze_facebook`          | Same, for FB pages or keyword search (Apify)           |
| `analyze_x`                 | Same, for X accounts and/or queries (xreach)           |
| `analyze_gplay_reviews`     | Cluster Google Play reviews for a given app            |
| `analyze_appstore_reviews`  | Cluster App Store reviews (Apify)                      |

### Task & report inspection (instant)

| Tool                          | What it does                                       |
|-------------------------------|----------------------------------------------------|
| `get_task_status`             | Poll task progress (`queued` / `running` / etc.)   |
| `get_task_result`             | Retrieve `handle_id` + KPIs once a task completes  |
| `list_tasks`                  | Recent task history                                |
| `get_report` / `list_reports` | Fetch a single report or browse the library       |
| `expand_topic`                | Drill into a topic cluster's full evidence set     |
| `compare_reports`             | Side-by-side comparison of 2+ reports              |
| `prepare_report_download`     | Generate a one-time `.zip`/`.md`/`.json` URL       |

### Utility

- `search_app` — find Google Play / App Store bundle IDs before analyzing
- `help` — per-tool docs (token-efficient progressive disclosure)

### Report shape (what your agent gets back)

Pure topic-aggregation, no prescriptive analysis. Each report contains:

- **Overview** — doc count, topic count, sentiment distribution, coverage
- **Topics** (one block per cluster) — discussion count, share %, sentiment
  breakdown, top key terms, top subreddits/accounts, monthly volume,
  representative quote, 4–6 cited evidence snippets
- **Time Trend** — monthly doc + sentiment counts
- **Data Quality** — confidence, uncertainty flags
- **Method Card** — collection / indexing / clustering / sentiment models
- **Citations** — full index, every cited source linkable

Reports are stored at `data/cache/<platform>/reports/<handle_id>.{md,json}`
and surfaced via the console at <http://localhost:8088/reports>.

---

## Architecture

```
┌────────────────┐   HTTP      ┌────────────────┐
│  Your Agent    │────────────▶│   mcp:8097     │ Streamable-HTTP MCP
│ (Claude/Cursor)│             │  (FastMCP)     │ + REST /api/*
└────────────────┘             └───┬────────────┘
                                   │ subprocess
                                   ▼
        ┌──────────────────────────────────────────┐
        │  tools/                                  │
        │   ├─ reddit-ops/   (Node, OAuth)         │
        │   ├─ social-ops/   (Python, Apify+xreach)│
        │   ├─ google-play-scraper/   (Node CLI)   │
        │   └─ app-store-scraper/     (Node CLI)   │
        └──────────────────────────────────────────┘
                                   │
        ┌──────────────────────────▼───────────────┐
        │  data/cache/{reddit,social-ops}/         │
        │  (collection JSONL / index / analysis /  │
        │   reports / cost log)                    │
        └──────────────────────────────────────────┘
                  ▲
                  │  /api/reports, /api/tasks
                  │
       ┌──────────┴──────────┐
       │  console:8088       │ React + Vite + Tailwind
       │  (FastAPI + SPA)    │ → 6 languages, no auth in core
       └─────────────────────┘
```

Pipeline per platform: **collect → embed/index → aggregate → report**.
Each stage is a standalone CLI under `tools/`; the MCP server orchestrates
them as background subprocesses, persists outputs to `data/cache/`, and the
console reads them back via the MCP REST API.

---

## Repo layout

```
.
├── docker-compose.yml          # Two services: mcp + console
├── .env.example                # Copy to .env, fill via console
├── services/
│   ├── mcp/                    # FastMCP server (Python, FastAPI, FastMCP)
│   └── console/                # React+Vite SPA + FastAPI backend
│       ├── app/                # Backend: providers, routers, env_store
│       └── web/                # Frontend: pages, components, i18n locales
└── tools/
    ├── reddit-ops/             # Node — Reddit OAuth pipeline (v2)
    ├── social-ops/             # Python — Instagram/Facebook/X/App-store
    ├── google-play-scraper/    # Node — google-play-scraper CLI wrapper
    └── app-store-scraper/      # Node — app-store-scraper CLI wrapper
```

---

## Configuration

All credentials are managed via the console's **Settings → Providers** tab
(or directly in `.env` if you prefer). Each provider has a built-in guide
explaining where to find the keys and a live "Test connection" button.

| Provider                     | Required for                                                  | Cost                                |
|------------------------------|---------------------------------------------------------------|-------------------------------------|
| **Reddit API**               | `analyze_reddit`                                              | Free (60 RPM per OAuth app)         |
| **Apify**                    | `analyze_instagram`, `analyze_facebook`, `analyze_appstore_reviews` | Freemium ($5/mo credit on free tier) |
| **Instagram session cookie** | `analyze_instagram` (Instaloader fallback)                    | Free, throwaway account recommended |
| **X (Twitter) session cookie** | `analyze_x`                                                 | Free, throwaway account recommended |

Google Play review analysis works without any credentials.

`.env` is `.gitignore`'d. Test credentials never leave your machine — the
console only contacts a provider when **you** click **Test connection**.

---

## UI

Available in **English / 中文 / 日本語 / 한국어 / Français / Deutsch**
(switch from the header dropdown; preference persists in `localStorage`).

- `/reports` — searchable / platform-filterable report library, KPI tiles
- `/reports/:handle_id` — full markdown report with sentiment bar + topic chips
- `/tasks` — live task table, auto-refresh every 5s
- `/settings` — sub-tabs:
  - **Providers** — credential cards with live validators + per-provider guide
  - **Connect** — MCP endpoint URL + copy-paste install snippets for Claude
    Code / Claude Desktop / Cursor / Continue.dev / custom HTTP
  - **About** — system info

---

## Security

> **The core ships without authentication.** This is intentional — the
> console binds to `127.0.0.1:8088` and the MCP server to `127.0.0.1:8097`
> by default, expecting a single-user, single-machine deployment.

If you want to expose either service to the network or the internet,
**add your own authentication** via:

- A reverse proxy (nginx / Caddy / Cloudflare Tunnel with Access)
- Tailscale or similar mesh VPN — limits exposure to your devices
- An OAuth proxy (oauth2-proxy, etc.) in front of the console

Pull requests that add auth as a hard project dependency will be declined;
keeping the core unopinionated about deployment is a design goal.

Report security issues privately — see [`SECURITY.md`](SECURITY.md) when
present, or open a private GitHub Security Advisory.

---

## Development

### Running the console frontend in dev mode

```bash
cd services/console/web
npm install
npm run dev    # Vite on :5173, proxies /api/* to :8088
```

The Vite dev server proxies `/api/*` to the running console container, so
you get live HMR while still hitting the real backend.

### Running collection scripts directly

Each tool ships as a standalone CLI:

```bash
# Reddit (after `cp .env.example .env` + filling REDDIT_*)
cd tools/reddit-ops
bash install.sh
node reddit-collect.mjs --subs "python,LocalLLaMA" --window 30d

# Instagram via Apify
cd tools/social-ops
bash install.sh
python3 insta_collect_apify.py --accounts "nike" --window 7d --max_posts 10
```

See each tool's README for full flag documentation.

---

## License

MIT — see [`LICENSE`](LICENSE).

---

## Acknowledgements

Built on top of [FastMCP](https://github.com/jlowin/fastmcp),
[FastAPI](https://github.com/fastapi/fastapi),
[React](https://github.com/facebook/react) +
[Vite](https://github.com/vitejs/vite),
[Instaloader](https://github.com/instaloader/instaloader), the Apify ecosystem,
[xreach-cli](https://github.com/Panniantong/xfetch), and the
[google-play-scraper](https://github.com/facundoolano/google-play-scraper) /
[app-store-scraper](https://github.com/facundoolano/app-store-scraper) libraries.

For the full dependency list with licenses, see
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).

Social-ops

Social-ops Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Social-ops

Social-ops Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README