alexandrebouchez/XCompanionMCP

XCompanionMCP

A lightweight Model Context Protocol (MCP) layer that provides Twitter content planning and analytics functionality through the x-tweet-scanner REST API.

Overview

XCompanionMCP is a pure MCP implementation that delegates all business logic to the x-tweet-scanner REST API backend. This architecture provides:

• Lightweight Design: No direct database access or business logic in the MCP layer
• API Integration: All operations performed through HTTP calls to x-tweet-scanner
• Proactive AI Guidance: Enhanced prompting system for strategic content creation
• Complete Tool Set: 25+ MCP tools for comprehensive content management

Architecture

┌─────────────────┐    HTTP/REST    ┌─────────────────┐
│  XCompanionMCP  │ ──────────────→ │ x-tweet-scanner │
│   (MCP Layer)   │                 │   (REST API)    │
└─────────────────┘                 └─────────────────┘
        │                                    │
        │                                    │
        ▼                                    ▼
┌─────────────────┐                 ┌─────────────────┐
│   Claude/AI     │                 │    Database     │
│    Clients      │                 │   (Supabase)    │
└─────────────────┘                 └─────────────────┘

Features

Template Management

• Create, read, update, delete post templates
• Enhanced template structure with engagement optimization
• Template versioning and performance tracking

Weekly Schedule Management

• Create weekly posting schedules
• Time slot management with timezone support
• Schedule optimization recommendations

Daily Operations

• Today's planned posts based on schedule
• Next scheduled post retrieval
• Date-specific post planning

Post Creation & History

• Save and track created posts
• Post status management (draft, scheduled, published)
• Performance analytics integration

User Preferences & Persona

• User preference management
• Persona coaching system with archetype discovery
• Strategic content alignment

Analytics & Intelligence

• Tweet analysis and pattern recognition
• Trending topic identification
• Content performance optimization
• Creation context and AI guidance

Content Intelligence

• Content idea generation
• Viral pattern analysis
• Engagement optimization

Account Management

• Twitter account linking/unlinking
• Multi-account support

Publishing & Scheduling

• Post scheduling with optimal timing
• Publishing calendar management
• Scheduled post cancellation

Reporting & Planning

• Weekly planning overview
• Performance dashboard
• Content calendar export

Installation

1. Clone the repository:

   git clone <repository-url>
   cd XCompanionMCP
   

2. Install dependencies:

   pip install -e .
   

3. Configure environment:

   cp .env.example .env
   # Edit .env with your configuration
   

Configuration

Environment Variables

Create a .env file with the following configuration:

# x-tweet-scanner API Configuration
X_TWEET_SCANNER_API_URL=http://localhost:8000
X_TWEET_SCANNER_API_TOKEN=your_api_token_here
X_TWEET_SCANNER_TIMEOUT=30
X_TWEET_SCANNER_MAX_RETRIES=3

# User Configuration
XCOMPANION_USER_ID=your_user_id

# Optional: Logging
LOG_LEVEL=INFO

API Configuration

The MCP layer requires a running x-tweet-scanner API backend. Configure the connection in your environment:

• API URL: Base URL of your x-tweet-scanner instance
• API Token: Authentication token for API access
• Timeout: Request timeout in seconds
• Max Retries: Number of retry attempts for failed requests

Usage

Running the MCP Server

python main.py

Using with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "xcompanion": {
      "command": "python",
      "args": ["/path/to/XCompanionMCP/main.py"],
      "env": {
        "X_TWEET_SCANNER_API_URL": "http://localhost:8000",
        "X_TWEET_SCANNER_API_TOKEN": "your_token"
      }
    }
  }
}

Available Tools

The MCP server provides 25+ tools organized by category:

Template Management

• create_post_template - Create reusable content templates
• get_post_template - Retrieve specific templates
• update_post_template - Modify existing templates
• list_post_templates - List all templates
• delete_post_template - Remove templates

Schedule Management

• create_weekly_template - Set up posting schedules
• get_weekly_template - View current schedules
• update_weekly_template - Modify schedules
• remove_weekly_slot - Remove schedule entries
• get_weekly_planning_markdown - Get formatted planning view

Content Operations

• save_created_post - Save posts with tracking
• get_all_previous_posts - Retrieve post history
• get_created_post - Get specific posts
• update_created_post - Modify saved posts
• delete_created_post - Remove posts

Analytics & Intelligence

• query_tweets - Analyze high-performing content
• get_trending_topics - Identify trending topics
• analyze_content_performance - Evaluate content potential
• get_creation_context - Get AI-powered creation guidance

And many more...

Proactive AI Guidance

The system includes enhanced AI prompting that provides:

• Pre-execution guidance: Context before tool execution
• Strategic recommendations: Next-step suggestions
• Workflow awareness: Phase-appropriate guidance
• Performance insights: Data-driven optimization tips

API Integration

All operations are performed through HTTP requests to the x-tweet-scanner API:

# Example: Creating a template
async with XTweetScannerClient() as client:
    result = await client.create_post_template(user_id, template_data)

The API client handles:

• Authentication with bearer tokens
• Request retries with exponential backoff
• Error handling and recovery
• Response validation

Error Handling

The MCP layer provides comprehensive error handling:

• Authentication Errors: Clear guidance for auth issues
• API Errors: Detailed error messages with recovery steps
• Network Errors: Retry logic with exponential backoff
• Validation Errors: Input validation and correction guidance

Development

Running Tests

pytest

Code Formatting

black src/
ruff check src/

Type Checking

mypy src/

Dependencies

Core Dependencies

• mcp[cli]>=1.0.0 - Model Context Protocol framework
• httpx>=0.27.0 - Async HTTP client
• pydantic>=2.0.0 - Data validation
• python-dotenv>=1.0.0 - Environment configuration

Development Dependencies

• pytest>=7.0.0 - Testing framework
• pytest-asyncio>=0.21.0 - Async test support
• black>=23.0.0 - Code formatting
• ruff>=0.1.0 - Linting
• mypy>=1.0.0 - Type checking

Architecture Benefits

Separation of Concerns

• MCP Layer: Handles protocol and AI guidance
• API Layer: Manages business logic and data
• Database Layer: Handled by x-tweet-scanner backend

Scalability

• Lightweight MCP instances
• Centralized business logic in API
• Easy horizontal scaling

Maintainability

• Clear boundaries between layers
• Simplified testing and debugging
• Independent deployment cycles

Comparison with Original XCompanion

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• Check the documentation
• Review the API integration guide
• Open an issue on GitHub