Ask Starknet Bot - Multi-Platform Monorepo

A monorepo containing bots for Telegram, X/Twitter, and Discord that answer questions about the Starknet ecosystem using LangGraph and MCP (Model Context Protocol).

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Bot Platforms                            │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
│  │ Telegram │    │ Twitter  │    │ Discord  │              │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘              │
│       │               │               │                      │
│       └───────────────┼───────────────┘                      │
│                       │                                      │
│                       ▼                                      │
│              ┌────────────────┐                             │
│              │  Queue Manager │                             │
│              │   (BullMQ)     │                             │
│              └────────┬───────┘                             │
│                       │                                      │
│                       ▼                                      │
│              ┌────────────────┐                             │
│              │ LangGraph Agent│                             │
│              │  + MCP Adapter │                             │
│              └────────────────┘                             │
│                                                              │
│                       ▼                                      │
│              ┌────────────────┐                             │
│              │   MCP Server   │                             │
│              │  (Your Tools)  │                             │
│              └────────────────┘                             │
└─────────────────────────────────────────────────────────────┘

📦 Monorepo Structure

ask-starknet-bot/
├── packages/
│   ├── shared/              # Shared agent, queue, and utilities
│   │   ├── src/
│   │   │   ├── agent.ts     # LangGraph agent with MCP
│   │   │   ├── queue.ts     # BullMQ queue manager
│   │   │   ├── types.ts     # Shared types
│   │   │   └── logger.ts    # Logging utilities
│   │   └── package.json
│   │
│   ├── telegram-bot/        # Telegram bot (Complete)
│   │   ├── src/
│   │   │   └── index.ts     # Bot implementation
│   │   ├── Dockerfile
│   │   └── package.json
│   │
│   ├── twitter-bot/         # X/Twitter bot (Complete)
│   │   ├── src/
│   │   │   └── index.ts     # Bot implementation
│   │   ├── Dockerfile
│   │   └── package.json
│   │
│   └── discord-bot/         # Discord bot (Architecture only)
│       ├── src/
│       │   ├── commands/    # Slash commands (TODO)
│       │   ├── events/      # Event handlers (TODO)
│       │   └── utils/       # Utilities (TODO)
│       ├── Dockerfile
│       └── package.json
│
├── docker-compose.yml       # Orchestration for all services
├── pnpm-workspace.yaml      # pnpm workspace configuration
├── package.json             # Root package with shared scripts
├── tsconfig.json            # Shared TypeScript configuration
├── env.example              # Environment variables template
└── README.md                # This file

🚀 Quick Start

Prerequisites

Node.js >= 20.0.0
pnpm >= 8.0.0
Docker & Docker Compose (for deployment)
Redis (if running without Docker)

Installation

Clone the repository

git clone <your-repo-url>
cd ask-starknet-bot

Install dependencies

pnpm install

Configure environment variables

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

Build all packages

pnpm build

Development

Run all bots in development mode:

pnpm dev

Run individual bots:

pnpm telegram:dev
pnpm twitter:dev
pnpm discord:dev

Production Deployment with Docker

Configure environment

cp env.example .env
# Edit .env with production credentials

Deploy all services

docker-compose up -d

Deploy specific services

# Only Telegram and Redis
docker-compose up -d redis telegram-bot

# Only Twitter and Redis
docker-compose up -d redis twitter-bot

View logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f telegram-bot

Stop services

docker-compose down

🤖 Bot Configuration

Telegram Bot

Get your bot token from @BotFather:

Send /newbot to BotFather
Follow instructions to create your bot
Copy the token to TELEGRAM_BOT_TOKEN in .env

Features:

Responds to direct messages
Responds to mentions in groups
/start, /help, /status commands
Queue-based processing

Usage:

Direct message: Just send a question
In groups: Mention the bot @your_bot_name what is Starknet?

More details

Twitter/X Bot

Get your credentials from Twitter Developer Portal:

Create an App with Read and Write permissions
Generate API Key, API Secret, Access Token, and Access Secret
Add credentials to .env

Features:

Monitors mentions of your username (e.g., @ask_starknet)
Automatic replies with threading for long responses
Rate limiting and duplicate detection
Configurable polling interval

Usage: Users mention your bot: @ask_starknet what's happening with Starknet?

More details

Discord Bot

Get your bot token from Discord Developer Portal:

Create a new Application
Create a bot and copy the token
Enable Message Content Intent
Add token to .env

Features (Architecture Provided):

Slash commands: /ask, /status, /help
Optional mention support
Embed-based responses
Queue integration

Status: Architecture and structure provided. Implementation TODO.

More details

🔧 Configuration

Environment Variables

Create a .env file based on env.example:

# Required for each bot you want to run
TELEGRAM_BOT_TOKEN=your_token
TWITTER_API_KEY=your_key
TWITTER_API_SECRET=your_secret
TWITTER_ACCESS_TOKEN=your_token
TWITTER_ACCESS_SECRET=your_secret
DISCORD_TOKEN=your_token
DISCORD_CLIENT_ID=your_id

# Redis (for queue)
REDIS_HOST=localhost
REDIS_PORT=6379

# MCP Server Configuration
MCP_COMMAND=npx
MCP_ARGS=-y,@your/mcp-server

MCP Server Configuration

The bots use a centralized LangGraph agent that connects to an MCP (Model Context Protocol) server. Configure your MCP server:

# Example: Using a built-in MCP server
MCP_COMMAND=npx
MCP_ARGS=-y,@modelcontextprotocol/server-everything

# Example: Using a custom MCP server
MCP_COMMAND=node
MCP_ARGS=./your-mcp-server.js

# With environment variables
MCP_ENV={"API_KEY":"your_key","ENV":"production"}

The agent uses @langchain/mcp-adapters to communicate with the MCP server.

📚 Package Details

@ask-starknet/shared

Core package with:

LangGraph Agent: Processes queries using MCP integration
Queue Manager: BullMQ-based queue for concurrent request handling
Types: Shared TypeScript types and Zod schemas
Logger: Structured logging with Pino

Documentation

🛠️ Development Scripts

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Build shared package only
pnpm shared:build

# Run all bots in development
pnpm dev

# Run individual bots
pnpm telegram:dev
pnpm twitter:dev
pnpm discord:dev

# Type checking
pnpm type-check

# Clean build artifacts
pnpm clean

🐳 Docker Deployment

The monorepo includes a complete Docker Compose setup:

Services:

redis: Queue backend
telegram-bot: Telegram bot
twitter-bot: Twitter/X bot
discord-bot: Discord bot

Features:

Multi-stage builds for optimized images
Health checks for Redis
Automatic restarts
Log rotation
Shared network
Persistent Redis data

Deployment:

# Full stack
docker-compose up -d

# Scale services (if needed)
docker-compose up -d --scale telegram-bot=2

# Update and rebuild
docker-compose up -d --build

# Monitor
docker-compose logs -f

# Stop
docker-compose down

🔍 Queue System

All bots use a centralized queue system (BullMQ + Redis) for:

Concurrent Processing: Handle multiple requests simultaneously
Rate Limiting: Control processing speed
Retry Logic: Automatic retries with exponential backoff
Job Tracking: Monitor job status and metrics
Error Handling: Graceful error recovery

Queue Metrics:

Each bot provides status information:

Telegram: /status command
Twitter: Check logs
Discord: /status command (when implemented)

📊 Monitoring & Logs

Docker Logs

# View all logs
docker-compose logs -f

# Specific service
docker-compose logs -f telegram-bot

# Last 100 lines
docker-compose logs --tail=100 telegram-bot

Log Levels

Set via LOG_LEVEL environment variable:

debug: Detailed debugging information
info: General information (default)
warn: Warning messages
error: Error messages only

Production Logging

In production (NODE_ENV=production), logs are in JSON format for easier parsing and aggregation.

🚨 Troubleshooting

Bots not starting

Check environment variables are set correctly
Verify Redis is running: docker-compose ps
Check logs: docker-compose logs -f <service-name>

Queue not processing

Verify Redis connection
Check worker is started (logs should show "Worker started")
Check queue metrics

MCP connection issues

Verify MCP_COMMAND and MCP_ARGS are correct
Check if MCP server is accessible
Review agent logs for connection errors

Rate limiting (Twitter)

Reduce TWITTER_POLL_INTERVAL
Monitor Twitter API rate limits
Check for duplicate processing

📈 Scaling

Horizontal Scaling

Run multiple instances of the same bot:

docker-compose up -d --scale telegram-bot=3

Queue Concurrency

Adjust in packages/shared/src/queue.ts:

concurrency: 5, // Process up to 5 jobs concurrently

Redis Performance

For high load, consider:

Separate Redis instance
Redis Cluster
Increased memory limits

🔐 Security

Never commit .env files
Use environment-specific credentials
Rotate API keys regularly
Use Redis password in production
Implement rate limiting per user
Sanitize user inputs
Review MCP server security

🤝 Contributing

Follow existing code structure
Use TypeScript strict mode
Write meaningful commit messages
Test before committing
Update documentation

📝 License

MIT

🔗 Useful Links

💡 Tips

Start Small: Deploy one bot at a time
Monitor Logs: Keep an eye on logs during initial deployment
Test MCP: Verify your MCP server works before deploying
Set Limits: Configure appropriate rate limits and timeouts
Backup Data: Regularly backup Redis data if needed
Health Checks: Monitor bot health and queue metrics

🆘 Support

For issues and questions:

Check bot-specific READMEs
Review logs for error messages
Verify configuration
Check API credentials and permissions

Built with ❤️ for the Starknet community

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
packages		packages
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml
env.example		env.example
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Ask Starknet Bot - Multi-Platform Monorepo

🏗️ Architecture

📦 Monorepo Structure

🚀 Quick Start

Prerequisites

Installation

Development

Production Deployment with Docker

🤖 Bot Configuration

Telegram Bot

Twitter/X Bot

Discord Bot

🔧 Configuration

Environment Variables

MCP Server Configuration

📚 Package Details

@ask-starknet/shared

🛠️ Development Scripts

🐳 Docker Deployment

🔍 Queue System

📊 Monitoring & Logs

Docker Logs

Log Levels

Production Logging

🚨 Troubleshooting

Bots not starting

Queue not processing

MCP connection issues

Rate limiting (Twitter)

📈 Scaling

Horizontal Scaling

Queue Concurrency

Redis Performance

🔐 Security

🤝 Contributing

📝 License

🔗 Useful Links

💡 Tips

🆘 Support

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages