tradergrader

TraderGrader

⚠️ WORK IN PROGRESS - USE WITH CAUTION ⚠️

This is an experimental Rust-based MCP (Model Context Protocol) server that provides AI tools with access to EVE Online market data, historical trends, and trading analysis through the ESI API. While functional with Claude Code and Claude Desktop, this project is still in active development and should be used with care, if at all.

🎯 What is TraderGrader?

TraderGrader bridges the gap between AI assistants and EVE Online's complex market ecosystem. By implementing the Model Context Protocol, it allows AI tools to query real-time market data, analyze historical price trends, identify trading opportunities, and provide insights into New Eden's economy.

✅ Basic functionality working with Claude Code - The MCP server connects and responds to basic queries, but comprehensive testing is ongoing.

Model Context Protocol (MCP) is an open standard that enables AI applications to connect securely with external data sources and tools. TraderGrader implements an experimental MCP server that exposes EVE Online market data as callable tools for AI assistants.

⚡ Quick Start

One-Liner Installation

curl -sSL https://raw.githubusercontent.com/fuuijin/tradergrader/main/scripts/install.sh | bash

This automatically:

• Installs TraderGrader to ~/.local/share/tradergrader
• Builds the optimized release binary
• Configures Claude Desktop integration
• Creates convenient CLI tools

Manual Installation

git clone https://github.com/fuuijin/tradergrader.git
cd tradergrader
cargo build --release
./scripts/install_mcp.sh  # Configure for Claude Desktop

🐳 Docker Installation

Quick Docker Start:

# Build and run with Docker
git clone https://github.com/fuuijin/tradergrader.git
cd tradergrader
./scripts/docker-build.sh
./scripts/docker-run.sh --interactive

Using docker-compose:

# Production setup
docker-compose up

# Development with Redis
docker-compose --profile with-redis up

# Development mode with hot reload
docker-compose --profile dev up

Docker Commands:

# Build optimized production image
./scripts/docker-build.sh

# Build development image (with Rust toolchain)
./scripts/docker-build.sh --dev

# Run interactively
./scripts/docker-run.sh --interactive

# Run health check
./scripts/docker-run.sh --health

# Test Docker setup
./scripts/docker-test.sh

🛠️ Available Tools

TraderGrader provides 5 MCP tools for comprehensive market analysis:

Core Market Data

• health_check - Test server connectivity and status
• get_market_orders - Current buy/sell order counts and activity
• get_market_summary - Real-time price analysis with spreads

Historical Analysis 📈

• get_market_history - Historical price data (~400 days)
• get_price_analysis - Advanced trend analysis with volatility

📊 Features

Real-Time Market Data

• Current market orders and pricing
• Buy/sell spreads and profit margins
• Multi-region arbitrage opportunities
• Order volume and market activity

Historical Analysis

• Price trend analysis (daily/weekly/monthly changes)
• Volatility calculations using standard deviation
• Trend classification (Strong Upward/Downward, Stable)
• Historical data spanning ~400 days per item

Trading Intelligence

• Automatic arbitrage opportunity detection
• Price spread analysis for profit margins
• Market activity monitoring
• Regional price comparison

🚀 Usage

With Claude Desktop

After installation, restart Claude Desktop and use TraderGrader tools in conversations:

• "Analyze the Tritanium market in Jita"
• "Check price trends for PLEX over the last month"
• "Find profitable trading opportunities for Skill Injectors"
• "Compare Pyerite prices between Jita and Amarr"

CLI Tools

# Market summary (default)
./market_query.sh -t 34 -r 10000002

# Price trend analysis
./market_query.sh --analysis -t 44992

# Historical data
./market_query.sh --history -t 35

# Current orders count
./market_query.sh --orders -t 36

# Help and options
./market_query.sh --help

Direct MCP Integration

# Start MCP server
cargo run

# Send JSON-RPC commands
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_price_analysis","arguments":{"region_id":10000002,"type_id":44992}}}' | cargo run

🏗️ Architecture

Technology Stack

• Language: Rust (2024 edition)
• Protocol: Model Context Protocol (MCP)
• API: EVE Online ESI (EVE Swagger Interface)
• Transport: JSON-RPC over stdio
• Runtime: Tokio async
• HTTP Client: Reqwest with rate limiting

Core Components

• MCP Server: Protocol communication and tool dispatch
• ESI Client: HTTP client with proper User-Agent and error handling
• Market Analysis: Real-time and historical data analysis
• CLI Tools: Command-line utilities for direct usage

Key Dependencies

• tokio - Async runtime
• reqwest - HTTP client for ESI API
• serde - JSON serialization/deserialization
• chrono - Date/time handling for historical analysis

📈 Example Analysis

Price Trend Analysis

Price Analysis for Type 44992 in Region 10000002:
Current Price: 6063000.00 ISK

Changes:
Daily: 0.00 ISK (+0.00%)
Weekly: -83000.00 ISK (-1.35%)
Monthly: -118000.00 ISK (-1.91%)

Volatility: 79716.97 ISK
Trend: Stable

Trading Opportunities

Market Summary for Type 34 in Region 10000002:
Total Orders: 215
Buy Orders: 71
Sell Orders: 144
Highest Buy: 4.27 ISK
Lowest Sell: 2.70 ISK
Spread: -1.57 ISK

🗺️ Common EVE Online IDs

Major Trade Hubs

• 10000002 - The Forge (Jita) - Primary trade hub
• 10000043 - Domain (Amarr) - Major trade hub
• 10000032 - Sinq Laison (Dodixie) - Regional hub
• 10000030 - Heimatar (Rens) - Regional hub

Popular Trading Items

• 34 - Tritanium (basic mineral)
• 35 - Pyerite (basic mineral)
• 44992 - Skill Injector (high-value item)
• 29668 - PLEX (game time token)
• 11399 - Morphite (rare mineral)

⚠️ Technical Considerations

Rate Limiting

• ESI history endpoint: 300 requests per IP per minute
• Proper error handling and backoff strategies
• User-Agent identification as required by CCP

Data Quality

• Real-time data from official EVE ESI API
• ~400 days of historical data per item
• Automatic handling of API downtime and errors

🧪 Testing

# Run unit tests
cargo test

# Run integration tests (makes real API calls)
cargo test -- --ignored

# Test specific functionality
cargo test test_price_analysis -- --ignored

📁 Project Structure

tradergrader/
├── src/
│   ├── main.rs          # Application entry point  
│   ├── lib.rs           # Main application & public API (123 lines)
│   ├── types.rs         # Data structures & types (50 lines)
│   ├── market.rs        # Market logic & ESI API (199 lines)
│   └── mcp.rs           # MCP protocol handling (411 lines)
├── tests/               # Integration tests
├── install.sh           # One-liner installer script
├── market_query.sh      # CLI utility for market queries
├── ROADMAP.md           # Development roadmap
├── HISTORICAL_DATA.md   # Historical features documentation
└── README_MCP.md        # MCP-specific documentation

🛣️ Development Roadmap

✅ Completed (v0.1.0)

• Production MCP server with stdio transport
• Real-time market data fetching
• Historical price data and trend analysis
• Price volatility and change calculations
• Trading opportunity analysis
• Comprehensive CLI tools
• One-liner installation script
• Claude Desktop integration

🚧 Next Phase (v0.2.0)

• Redis caching for improved performance
• Multi-item bulk operations
• Corporation and alliance market tools
• Manufacturing cost calculations
• Advanced portfolio tracking

🔮 Future Phases

• Web dashboard interface
• Real-time market alerts and notifications
• Machine learning price prediction
• Integration with EVE character APIs
• Docker containerization

📝 License

[License TBD]

🤝 Contributing

Contributions welcome! Areas of interest:

• EVE Online market mechanics and trading strategies
• Rust async programming and optimization
• MCP protocol extensions and improvements
• Market analysis algorithms and statistics

Development Guidelines

• Follow Rust idioms and conventions
• Add comprehensive tests for new features
• Respect ESI rate limits and best practices
• Maintain MCP protocol compliance

📚 Resources

EVE Online & Market Data

• ESI Documentation - Interactive API docs
• Market Data Guide - Comprehensive market API guide
• EVE University Trading - Trading mechanics and strategies

Model Context Protocol

• MCP Specification - Official protocol docs
• MCP Introduction - Getting started guide

Rust Development

• Tokio Async Runtime - Async programming
• Reqwest HTTP Client - HTTP requests
• Serde JSON - Serialization

---

Fly safe, trade smart, profit wisely. 🚀

Status: Experimental v0.1.0 - Use with Caution | Last Updated: June 2025