agent-twitter-client-mcp Developer Guide

This guide provides comprehensive information for developers who want to use, extend, or contribute to the agent-twitter-client-mcp server.

Architecture Overview

The agent-twitter-client-mcp server is built with a modular architecture:

agent-twitter-client-mcp/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── types.ts                 # Type definitions
│   ├── authentication.ts        # Authentication manager
│   ├── twitter-client.ts        # Twitter client wrapper
│   ├── health.ts                # Health check functionality
│   ├── test-interface.ts        # Interactive testing interface
│   ├── tools/                   # MCP tool implementations
│   │   ├── tweets.ts            # Tweet-related tools
│   │   ├── profiles.ts          # Profile-related tools
│   │   └── grok.ts              # Grok integration tools
│   ├── utils/                   # Utility functions
│   │   ├── formatters.ts        # Response formatters
│   │   ├── validators.ts        # Input validators
│   │   └── logger.ts            # Logging utilities
│   └── types/                   # Type declarations
│       └── agent-twitter-client.d.ts # Twitter client type declarations
├── tests/                       # Load testing
│   ├── load-test.yml            # Load test configuration
│   └── load-test-functions.js   # Load test functions
└── docs/
    ├── TESTING.md               # Testing guide
    ├── AGENT_GUIDE.md           # Guide for AI agents
    └── DEVELOPER_GUIDE.md       # This file

Key Components

Authentication Manager: Handles Twitter authentication using cookies, credentials, or API keys.
Twitter Client: Wraps the agent-twitter-client package to provide a clean interface.
MCP Tools: Implements the Model Context Protocol tools for tweets, profiles, and Grok.
Utilities: Provides formatting, validation, and logging functionality.

Getting Started

Prerequisites

Node.js 18+
npm or yarn
Twitter credentials (see Authentication)

Installation

# Clone the repository
git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp

# Install dependencies
npm install

# Create a .env file with your Twitter credentials
touch .env

Edit the .env file with your Twitter credentials (see Authentication).

Building

# Build the project
npm run build

# Start the server
npm start

Authentication

The agent-twitter-client-mcp supports three authentication methods:

1. Cookie Authentication (Recommended)

AUTH_METHOD=cookies
TWITTER_COOKIES=["auth_token=your_auth_token; Domain=.twitter.com", "ct0=your_ct0_value; Domain=.twitter.com", "twid=u%3Dyour_user_id; Domain=.twitter.com"]

To obtain cookies:

Log in to Twitter in your browser
Open Developer Tools (F12)
Go to the Application tab > Cookies
Copy the values of auth_token, ct0, and twid cookies
Make sure to include the Domain=.twitter.com part for each cookie

2. Username/Password Authentication

AUTH_METHOD=credentials
TWITTER_USERNAME=your_username
TWITTER_PASSWORD=your_password
TWITTER_EMAIL=your_email@example.com  # Optional
TWITTER_2FA_SECRET=your_2fa_secret    # Optional, required if 2FA is enabled

3. API Authentication

AUTH_METHOD=api
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

Available Tools

The agent-twitter-client-mcp provides the following tools:

Tweet Tools

get_user_tweets: Fetch tweets from a specific user
get_tweet_by_id: Fetch a specific tweet by ID
search_tweets: Search for tweets
send_tweet: Post a new tweet
send_tweet_with_poll: Post a tweet with a poll
like_tweet: Like a tweet
retweet: Retweet a tweet
quote_tweet: Quote a tweet

Profile Tools

get_user_profile: Get a user's profile
follow_user: Follow a user
get_followers: Get a user's followers
get_following: Get users a user is following

Grok Tools

grok_chat: Chat with Grok via Twitter

This tool enables interaction with Twitter's Grok AI assistant, providing access to:

Real-time Twitter data analysis
Web search capabilities
Conversation history management
Citations for information sources

Important: Grok functionality requires agent-twitter-client v0.0.19 or higher. The current package uses v0.0.18 for basic functionality, but you'll need to upgrade to v0.0.19 to use Grok features.

The implementation directly interfaces with Twitter's internal Grok API endpoints, handling authentication, conversation creation, and response parsing. It supports both new conversations and continuing existing ones via conversation IDs.

Grok Implementation Details

The Grok functionality is implemented in src/twitter-client.ts and uses Twitter's GraphQL and REST APIs:

https://x.com/i/api/graphql/6cmfJY3d7EPWuCSXWrkOFg/CreateGrokConversation for creating new conversations
https://api.x.com/2/grok/add_response.json for sending messages and receiving responses

The implementation handles various response formats, including:

Streaming responses with multiple JSON chunks
Single JSON responses
Rate limiting responses
Error responses

Grok Rate Limiting

Grok has rate limits enforced by Twitter:

Non-premium accounts: 25 messages per 2 hours
The implementation detects rate limiting and provides appropriate error messages

Utility Tools

health_check: Check the health of the agent-twitter-client-mcp server

Extending the MCP

Adding a New Tool

To add a new tool to the MCP:

Define the input schema in src/types.ts:

export const MyNewToolSchema = z.object({
  param1: z.string().min(1, 'Param1 is required'),
  param2: z.number().int().min(1).max(100).default(10)
});

Add the tool implementation in the appropriate file in src/tools/:

async myNewTool(authConfig: AuthConfig, args: unknown) {
  const params = validateInput(MyNewToolSchema, args);
  // Implement the tool functionality
  return {
    result: 'Success',
    data: { /* ... */ }
  };
}

{
  name: 'my_new_tool',
  description: 'Description of the new tool',
  inputSchema: {
    type: 'object',
    properties: {
      param1: {
        type: 'string',
        description: 'Description of param1'
      },
      param2: {
        type: 'number',
        description: 'Description of param2',
        default: 10
      }
    },
    required: ['param1']
  }
} as Tool,

Add the tool handler in the CallToolRequestSchema handler:

case 'my_new_tool':
  return {
    content: [{ 
      type: 'text',
      text: JSON.stringify(await toolsInstance.myNewTool(authConfig, args))
    }] as TextContent[]
  };

Add the command to the test interface in src/test-interface.ts if applicable:

case 'my_new_tool':
  if (!args[1]) {
    console.log('Error: Parameter is required');
    break;
  }
  console.log(`Executing my_new_tool with ${args[1]}...`);
  const result = await toolsInstance.myNewTool(authConfig, { 
    param1: args[1],
    param2: args[2] ? parseInt(args[2]) : 10
  });
  console.log(JSON.stringify(result, null, 2));
  break;

Modifying Existing Tools

To modify an existing tool:

Locate the tool implementation in src/tools/
Update the implementation as needed
Update the tool schema in src/types.ts if necessary
Update the tool registration in src/index.ts if necessary
Update the test interface command in src/test-interface.ts if necessary

Error Handling

The MCP uses a centralized error handling approach:

TwitterMcpError: Custom error class for MCP-specific errors
Input Validation: Uses Zod schemas to validate inputs
Error Logging: Logs errors with context for debugging

Example of proper error handling:

try {
  // Attempt an operation
} catch (error) {
  if (error instanceof TwitterMcpError) {
    // Handle MCP-specific errors
    throw error;
  }
  // Handle other errors
  throw new TwitterMcpError(
    `Operation failed: ${error instanceof Error ? error.message : String(error)}`,
    'operation_error',
    500
  );
}

Logging

The MCP uses Winston for logging:

import { logInfo, logError, logWarning, logDebug } from './utils/logger.js';

// Log information
logInfo('Operation completed', { context: 'value' });

// Log errors
try {
  // Attempt an operation
} catch (error) {
  logError('Operation failed', error, { context: 'value' });
}

Log files:

error.log: Contains error-level messages
combined.log: Contains all log messages

Testing

Unit Testing

The MCP includes unit tests for core functionality:

# Run unit tests
npm test

Integration Testing

Integration tests are available to test the MCP against the Twitter API:

# Run integration tests (requires valid Twitter credentials)
RUN_INTEGRATION_TESTS=true npm test

Manual Testing

The MCP includes an interactive test interface for manual testing:

# Run the test interface
npm run test:interface

Deployment

Docker Deployment

The MCP includes a Dockerfile and docker-compose.yml for containerized deployment:

# Build the Docker image
docker build -t agent-twitter-client-mcp .

# Run the container
docker run -p 3000:3000 \
  -e AUTH_METHOD=cookies \
  -e TWITTER_COOKIES='["auth_token=value; Domain=.twitter.com", "ct0=value; Domain=.twitter.com", "twid=u%3Dvalue; Domain=.twitter.com"]' \
  agent-twitter-client-mcp

Using Docker Compose

For a more comprehensive setup, you can use Docker Compose:

Create a .env file with your Twitter credentials
Run with docker-compose:

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

The docker-compose.yml file includes:

Environment variable configuration
Volume mounting for logs
Network configuration
Restart policy

Docker Development Workflow

For development with Docker:

Make changes to the code
Rebuild the Docker image:
```
docker-compose build
```
Restart the container:
```
docker-compose up -d
```
View logs:
```
docker-compose logs -f
```

Environment Variables

In addition to authentication variables, you can set:

LOG_LEVEL: Set logging level (error, warn, info, debug)
NODE_ENV: Set environment (development, production)
RUN_INTEGRATION_TESTS: Enable/disable integration tests
RUN_WRITE_TESTS: Enable/disable write tests (posting, liking, etc.)

Health Monitoring

The MCP includes a health check tool that can be used for monitoring:

# Check the health of the MCP using the test interface
npm run test:interface
agent-twitter-client-mcp> health

Development Environment

VSCode Configuration

The repository includes VSCode configuration files to enhance the development experience:

Recommended Extensions

The .vscode/extensions.json file recommends the following extensions:

ESLint: For code linting
Prettier: For code formatting
TypeScript Next: For TypeScript language features
Jest: For test running and debugging
DotENV: For .env file syntax highlighting
NPM Intellisense: For npm package autocompletion
Path Intellisense: For file path autocompletion
Docker: For Docker file support

Editor Settings

The .vscode/settings.json file includes settings for:

Format on save
ESLint auto-fix on save
TypeScript configuration
File exclusions
Search exclusions
Import path preferences

Debugging

The .vscode/launch.json file includes configurations for:

Debugging the MCP server
Debugging the test interface
Debugging individual Jest tests

To start debugging:

Open the Debug panel in VSCode
Select a debug configuration
Press F5 or click the green play button

Tasks

The .vscode/tasks.json file includes tasks for:

Building the project
Starting the server
Running linting
Running tests
Running the test interface

To run a task:

Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
Type "Run Task"
Select the task to run

Security Considerations

Authentication Security

Store credentials securely, preferably using environment variables or a secure vault
Use cookie authentication when possible, as it's the most reliable method
Rotate API keys regularly
Never commit credentials to version control

Input Validation

All inputs are validated using Zod schemas to prevent injection attacks and other security issues.

Rate Limiting

Twitter imposes rate limits on API calls. The MCP does not currently implement rate limiting, so be careful not to exceed Twitter's limits.

Troubleshooting

Common Issues

Authentication Failures:
- Check that your credentials are correct and up-to-date
- Ensure cookies are properly formatted with the correct domain
- Try refreshing your cookies by logging out and back into Twitter
API Rate Limiting:
- Twitter limits API calls, which can cause failures
- Implement exponential backoff for retries
- Monitor rate limit headers in responses
Zod Validation Errors:
- Check that your input data matches the expected schema
- Look for missing required fields or invalid data types
- Check for string length or number range violations

Debugging

Enable Debug Logging:
```
LOG_LEVEL=debug npm start
```
Check Log Files:
- error.log: Contains error-level messages
- combined.log: Contains all log messages
Use the Test Interface:
```
npm run test:interface
```

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Make your changes
Run tests (npm test)
Commit your changes (git commit -am 'Add my feature')
Push to the branch (git push origin feature/my-feature)
Create a new Pull Request

License

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

Uh oh!

FilesExpand file tree

DEVELOPER_GUIDE.md

Latest commit

History

DEVELOPER_GUIDE.md

File metadata and controls

agent-twitter-client-mcp Developer Guide

Architecture Overview

Key Components

Getting Started

Prerequisites

Installation

Building

Authentication

1. Cookie Authentication (Recommended)

2. Username/Password Authentication

3. API Authentication

Available Tools

Tweet Tools

Profile Tools

Grok Tools

Grok Implementation Details

Grok Rate Limiting

Utility Tools

Extending the MCP

Adding a New Tool

Modifying Existing Tools

Error Handling

Logging

Testing

Unit Testing

Integration Testing

Manual Testing

Deployment

Docker Deployment

Using Docker Compose

Docker Development Workflow

Environment Variables

Health Monitoring

Development Environment

VSCode Configuration

Recommended Extensions

Editor Settings

Debugging

Tasks

Security Considerations

Authentication Security

Input Validation

Rate Limiting

Troubleshooting

Common Issues

Debugging

Contributing

License