spectre-mcp 1.1.0__tar.gz

spectre_mcp-1.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual env
+.venv/
+venv/
+
+# Data files (user-specific)
+*.db
+accounts.db
+spectre.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local

spectre_mcp-1.1.0/.python-version

@@ -0,0 +1 @@
+3.11

spectre_mcp-1.1.0/PKG-INFO

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: spectre-mcp
+Version: 1.1.0
+Summary: X/Twitter automation for AI agents — 83 MCP tools. Search, post, media upload, DMs, scheduled tweets, drafts, bookmark folders, lists, communities, topics, community notes, account settings, profile management. No paid API keys.
+Author: Pranjal Richhariya
+License-Expression: MIT
+Keywords: agent,ai-agent,automation,mcp,scraper,social-media,twitter,x
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: curl-cffi>=0.15.0
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: twscrape>=0.19.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Spectre MCP
+
+**The fastest X/Twitter automation for AI agents.**
+
+83 tools · Direct API calls · Cookie auth · No browser needed · Account pool with auto-rotation
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-8B5CF6?style=flat-square)](https://modelcontextprotocol.io)
+
+[Quick Start](#-quick-start) · [Why Spectre?](#-why-spectre) · [All 83 Tools](#all-83-tools) · [Safety Guide](#%EF%B8%8F-safety-guide-for-ai-agents) · [Comparison](#-how-spectre-compares)
+
+</div>
+
+---
+
+## Why Spectre?
+
+> Spectre makes **direct HTTP calls** to X's internal GraphQL and REST APIs. No browser, no Puppeteer, no DOM scraping. It's the fastest and lightest way for AI agents to automate X/Twitter.
+
+| | **Spectre** | **XActions** | **twikit** |
+|--|:-:|:-:|:-:|
+| **Architecture** | Direct GraphQL/REST API | Puppeteer (headless browser) | Python API wrapper |
+| **Speed** | <1s per request | 3-10s (browser startup + page load) | ~1s per request |
+| **Resource usage** | ~10MB (just HTTP client) | ~200MB+ (Chromium process) | ~10MB |
+| **MCP Server** | ✅ 83 real API tools | ⚠️ ~50 API tools + 40 AI wrappers | ❌ None |
+| **Account Pool** | ✅ Multi-account auto-rotation | ❌ Single auth_token | ❌ Single session |
+| **Browser Required** | ❌ Never | ✅ Always | ❌ Never |
+| **DOM Breakage Risk** | ❌ None (no DOM) | ⚠️ Breaks when X changes UI | ❌ None |
+| **Community Notes** | ✅ Create, read, rate | ❌ | ❌ |
+| **Bookmark Folders** | ✅ Full CRUD + timeline | ❌ Basic only | ❌ |
+| **Draft Tweets** | ✅ Create, list, delete | ❌ | ❌ |
+| **Scheduled Tweets** | ✅ Create, list, delete | ⚠️ Basic | ❌ |
+| **DM Search** | ✅ Search by text | ❌ | ❌ |
+| **Profile Highlights** | ✅ Create, delete, get | ❌ | ❌ |
+| **Pin/Unpin Tweet** | ✅ | ❌ | ❌ |
+| **Profile Image Upload** | ✅ Direct file upload | ⚠️ Basic update | ❌ |
+| **Destructive Tool Warnings** | ✅ Every tool marked ⚠️ | ❌ Generic disclaimer | ❌ |
+| **Language** | Python | JavaScript | Python |
+| **Install** | `uvx spectre-mcp` | `npm install xactions` | `pip install twikit` |
+
+**Spectre is the only MCP server that makes direct API calls with multi-account rotation.** No browser overhead, no DOM fragility, no wasted resources.
+
+---
+
+## Quick Start
+
+### 1. Install (10 seconds)
+
+```bash
+uvx spectre-mcp
+```
+
+### 2. Add Your Account
+
+```bash
+spectre add myaccount "auth_token=xxx; ct0=yyy"
+```
+
+> Get cookies: x.com → DevTools (F12) → Application → Cookies → copy `auth_token` and `ct0`
+
+### 3. Configure Your MCP Client
+
+**Hermes Agent** (`~/.hermes/config.yaml`):
+```yaml
+mcp_servers:
+  spectre:
+    command: "uvx"
+    args: ["spectre-mcp"]
+    timeout: 120
+```
+
+**Claude Desktop / Cursor** (`.json`):
+```json
+{
+  "mcpServers": {
+    "spectre": {
+      "command": "uvx",
+      "args": ["spectre-mcp"]
+    }
+  }
+}
+```
+
+### Example Prompts
+
+> **"Search for tweets about AI startups from the last week"**
+> → Calls `search("AI startups since:2026-06-15", mode="latest")`
+
+> **"Find everyone I follow who doesn't follow me back"**
+> → Calls `get_following` + `get_followers` → computes diff
+
+> **"Post a tweet with an image, then pin it to my profile"**
+> → Calls `upload_media` → `post_tweet(media_ids=...)` → `pin_tweet`
+
+> **"Update my bio to 'Building in public' and change my avatar"**
+> → Calls `update_profile(bio="Building in public")` + `update_profile_image(path)`
+
+> **"Search my DMs for 'meeting' and send a follow-up"**
+> → Calls `search_dm("meeting")` → `send_dm(user_id, "Following up on...")`
+
+---
+
+## All 83 Tools
+
+### Account Pool (5)
+
+| Tool | Description |
+|------|-------------|
+| `list_accounts()` | List all accounts with status |
+| `set_active_account(username)` | Set primary account |
+| `set_auto_rotate(enabled)` | Enable/disable auto-rotation on rate limits |
+| `remove_account(username)` | Remove account from pool |
+| `pool_status()` | Pool health stats |
+
+### Search (2)
+
+| Tool | Description |
+|------|-------------|
+| `search(query, limit, mode)` | Search tweets. Supports `from:username`, `since:2026-01-01`, `#hashtag`, `filter:media` |
+| `search_users(query, limit)` | Search users by name/keyword |
+
+### Users (5)
+
+| Tool | Description |
+|------|-------------|
+| `get_user(username)` | User profile by @handle |
+| `get_user_tweets(username, limit)` | User's recent tweets |
+| `get_user_media(username, limit)` | User's photos/videos/GIFs |
+| `get_followers(username, limit)` | User's followers |
+| `get_following(username, limit)` | Who a user follows |
+
+### Tweets (4)
+
+| Tool | Description |
+|------|-------------|
+| `get_tweet(tweet_id)` | Single tweet by ID |
+| `get_tweet_replies(tweet_id, limit)` | Replies to a tweet |
+| `get_thread(tweet_id, limit)` | Full conversation thread |
+| `get_retweeters(tweet_id, limit)` | Users who retweeted |
+
+### Timeline & Discovery (3)
+
+| Tool | Description |
+|------|-------------|
+| `get_trends(category, limit)` | Trending topics |
+| `get_home_timeline(limit)` | Home feed |
+| `get_bookmarks(limit)` | Your bookmarked tweets |
+
+### Post & Media (3)
+
+| Tool | Description |
+|------|-------------|
+| `post_tweet(text, reply_to?, quote_tweet?, media_ids?)` | Post a tweet with optional media |
+| `upload_media(file_path)` | Upload image or video (jpg, png, gif, mp4, mov) |
+| `delete_tweet(tweet_id)` | ⚠️ Delete a tweet |
+
+### Engagement (6)
+
+| Tool | Description |
+|------|-------------|
+| `like_tweet(tweet_id)` / `unlike_tweet(tweet_id)` | Like/unlike |
+| `retweet(tweet_id)` / `unretweet(tweet_id)` | Retweet/undo |
+| `bookmark_tweet(tweet_id)` / `unbookmark_tweet(tweet_id)` | Bookmark/undo |
+
+### Social (6)
+
+| Tool | Description |
+|------|-------------|
+| `follow_user(user_id)` / `unfollow_user(user_id)` | ⚠️ Follow/unfollow |
+| `mute_user(user_id)` / `unmute_user(user_id)` | Mute/unmute |
+| `block_user(user_id)` / `unblock_user(user_id)` | ⚠️ Block/unblock |
+
+### DMs (6)
+
+| Tool | Description |
+|------|-------------|
+| `send_dm(user_id, text)` | ⚠️ Send a direct message |
+| `get_dm_inbox(limit)` | List DM conversations |
+| `get_dm_conversation(conversation_id, limit)` | Read messages in a conversation |
+| `search_dm(query, limit)` | Search DMs by text |
+| `dm_block_user(user_id)` / `dm_unblock_user(user_id)` | Block/unblock in DMs |
+
+### Scheduled Tweets (3)
+
+| Tool | Description |
+|------|-------------|
+| `schedule_tweet(text, execute_at, reply_to?)` | Schedule a tweet for future posting |
+| `get_scheduled_tweets()` | List all scheduled tweets |
+| `delete_scheduled_tweet(tweet_id)` | ⚠️ Delete a scheduled tweet |
+
+### Draft Tweets (3)
+
+| Tool | Description |
+|------|-------------|
+| `create_draft(text)` | Save a tweet draft |
+| `get_drafts()` | List all drafts |
+| `delete_draft(tweet_id)` | ⚠️ Delete a draft |
+
+### Bookmark Folders (7)
+
+| Tool | Description |
+|------|-------------|
+| `get_bookmark_folders()` | List all bookmark folders |
+| `create_bookmark_folder(name)` | Create a folder |
+| `delete_bookmark_folder(folder_id)` | ⚠️ Delete a folder |
+| `edit_bookmark_folder(folder_id, name)` | Rename a folder |
+| `add_tweet_to_folder(folder_id, tweet_id)` | Add tweet to folder |
+| `remove_tweet_from_folder(folder_id, tweet_id)` | Remove tweet from folder |
+| `get_bookmark_folder_timeline(folder_id, limit)` | Get tweets in a folder |
+
+### Lists (7)
+
+| Tool | Description |
+|------|-------------|
+| `get_list_timeline(list_id, limit)` | Tweets from a list |
+| `get_list_members(list_id, limit)` | Members of a list |
+| `create_list(name, description)` | Create a new list |
+| `update_list(list_id, name, description)` | Update list details |
+| `delete_list(list_id)` | ⚠️ Delete a list |
+| `add_list_member(list_id, user_id)` | Add user to list |
+| `remove_list_member(list_id, user_id)` | Remove user from list |
+
+### Communities (4)
+
+| Tool | Description |
+|------|-------------|
+| `get_community_tweets(community_id, limit)` | Community feed |
+| `get_community_info(community_id)` | Community details |
+| `join_community(community_id)` | Join a community |
+| `leave_community(community_id)` | ⚠️ Leave a community |
+
+### Topics (2)
+
+| Tool | Description |
+|------|-------------|
+| `follow_topic(topic_id)` | Follow a topic |
+| `unfollow_topic(topic_id)` | Unfollow a topic |
+
+### Community Notes (3)
+
+| Tool | Description |
+|------|-------------|
+| `create_community_note(tweet_id, text)` | Create a note on a tweet |
+| `get_community_notes(tweet_id)` | Get notes on a tweet |
+| `rate_community_note(note_id, rating)` | Rate a note as helpful/not helpful |
+
+### Account Settings (5)
+
+| Tool | Description |
+|------|-------------|
+| `get_account_settings()` | View account settings (language, timezone, etc.) |
+| `update_profile(name?, bio?, location?, website?)` | ⚠️ Update profile info |
+| `update_profile_image(file_path)` | ⚠️ Change avatar image |
+| `update_profile_banner(file_path)` | ⚠️ Change banner image |
+| `delete_profile_banner()` | ⚠️ Remove banner |
+
+### Pin & Highlights (5)
+
+| Tool | Description |
+|------|-------------|
+| `pin_tweet(tweet_id)` | ⚠️ Pin tweet to profile (replaces existing pin) |
+| `unpin_tweet(tweet_id)` | Unpin tweet |
+| `create_highlight(tweet_ids)` | ⚠️ Add tweets to profile highlights |
+| `delete_highlight(highlight_id)` | ⚠️ Remove a highlight |
+| `get_user_highlights(user_id, limit)` | Get user's highlighted tweets |
+
+### Safety & Privacy (4)
+
+| Tool | Description |
+|------|-------------|
+| `get_muted_accounts(limit)` | List all muted accounts |
+| `get_blocked_accounts(limit)` | List all blocked accounts |
+| `get_verified_followers(user_id, limit)` | Get Blue-verified followers |
+| `get_user_likes(user_id, limit)` | Get a user's liked tweets |
+
+---
+
+## ⚠️ Safety Guide for AI Agents
+
+Spectre marks every destructive tool with **⚠️** in its docstring. Agents should respect these warnings.
+
+### Always Confirm Before Calling
+
+| Tool | Why |
+|------|-----|
+| `update_profile` | Changes your public bio/name/website immediately |
+| `update_profile_image` / `update_profile_banner` | Replaces existing images |
+| `pin_tweet` | Replaces any existing pinned tweet |
+| `post_tweet` | Tweets are public and live immediately |
+| `delete_tweet` | Permanent, cannot be undone |
+| `follow_user` / `unfollow_user` | Visible to the other user |
+| `block_user` | The blocked user loses access to your content |
+| `send_dm` | Messages are sent immediately, no recall |
+
+### Safe to Use Freely (Read-Only)
+
+All `get_*`, `search_*`, `list_*` tools. `pool_status`, `get_muted_accounts`, `get_blocked_accounts`, `get_scheduled_tweets`, `get_drafts`, `get_bookmarks`, `get_trends`, `get_home_timeline`.
+
+### Rate Limits
+
+- ~300 requests/hour/account
+- Spectre auto-rotates to the next account when one hits a rate limit
+- Use `set_auto_rotate(false)` to lock to a single account
+- Rate limit errors include `retry_after_seconds`
+
+---
+
+## X Query Operators
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `from:username` | `from:elonmusk` | Tweets by a user |
+| `since:YYYY-MM-DD` | `since:2026-01-01` | After date |
+| `until:YYYY-MM-DD` | `until:2026-06-01` | Before date |
+| `#hashtag` | `#python` | Hashtag search |
+| `filter:media` | `AI filter:media` | Only media tweets |
+| `filter:links` | `AI filter:links` | Only tweets with links |
+| `lang:en` | `AI lang:en` | Language filter |
+| `min_retweets:N` | `AI min_retweets:100` | Minimum retweets |
+| `min_faves:N` | `AI min_faves:50` | Minimum likes |
+| `-"term"` | `AI -"GPT"` | Exclude term |
+| `OR` | `python OR rust` | Either term |
+
+---
+
+## CLI
+
+```bash
+spectre add <username> <cookies>     Add account via browser cookies
+spectre remove <username>            Remove an account
+spectre list                         List all accounts
+spectre status                       Pool health check
+spectre serve                        Start MCP server (default)
+spectre help                         Show help
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPECTRE_DB` | `~/.spectre/accounts.db` | Account pool path |
+| `SPECTRE_PROXY` | none | Global proxy (`socks5://user:pass@host:port`) |
+| `TWS_HTTP_BACKEND` | `httpx` | Set to `curl` for TLS fingerprinting |
+| `TWS_TELEMETRY` | `0` | Disable telemetry |
+| `SPECTRE_OP_*` | built-in | Override GraphQL operation IDs (when they rotate) |
+
+---
+
+## Limitations
+
+- **Requires authenticated accounts** — X blocks unauthenticated access
+- **Rate limited** — ~300 requests/hour/account (rotation handles this)
+- **~3200 tweet cap** on user timelines (X's own limit)
+- **ToS risk** — automated access violates X's terms
+
+---
+
+## License
+
+MIT
+
+---
+
+<div align="center">
+
+**Built for AI agents, by an AI agent.**
+
+[GitHub](https://github.com/pranrichh/spectre-mcp) · [Issues](https://github.com/pranrichh/spectre-mcp/issues)
+
+</div>