twitterapi-io-mcp 1.0.9 → 1.0.10

package/README.md

@@ -1,8 +1,8 @@
 # twitterapi-io-mcp
 
 **npm packages**
-- `twitterapi-io-mcp` (recommended)
-- `twitterapi-docs-mcp` (legacy compatibility wrapper)
+- `twitterapi-io-mcp` (recommended, canonical)
+- `twitterapi-docs-mcp` (deprecated compatibility wrapper → delegates to `twitterapi-io-mcp`)
 
 [![npm version](https://img.shields.io/npm/v/twitterapi-io-mcp.svg)](https://www.npmjs.com/package/twitterapi-io-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/twitterapi-io-mcp.svg)](https://www.npmjs.com/package/twitterapi-io-mcp)
@@ -32,7 +32,7 @@ I'm sharing this with the community because if it helped me, it might help you t
 
 ## Features
 
-- **52 API endpoints** documented
+- **54 API endpoints** documented
 - **Site + docs pages** via sitemap + internal link crawl (pricing, QPS limits, privacy, contact, terms, acceptable use, dashboard, etc.)
 - **Blog posts** via blog index crawl (and internal discovery)
 - **Offline-first** - Works without network access
@@ -41,8 +41,16 @@ I'm sharing this with the community because if it helped me, it might help you t
 
 ## Installation
 
+**Prerequisites**
+- Node.js `>=18.18.0` (required to run the MCP server)
+- Claude Code users: the `claude` CLI installed (for `claude mcp add`)
+
+Note: This MCP server serves an **offline docs snapshot**. You do **not** need a TwitterAPI.io key just to use the docs tools.
+
 ### Claude Desktop
 
+Requires Node.js `>=18.18.0` (because this runs via `npx`).
+
 Add to your Claude Desktop configuration file:
 
 **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -61,12 +69,17 @@ Add to your Claude Desktop configuration file:
 
 ### Claude Code
 
+Requires Node.js `>=18.18.0` (because this runs via `npx`).
+
 ```bash
 # Add globally (all projects)
 claude mcp add --scope user twitterapi-io -- npx -y twitterapi-io-mcp
 
 # Or add to current project only
 claude mcp add twitterapi-io -- npx -y twitterapi-io-mcp
+
+# Legacy name (still works, but deprecated)
+claude mcp add --scope user twitterapi-docs -- npx -y twitterapi-docs-mcp
 ```
 
 Verify installation:
@@ -74,6 +87,11 @@ Verify installation:
 claude mcp list
 ```
 
+Troubleshooting:
+- `claude: command not found` → install Claude Code / the `claude` CLI first
+- `npx` fails or shows syntax errors → upgrade Node.js to `>=18.18.0`
+- Corporate networks → ensure npm can reach the registry (or configure your proxy/registry)
+
 ## Available Tools
 
 | Tool | Description |
@@ -88,6 +106,8 @@ claude mcp list
 
 ## Available Resources
 
+Note: resources are optional. The canonical guide fetch is `get_twitterapi_guide` (e.g., `guide_name: "changelog"`).
+
 | Resource URI | Description |
 |--------------|-------------|
 | `twitterapi://guides/pricing` | Pricing guide |
@@ -99,6 +119,70 @@ claude mcp list
 | `twitterapi://endpoints/list` | Full endpoint listing |
 | `twitterapi://status/freshness` | Data freshness status |
 
+## MCP Tool Recipes
+
+If you’re evaluating this MCP via Context7 or want copy/pasteable “tool chaining” patterns, see `CONTEXT7.md`.
+
+Focused, single-purpose recipes are in `recipes/` (e.g. `recipes/01-auth-summary.md`, `recipes/07-rate-limits.md`).
+
+Common workflows:
+- **Rate limits**: `search_twitterapi_docs` (`"rate limit qps"`) → `get_twitterapi_guide` (`"qps_limits"`)
+- **Typos are OK**: `search_twitterapi_docs` is fuzzy/typo-tolerant (e.g., `"twet object"`)
+- **Tweets Lookup**: `get_twitterapi_endpoint` (`"get_tweet_by_ids"`)
+
+## Context7 Quick Recipes (copy/paste)
+
+### Search → refine → endpoint details (Q2)
+
+```json
+{ "tool": "search_twitterapi_docs", "arguments": { "query": "advanced search", "max_results": 10 } }
+```
+
+Filter to `type: "endpoint"` results. If none, retry with a narrower query like `"advanced search endpoint"`.
+Then fetch details using the returned `name`:
+
+```json
+{ "tool": "get_twitterapi_endpoint", "arguments": { "endpoint_name": "tweet_advanced_search" } }
+```
+
+### Changelogs via `get_twitterapi_guide` (Q7)
+
+```json
+{ "tool": "get_twitterapi_guide", "arguments": { "guide_name": "changelog" } }
+```
+
+### Tweets Lookup endpoint details (Q9)
+
+```json
+{ "tool": "get_twitterapi_endpoint", "arguments": { "endpoint_name": "get_tweet_by_ids" } }
+```
+
+### Auth metadata (Q1)
+
+```json
+{ "tool": "get_twitterapi_auth", "arguments": {} }
+```
+
+Endpoint details also include an `auth` block (header/base URL). For per-endpoint extras, scan `description`/`parameters` for `login_cookie` or `proxy`.
+
+### Authentication page snapshot (Q6)
+
+```json
+{ "tool": "get_twitterapi_url", "arguments": { "url": "/documentation/authentication" } }
+```
+
+Fallback if the snapshot is missing:
+
+```json
+{ "tool": "get_twitterapi_guide", "arguments": { "guide_name": "authentication" } }
+```
+
+### Pagination search (Q5)
+
+```json
+{ "tool": "search_twitterapi_docs", "arguments": { "query": "pagination cursor next_cursor", "max_results": 10 } }
+```
+
 ## Usage Examples
 
 Once installed, you can ask Claude questions like:
@@ -114,15 +198,16 @@ Once installed, you can ask Claude questions like:
 
 | Category | Count | Examples |
 |----------|-------|----------|
-| **User** | 9 | get_user_by_username, get_user_followers, get_user_followings |
-| **Tweet** | 7 | tweet_advanced_search, get_tweet_reply, get_tweet_quote |
-| **Community** | 5 | get_community_by_id, get_community_members |
+| **User** | 11 | get_user_by_username, get_user_followers, batch_get_user_by_userids |
+| **Tweet** | 7 | tweet_advanced_search, get_tweet_by_ids, get_tweet_quote |
+| **Community** | 9 | create_community_v2, get_community_by_id, join_community_v2 |
 | **Webhook** | 4 | add_webhook_rule, get_webhook_rules |
-| **Stream** | 2 | add_user_to_monitor_tweet |
-| **Action** | 16 | create_tweet, like_tweet, follow_user_v2 |
+| **Stream** | 2 | add_user_to_monitor_tweet, remove_user_to_monitor_tweet |
+| **Action** | 15 | create_tweet_v2, like_tweet_v2, upload_media_v2 |
 | **DM** | 2 | send_dm_v2, get_dm_history_by_user_id |
 | **List** | 2 | get_list_followers, get_list_members |
 | **Trend** | 1 | get_trends |
+| **Other** | 1 | get_space_detail |
 
 ## How It Works