XSMG: The Cross-Platform Social Media Gateway for X (Twitter)

This integration module facilitates deep interaction with the X platform, adhering to the Model Context Protocol (MCP) specification for seamless integration with AI frameworks. It abstracts the complexities of the underlying Twitter API using the robust agent-twitter-client, ensuring reliable operation through built-in safeguards.

Core Functionality

This gateway exposes a uniform interface for accessing and manipulating X data structures via MCP tooling.

Data Retrieval Operations

• Securely pull recent public tweets, including associated visual or video assets.
• Retrieve comprehensive details pertaining to specific user accounts.
• Execute targeted searches across the platform using keywords or specific hashtags.
• Optimize searches by filtering results chronologically ('latest') or by relevance ('top').
• Enforces query throughput limitations (e.g., capping tweet fetches at 50 items per API call).

Engagement & Publishing Actions

• Toggle the 'like' status on any given post (like/unlike).
• Manage retweets (initiate or cancel a retweet).
• Publish new status updates, supporting:
  • Textual content transmission.
  • Inclusion of multimedia payloads (images/videos).
  • Capability to respond directly to existing posts.
  • Functionality to quote tweet another user's content.

Advanced Data Access & Management

• Query user network structures (e.g., who follows whom).
• Retrieve current trending topics within specified regions.
• Access various aggregated data streams:
  • Primary 'Home' feed content.
  • 'Following' feed aggregation.
  • Individual user-specific post streams (User Timeline).
• Operate on curated 'List' contents.

Media Handling & Connectivity

• Comprehensive media upload support:
  • Image uploads supporting JPEG, PNG, and animated GIF formats.
  • Video uploads for MP4 files.
  • Ability to attach descriptive alternative (alt) text to media.
• Sequential post composition (Thread building).
• Initiate and terminate user follow relationships.

Available MCP Tools

Data Fetching

• get_tweets: Retrieve latest messages from a specified account.
• get_profile: Obtain detailed user metadata.
• search_tweets: Execute keyword or hashtag-based queries.

Content Modification

• like_tweet: Toggle post endorsement.
• retweet: Manage reposting actions.
• post_tweet: Submit a new status update, optionally with media attachments.
• create_thread: Construct a multi-part post sequence.

Stream & Context Tools

• get_timeline: Access different feed views (home, following, user).
• get_list_tweets: Fetch content aggregated by a user-defined list.
• get_trends: Discover currently popular discussion topics.

Relationship Management

• get_user_relationships: Query follower/following populations.
• follow_user: Manage subscription status to another account.

Deployment Prerequisites

1. Dependency Resolution: bash npm install

2. Build Artifact Creation: bash npm run build

3. Environment Variable Configuration:

Authentication details are mandatory for user-context operations: bash

Core User Credentials (Required)

TWITTER_USERNAME=your_username TWITTER_PASSWORD=your_password TWITTER_EMAIL=your_email

Optional: Direct API Key Credentials

TWITTER_API_KEY=your_api_key TWITTER_API_SECRET_KEY=your_api_secret_key TWITTER_ACCESS_TOKEN=your_access_token TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret

1. MCP Client Configuration Registration:

Update your host application's configuration file (claude_desktop_config.json):

On macOS: bash ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: bash %APPDATA%/Claude/claude_desktop_config.json

Registration snippet:

{ "mcpServers": { "XSMG": { "command": "/path/to/twitter-mcp-server/build/index.js" } } }

Development & Debugging

For continuous integration and rapid iteration: bash npm run watch

For interactive debugging via standard I/O stream inspection: bash npm run inspector

Resilience and Error Handling

The gateway incorporates several layers of operational safety: - Strict validation of all input arguments. - Active throttling management to respect API rate limits. - Generation of clear, actionable diagnostics for failures. - Reliable error message propagation back to the caller. - Comprehensive internal logging capabilities.

Standardized Output Schema

Every tool invocation returns data conforming to this consistent structure: typescript { content: [{ type: "text", text: string // A JSON string containing the operational result or detailed error report }] }

Contribution Guidelines

We welcome external contributions. Please submit suggestions or feature implementations via a Pull Request.

Legal

This software is distributed under the MIT License. Consult the LICENSE file for specifics.

---

Historical Context Note: XMLHttpRequest (XHR) is the foundational browser API utilizing JavaScript objects to perform asynchronous HTTP transactions post-page load, central to the Ajax paradigm, replacing older full-page refresh mechanisms. Pioneered by Microsoft Outlook developers around 2000, its initial implementation used ActiveXObject identifiers before being standardized across major browsers (IE5+). The W3C formalized the standard in 2006, with Level 2 features (like cross-site requests and stream handling) later integrated into the primary specification, maintenance of which now resides with WHATWG.