X-Go

A Go library and HTTP server for interacting with Twitter/X using the github.com/imperatrona/twitter-scraper package.

Account Management

The library supports managing multiple Twitter accounts with cookie persistence. Here's how it works:

1. Create an accounts.json file in the XGO path (default: $HOME/x-go) with your Twitter accounts:

   [
       {
           "username": "your_twitter_username",
           "password": "your_twitter_password"
       }
   ]
   

2. When the server starts:

   • It checks for existing cookies in the cookies directory
   • If cookies exist, it tries to use them for authentication
   • If cookies are invalid or don't exist, it logs in using the credentials from accounts.json
   • After successful login, it saves the cookies to cookies/{username}.json

Environment Variables

• XGO_PATH: Path to the X-Go directory (default: $HOME/x-go)

API Endpoints

Public Endpoints (No Login Required)

• GET /api/user/{username}/tweets - Get user tweets
• GET /api/user/{username}/profile - Get user profile
• GET /api/tweet/{id} - Get tweet by ID

Authenticated Endpoints (Login Required)

• GET /api/search?q={query} - Search tweets
• POST /api/follow/{id} - Follow user
• POST /api/unfollow/{id} - Unfollow user
• POST /api/tweet - Create tweet
• POST /api/tweet/{id}/like - Like tweet
• POST /api/tweet/{id}/unlike - Unlike tweet
• POST /api/tweet/{id}/retweet - Retweet

MCP Server

The project implements a Multi-Agent Communication Protocol (MCP) server that provides programmatic access to Twitter functionality through standardized agent communication.

MCP Server Features

• Manages multiple Twitter agents with session persistence
• Provides tool-based interaction with Twitter API
• Supports middleware for request handling
• Includes logging and recovery capabilities

Environment Variables

• XGO_PATH: Path to the X-Go directory (default: $HOME/x-go) - Required for agent management and cookie storage

Running as MCP Server

1. Ensure XGO_PATH environment variable is set
2. Configure your Twitter accounts in accounts.json
3. Run the MCP server:

   go run main.go
   

The server will start and handle MCP protocol communication through stdin/stdout.

Building and Running Servers

This project supports two server modes: HTTP API server and MCP server.

Building the Servers

1. Build the HTTP server:

   go build -o x-go-http cmd/httpserver/main.go
   

2. Build the MCP server:

   go build -o x-go-mcp main.go
   

Running HTTP Server

1. Copy accounts.json.example to accounts.json and add your Twitter accounts
2. Set environment variables:

   export XGO_PATH=$HOME/x-go
   

3. Run the server:

   ./x-go-http
   

The HTTP server will start on port 8080.

Running MCP Server

1. Ensure accounts.json is configured with your Twitter accounts
2. Set environment variables:

   export XGO_PATH=$HOME/x-go
   

3. Run the server:

   ./x-go-mcp
   

The MCP server will handle communication through stdin/stdout using the MCP protocol.

Docker Support

You can also run the servers using Docker. Both servers use a Docker volume to persist data and configurations.

1. Build HTTP server image:

   docker build -f Dockerfile.http -t x-go-http .
   

2. Build MCP server image:

   docker build -f Dockerfile.mcp -t x-go-mcp .
   

3. Create a Docker volume for data persistence (optional):

   docker volume create x-go-data
   

4. Run HTTP server container:

   # Using a named volume
   docker run -p 8080:8080 \
     -v x-go-data:/x-go \
     x-go-http
   
   # OR using a local directory
   docker run -p 8080:8080 \
     -v $HOME/x-go:/x-go \
     x-go-http
   

5. Run MCP server container:

   # Using a named volume
   docker run -i \
     -v x-go-data:/x-go \
     x-go-mcp
   
   # OR using a local directory
   docker run -i \
     -v $HOME/x-go:/x-go \
     x-go-mcp
   

The volume at /x-go contains:

• accounts.json: Twitter account credentials
• cookies/: Directory storing authentication cookies
• Other persistent data generated by the application

Note:

• The -v flag mounts the volume to persist data between container restarts
• Using a named volume (x-go-data) is recommended for production
• Using a local directory mount is useful for development
• The same volume can be shared between HTTP and MCP servers if needed