Content
# EasyAgent-SocialMedia
**Break down the internet social platform capabilities of AI Agent into independent MCP servers, rather than stuffing them into a large, unified framework.**
> `EasyAgent` is a series of lightweight MCP toolsets.
> `SocialMedia` is the first set in this series: Bilibili, X, Xiaohongshu, and Reddit.
> **If you want to learn about the project, read on. If you just want to get this MCP service, directly request your AI Agent instead of reading this document.**
---
```
Clean data (transparent) Data cleaning required (extraction / deduplication)
───────────────── ─────────────────────────
Zero configuration (public API) A-1: Bilibili A-2: Template ready
Login required (Cookie/CLI) B-1: X, Reddit B-2: Xiaohongshu
```
Each MCP server is an independent process, does not affect each other, starts on demand, and has zero token injection.
---
## Story
> Inspired by [Agent-Reach](https://github.com/Panniantong/Agent-Reach), an excellent project that allows your AI Agent to read 15 internet platforms, with one-click installation, testing, and routing.
>
> But in actual use, I found a problem: **it's too heavy.**
>
> The framework itself, plus detection logic for all channels, SKILL.md, and 6 references, injects ~30KB of tokens for each conversation, and unnecessary platforms take up space. I only need three platforms (Bilibili, X, and Xiaohongshu), and I don't want to pay for the entire framework.
>
> I proposed breaking it down into independent MCP servers - one for each platform, process-isolated, and loaded on demand. My AI assistant (Hermes Agent) is responsible for implementation: writing code, setting up templates, and doing normalization.
>
> **The result exceeded expectations:**
> - MCP is an independent process, does not occupy context, and does not consume tokens
> - Each server is self-contained, and you can choose which one to use
> - Unified OpenCLI backend + search engine fallback, abandoned independent CLI
> - One server crashing does not affect others
>
> As I continued to use it, Reddit was also added. The code gradually became standardized, forming a "four-quadrant classification" template system.
>
> This is the origin of EasyAgent-SocialMedia - **not another framework, but a set of MCP servers that you can freely combine, each doing one thing but doing it well.**
## Architecture
```bash
Hermes Agent / Claude Code / Codex / Cursor …
│
MCP Gateway (process-isolated, on-demand startup)
│
├── bilibili-mcp → [A] Public API → Automatic downgrade to OpenCLI → Search engine fallback
├── x-mcp → [B] OpenCLI → [Cookie failure] Search engine fallback
├── xiaohongshu-mcp → [B] OpenCLI → [Cookie failure] Search engine fallback
└── reddit-mcp → [B] OpenCLI → [Cookie failure] Search engine fallback
```
Each MCP server's internal backend detection and downgrade logic is self-contained and independent.
## Four-Quadrant Classification
| Quadrant | Login | Data Cleaning | Example |
|------|------|---------|------|
| **A-1** | No login required | No cleaning required (direct transmission) | Bilibili (public API) |
| **A-2** | No login required | **Cleaning required** | Template ready (Zhihu, etc.) |
| **B-1** | **Login required** | No cleaning required | X, Reddit |
| **B-2** | **Login required** | **Cleaning required** | Xiaohongshu |
Each MCP file header is labeled with `CLASS` + `CLEAN`, and the `doctor()` output also includes these two fields.
## Finished Product Overview
| MCP | Class | File | Chain |
|-----|-----|------|------|
| bilibili-mcp | A | `servers/bilibili_mcp.py` | Public API → Automatic downgrade to OpenCLI → Search engine fallback |
| x-mcp | B | `servers/x_mcp.py` | OpenCLI → [Cookie failure] Search engine fallback |
| xiaohongshu-mcp | B-2 | `servers/xiaohongshu_mcp.py` | OpenCLI → [Cookie failure] Search engine fallback |
| reddit-mcp | B | `servers/reddit_mcp.py` | OpenCLI → [Cookie failure] Search engine fallback |
Each MCP server provides 4-5 tools (search, details, comments, status diagnosis), all derived from the same template.
## One-Click Startup
After downloading this project, tell your AI Agent:
> "Help me configure EasyAgent-SocialMedia, the project is in [path]/EasyAgent-SocialMedia."
The Agent should follow these steps:
### Agent Installation Process
```plaintext
1. Read this README, understand the project structure
2. Ask the user: Which platforms do you need to configure? (e.g., Bilibili, X, Xiaohongshu, Reddit)
3. Based on the user's selection, operate according to the following rules:
- [Class A] Zero configuration, direct registration and use
- [Class B] First, install OpenCLI using `npm install -g @jackwener/opencli`, then register
4. After all registrations are completed, call each MCP's `doctor()` to confirm the status
5. Inform the user that they need to install the Chrome extension, **provide a direct, clickable link**:
https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk
6. After the user installs the extension and logs in to the corresponding website, call `doctor()` to verify
7. List the verification results:
✅ Logged-in platforms (can be used directly)
❌ Unlogged platforms (each provides a root domain clickable link for the user to log in)
```
> **Agent Key Points:** The installation of OpenCLI (`npm install -g @jackwener/opencli`) is automatically executed by you, and the user does not need to do it manually.
> The user only needs to do two things: install the Chrome extension and log in to the website. When the user says "installed", call `doctor()` to confirm availability.
### Registration Command Reference
```bash
# Agent executes automatically, no need for user manual input
hermes mcp add bilibili-mcp --command python --args {project path}/servers/bilibili_mcp.py
hermes mcp add x-mcp --command python --args {project path}/servers/x_mcp.py
hermes mcp add xiaohongshu-mcp --command python --args {project path}/servers/xiaohongshu_mcp.py
hermes mcp add reddit-mcp --command python --args {project path}/servers/reddit_mcp.py
```
### User Experience
```plaintext
You: "Help me configure EasyAgent-SocialMedia, the project is in ~/EasyAgent-SocialMedia"
Agent: "Okay, which platforms do you need? Bilibili, X, Xiaohongshu, Reddit?"
You: "Bilibili and X"
Agent: "Bilibili is ready. Installing OpenCLI... Done.
Please install the Chrome extension (click the link to install):
https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk
Then log in to the corresponding website in Chrome and tell me when you're done."
You: "Done"
Agent: Call `doctor()` → "The readiness status is as follows:
✅ Bilibili — Zero configuration, directly available
✅ X — Logged in, can be searched directly
❌ Xiaohongshu — Not configured, please tell me if you need it
Quick link: https://x.com"
You: "Okay, that's enough"
```
## Template Structure
```
template/mcp_template.py
├── Meta-information (SERVER_NAME / CLASS / CLEAN / BACKENDS)
├── [B Series] Configuration management (Cookie/Token reading)
├── [Quadrant 2] Data cleaning (_clean_item / _clean_items)
├── Backend detection (_check_* / _CHECK_FUNCS / doctor)
├── Business functions (select mode by quadrant)
└── MCP protocol layer (universal, no need to change)
```
## Appendix: Manual Registration Reference
The following commands are only for understanding what the Agent does behind the scenes. Normally, you don't need to execute them manually - just tell the Agent one sentence, and it will do it for you.
```bash
# Register Bilibili (zero configuration, directly available)
hermes mcp add bilibili-mcp --command python --args /path/to/servers/bilibili_mcp.py
# Install OpenCLI (unlock login status for X + Xiaohongshu + Reddit)
npm install -g @jackwener/opencli
# Install Chrome extension: https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk
# Register other platforms
hermes mcp add x-mcp --command python --args /path/to/servers/x_mcp.py
hermes mcp add xiaohongshu-mcp --command python --args /path/to/servers/xiaohongshu_mcp.py
hermes mcp add reddit-mcp --command python --args /path/to/servers/reddit_mcp.py
```
### Extension Process (Create a New MCP from Template)
1. Copy template: `cp template/mcp_template.py servers/new_platform_mcp.py`
2. Set `CLASS` (A=zero configuration/B=login required), `CLEAN` (True=cleaning required), `BACKENDS`, `SEARCH_DOMAIN`
3. Implement business functions (refer to template A/B mode examples)
4. Register with the gateway (the Agent will automatically execute this step)
The MCP protocol layer (TOOLS / handle_call / main) is universal for all platforms, **copy and use without modification**.
## Comparison with Agent-Reach
| Dimension | Agent-Reach | EasyAgent-SocialMedia |
|------|------------|------------|
| Architecture | Large unified framework + 15 channels | **Independent MCP servers, combined on demand** |
| Token overhead | ~30KB (skill + refs) | **0** (MCP is an independent process) |
| Process model | Single process | **Multi-process, isolated operation** |
| Dependency | pip install agent-reach | **Zero framework dependency, only install underlying CLI** |
| Extension | Modify project code | **Add an MCP server configuration** |
| Maintenance | Wait for upstream updates | **Independent, repair which one** |
## Tools Reference
| Tool | Purpose | Applicable MCP |
|------|------|---------|
| `bilibili_search` / `bilibili_hot` / `bilibili_video` | Search / Hot / Details | bilibili-mcp |
| `twitter_search` / `twitter_tweet` / `twitter_user` | Search / Read tweets / User | x-mcp |
| `xiaohongshu_search` / `xiaohongshu_note` / `xiaohongshu_comments` | Search / Notes / Comments | xiaohongshu-mcp |
| `reddit_hot` / `reddit_search` / `reddit_post` / `reddit_subreddit` | Hot / Search / Read / Subreddit | reddit-mcp |
| `doctor` | Backend status diagnosis | All |
## License
MIT
