Elite Dangerous Local AI Tie-In MCP

A Model Context Protocol (MCP) server that provides real-time integration between Elite Dangerous and Claude Desktop, enabling AI-powered analysis of your gameplay data and dynamic generation of EDCoPilot custom content.

Features

Real-time Journal Monitoring: Automatically monitors Elite Dangerous journal files for live gameplay events

Historical Data Loading: Processes existing journal files on startup (last 24 hours) for immediate data availability

Historical Data Search (NEW!): Search your complete gameplay history with flexible date ranges using natural language (e.g., "last month to two weeks ago") or absolute dates

Claude Desktop Integration: Provides MCP tools, resources, and prompts for AI-powered gameplay analysis

EDCoPilot Integration: Generates dynamic custom chatter, crew dialogue, and speech extensions based on your current game state

Dynamic Theme System (NEW!): AI-powered personality themes with ship-specific multi-crew support for immersive roleplay and dynamic character development

Comprehensive Analytics: Track exploration progress, trading performance, combat statistics, and journey summaries

Flexible Configuration: Configurable paths, event limits, and integration options

Claude Desktop Working

Headless EDCoPilot Generation

Generate EDCoPilot chatter files without opening Claude Desktop.

• Command: python scripts/generate_edcopilot.py
• See full usage: docs/HEADLESS_CLI.md
• Examples:
• python scripts/generate_edcopilot.py (defaults: last 7 days; theme "Grizzled Veteran Space Captain"; context "Worn Hands, Endless Horizon")
• python scripts/generate_edcopilot.py --hours 12 --theme "Corporate Fixer" --context "Cold Calculus, Clean Ledger"
• python scripts/generate_edcopilot.py --from "2025-09-10" --to "2025-09-13 18:00" --output-dir C:\\temp\\edc --dry-run

Quick Start

Automated Setup (Recommended)

For the fastest setup experience, use our automation scripts:

# 1. Clone the repository
git clone https://github.com/GWLlosa/elite-dangerous-local-ai-tie-in-mcp.git
cd elite-dangerous-local-ai-tie-in-mcp

# 2. Set up all dependencies automatically
python scripts/setup_dependencies.py

# 3. Verify environment setup
python scripts/check_dependencies.py

# 4. Run tests to verify everything works
python scripts/run_tests.py

Prerequisites

• Python 3.9+ (Python 3.11+ recommended)
• Git for version control
• Elite Dangerous installed and running
• Claude Desktop application
• EDCoPilot (optional, for voice integration)

Manual Installation

If you prefer manual setup:

1. Clone the repository:

   git clone https://github.com/GWLlosa/elite-dangerous-local-ai-tie-in-mcp.git
   cd elite-dangerous-local-ai-tie-in-mcp

1. Create virtual environment:

   python -m venv venv
   .\venv\Scripts\Activate.ps1  # Windows
   source venv/bin/activate     # Linux/Mac

1. Install dependencies:

   pip install -r requirements.txt

1. Verify installation:

   python scripts/check_environment.py

See the Testing Guide for detailed setup and verification instructions.

Testing and Development

Available Scripts

• `scripts/setup_dependencies.py` - Automated environment setup with package verification
• `scripts/check_environment.py` - Comprehensive environment validation
• `scripts/run_tests.py` - Run complete test suite with coverage reporting

Running Tests

# Quick test run with coverage
python scripts/run_tests.py

# Manual test execution
pytest tests/ -v --cov=src --cov-report=html

# Run specific test categories
pytest tests/unit/ -v          # Unit tests only
pytest tests/integration/ -v   # Integration tests only

Test Coverage

• 592 tests passing with 83% code coverage
• Real-time monitoring validated with mock journal events and race condition fixes
• Event processing tested with 213 event types across 17 categories
• Comprehensive event coverage with 98% categorization accuracy (Milestone 17)
• Historical data search with 61 tests covering date parsing, natural language queries, and range filtering (Milestone 18)
• Fleet carrier events with 8 tests for CarrierStats, CarrierFinance, and crew/module management (Issue #18)
• Fleet carrier cargo tracking with 9 tests for CargoTransfer events and inventory management (Issue #15)
• Data storage verified with concurrent access patterns and thread safety
• MCP server tested with comprehensive unit and integration tests
• MCP tools, resources, and prompts extensively tested with edge cases
• Dynamic Theme System tested with 159 comprehensive tests covering performance, edge cases, and integration scenarios
• File monitoring race conditions tested and fixed (Issue #12)

Documentation

• [Testing Guide](docs/TESTING_GUIDE.md) - Comprehensive testing instructions
• [Journal Events Reference](docs/JOURNAL_EVENTS.md) - Complete reference of all 213 supported event types (NEW!)
• [Dynamic Theme System Guide](docs/THEME_SYSTEM_GUIDE.md) - Complete guide to AI-powered crew themes
• [Headless CLI Guide](docs/HEADLESS_CLI.md) - Standalone EDCoPilot generation without Claude Desktop
• [Scripts Documentation](scripts/README.md) - Automation script details
• [AI Directives](ai-directives/README.md) - Development guidelines for AI assistants

Configuration

Claude Desktop Integration

#### Step 1: Locate Claude Desktop Configuration File

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

#### Step 2: Add MCP Server Configuration

Add the following to your Claude Desktop configuration file:

{
  "mcpServers": {
    "elite-dangerous": {
      "command": "C:/path/to/elite-dangerous-local-ai-tie-in-mcp/venv/Scripts/python.exe",
      "args": ["C:/path/to/elite-dangerous-local-ai-tie-in-mcp/src/server.py"],
      "env": {
        "ELITE_JOURNAL_PATH": "C:/Users/YourUsername/Saved Games/Frontier Developments/Elite Dangerous",
        "ELITE_EDCOPILOT_PATH": "C:/Utilities/EDCoPilot/User custom files",
        "ELITE_DEBUG": "false"
      }
    }
  }
}

#### Step 3: Update Path Configuration

Critical: Replace the paths in the configuration with your actual system paths:

1. Server Path (args): Update to your actual repository location
2. Python Environment: Use the full path to your virtual environment's Python executable:

• Windows: C:/path/to/project/venv/Scripts/python.exe
• Linux/Mac: C:/path/to/project/venv/bin/python

1. Journal Path (ELITE_JOURNAL_PATH):

• Windows: C:/Users/[Username]/Saved Games/Frontier Developments/Elite Dangerous
• Steam: C:/Users/[Username]/Saved Games/Frontier Developments/Elite Dangerous
• Epic: Same as Steam
• Linux: ~/.local/share/Steam/steamapps/compatdata/359320/pfx/drive_c/users/steamuser/Saved Games/Frontier Developments/Elite Dangerous

1. EDCoPilot Path (optional): Update if you use EDCoPilot voice integration

#### Step 4: Restart Claude Desktop

After saving the configuration file, restart Claude Desktop for the changes to take effect.

#### Step 5: Verify Connection

In Claude Desktop, try asking:

"What's my current status in Elite Dangerous?"

If configured correctly, Claude will respond with your current game state using the MCP tools.

### Environment Variables
- `ELITE_JOURNAL_PATH` - Path to Elite Dangerous journal directory (auto-detected if not set)
- `ELITE_EDCOPILOT_PATH` - Path to EDCoPilot custom files directory
- `ELITE_DEBUG` - Enable debug logging (true/false)
- `ELITE_MAX_RECENT_EVENTS` - Maximum recent events to store (default: 10000)

##  Project Status

**Current Status**: Production Ready - All Core Milestones Completed [OK]

### [OK] Completed Milestones:
1. **Project Structure** - Complete foundation and build system
2. **Configuration Management** - Environment variables and path validation
3. **Journal File Discovery** - File parsing with comprehensive tests
4. **Real-time Monitoring** - File system watching with position tracking
5. **Event Processing** - 213 event types across 17 categories (98% categorization accuracy)
6. **Data Storage** - In-memory storage with thread safety and game state tracking
7. **MCP Server Framework** - FastMCP integration with background monitoring
8. **Core MCP Tools** - 43+ tools for game data queries and analysis
9. **MCP Resources** - 17+ dynamic resource endpoints with caching
10. **MCP Prompts** - 9 context-aware prompt templates for AI assistance
11. **EDCoPilot Integration** - 4 MCP tools, 3 chatter types, 40+ contextual dialogue entries
12. **Historical Data Loading** - Automatic processing of existing journal files (last 24 hours) on server startup
13. **Journal Parser Fixes** - Fixed filename validation and timestamp extraction for all journal file formats
14. **AsyncIO Stability** - Resolved FastMCP integration issues for stable Claude Desktop connection
15. **Dynamic Multi-Crew Theme System** - AI-powered theme generation with ship-specific crew management
16. **Headless EDCoPilot CLI** - Standalone command-line tool for chatter generation without Claude Desktop
17. **Comprehensive Event Coverage** - Closed 30% event gap, all 213 event types properly categorized (Milestone 17 complete)
18. **Historical Data Search with Date Ranges** - Flexible date range queries with natural language and ISO 8601 support (Milestone 18 complete)

###  Recent Achievements (October 2025):

- **Milestone 18: Historical Data Search with Date Range Support** - Query gameplay history with flexible date ranges
  - **Natural language dates**: "last month", "two weeks ago", "yesterday"
  - **Relative expressions**: "3 days ago", "2 weeks ago", "30 days ago"
  - **ISO 8601 format**: "2025-01-15", "2025-01-15T10:30:00Z"
  - **Flexible queries**: Search by event types, categories, systems, and date ranges
  - **577+ Tests Passing** - Added 61 comprehensive tests for date parsing and historical queries
  - **New MCP Tool**: `search_historical_events` for time-based gameplay analysis

- **Milestone 17: Comprehensive Event Coverage** - Closed 30% event gap with 34 new event mappings
  - 213 total event types now properly categorized (98% accuracy)
  - Navigation: Added BookTaxi, FSDTarget, SupercruiseDestinationDrop, USSDrop, FetchRemoteModule
  - Combat: Added HeatDamage, HeatWarning, LaunchDrone, Scanned, DataScanned
  - Trading: Added RefuelAll, RedeemVoucher, BuyDrones, CargoTransfer
  - Ship Management: Added FuelScoop, SetUserShipName, ShipLocker, ModuleInfo, StoredModules, and more
  - Community Goals, Odyssey/on-foot events, Powerplay, Carrier events
  - **Gap Analysis System** - Automated detection of unmapped event types from real gameplay

###  Recent Achievements (September 2025):
- **Dynamic Multi-Crew Theme System** - Complete AI-powered theme generation with ship-specific crew management
- **159 New Tests** - Comprehensive test coverage for performance, edge cases, and integration scenarios
- **10+ New MCP Tools** - Enhanced theme management tools for Claude Desktop integration
- **AI Theme Generation** - Intelligent prompt generation for creating immersive crew personalities
- **Ship-Specific Themes** - Automatic crew configuration based on ship type and role
- **258+ Historical Events** loaded automatically on server startup
- **200+ Journal Files** now properly recognized and processed
- **Zero-downtime Integration** - Works with existing journal files even when Elite Dangerous is offline
- **Stable MCP Protocol** - Fixed asyncio conflicts for reliable Claude Desktop communication
- **Production Ready** - All critical bugs resolved, comprehensive testing completed

###  AI Development Efficiency:
**This entire project was built with AI assistance using approximately 1.87 million tokens (~$15.57 in AI costs) over 3 months**, demonstrating the incredible efficiency of AI-powered development. The system includes 22,532 lines of Python code, 440+ comprehensive tests, and complete documentation - representing an estimated **99.97% cost reduction** compared to traditional development approaches.

 **[View Complete Token Usage Analysis](docs/TOKEN_USAGE_ANALYSIS.md)** - Detailed breakdown of AI assistance costs, development efficiency, and ROI analysis.

###  Future Enhancements:
- **Advanced Analytics Dashboard** - Web-based gameplay statistics
- **Performance Optimizations** - Enhanced caching and batch processing
- **Extended EDCoPilot Features** - More voice integration options
- **Cross-platform Improvements** - Enhanced Linux and Mac support

##  MCP Server Features

### MCP Tools (43+ Available)
#### Core Data Access
- **`server_status`** - Get current server status and statistics
- **`get_recent_events`** - Retrieve recent journal events with filtering
- **`clear_data_store`** - Clear stored events and reset game state
- **`get_current_location`** - Current system, station, and coordinates
- **`get_current_ship`** - Ship type, status, fuel, hull, and cargo

#### Activity Analysis
- **`get_exploration_summary`** - Exploration progress and discoveries
- **`get_trading_summary`** - Trading performance and profit analysis
- **`get_combat_summary`** - Combat statistics and earnings
- **`search_events`** - Advanced event filtering and search

#### AI Assistance
- **`list_available_prompts`** - View all prompt templates
- **`generate_analysis_prompt`** - Context-aware AI prompts for any activity
- **`list_available_resources`** - View all MCP resource endpoints
- **`get_resource_data`** - Access structured data by URI

#### EDCoPilot Integration
- **`generate_edcopilot_chatter`** - Generate contextual chatter files based on game state (follows formal grammar specification)
- **`get_edcopilot_status`** - Check EDCoPilot integration configuration and custom files
- **`backup_edcopilot_files`** - Create timestamped backups of existing custom files
- **`preview_edcopilot_chatter`** - Preview generated content without writing files

#### Dynamic Theme System *(NEW!)*
- **`set_edcopilot_theme`** - Set AI-powered personality themes for crew members
- **`get_theme_status`** - View current theme configuration and ship setups
- **`reset_theme`** - Clear all theme settings and return to defaults
- **`generate_themed_templates_prompt`** - Create Claude Desktop prompts for theme generation
- **`apply_generated_templates`** - Apply AI-generated templates to EDCoPilot with validation
- **`configure_ship_crew`** - Set up ship-specific crew roles and personalities
- **`set_crew_member_theme`** - Configure individual crew member themes and contexts
- **`generate_crew_setup_prompt`** - Generate prompts for multi-crew theme coordination
- **`preview_themed_content`** - Preview themed content before applying to files
- **`backup_current_themes`** - Create backups of current theme configurations

**Grammar Compliance**: All EDCoPilot chatter generation follows the formal grammar specification documented in [`docs/edcopilot-chatter-grammar.md`](docs/edcopilot-chatter-grammar.md), ensuring compatibility with EDCoPilot's expected file formats and preventing syntax errors.

### MCP Resources (17+ Dynamic Endpoints)
#### Status Resources
- `elite://status/location` - Current location and coordinates
- `elite://status/ship` - Ship status and configuration
- `elite://status/game` - Overall game state and session info

#### Data Resources
- `elite://journal/recent?minutes=60` - Recent journal events
- `elite://journal/stats` - Journal statistics and counts
- `elite://events/by-category?category=exploration` - Events by category
- `elite://events/by-type?type=FSDJump` - Events by specific type

#### Activity Summaries
- `elite://summary/exploration?hours=24` - Exploration analysis
- `elite://summary/trading?hours=12` - Trading performance
- `elite://summary/combat?hours=6` - Combat statistics
- `elite://summary/journey?hours=48` - Journey overview

#### Analytics
- `elite://metrics/performance?hours=24` - Performance metrics
- `elite://metrics/credits?hours=12` - Credit flow analysis

### MCP Prompts (9 Context-Aware Templates)
- **Exploration Analysis** - Analyze recent exploration activities
- **Trading Strategy** - Trading performance and market opportunities
- **Combat Assessment** - Combat statistics and tactical analysis
- **Mining Optimization** - Mining efficiency and resource analysis
- **Mission Guidance** - Mission progress and completion strategies
- **Engineering Progress** - Engineering upgrades and material status
- **Journey Review** - Travel analysis and route optimization
- **Performance Review** - Overall gameplay performance metrics
- **Strategic Planning** - Long-term goal planning and recommendations

### Background Services
- **Journal Monitoring** - Automatic real-time journal file watching
- **Event Processing** - Classification and summarization of game events
- **State Tracking** - Current ship, location, and game mode tracking
- **Automatic Cleanup** - Memory management for long-running sessions

##  Usage Guide

### Starting the MCP Server

Method 1: Direct server startup (for testing)

python src/server.py

Method 2: Via Claude Desktop (recommended for production)

Configure in Claude Desktop config file (see Configuration section)

Method 3: Using virtual environment

venv/Scripts/activate # Windows source venv/bin/activate # Linux/Mac python src/server.py

### Claude Desktop Integration Examples

Once connected to Claude Desktop, you can interact with your Elite Dangerous data:

#### Basic Status Queries

"What's my current location and ship status in Elite Dangerous?" "Show me my recent journal activity from the last hour" "How much fuel and cargo space do I have?"

#### Activity Analysis

"Analyze my exploration progress from the last 24 hours" "What's my trading performance this session?" "Summarize my combat encounters and earnings" "Show me my recent mining activity and profits"

#### AI-Powered Insights

"Generate an exploration strategy prompt based on my recent activities" "Help me optimize my trading routes using my current data" "Analyze my combat performance and suggest improvements" "Create a mission planning prompt for my current situation"

#### Dynamic Theme System *(NEW!)*

"Set my EDCoPilot theme to 'space explorer' with context 'veteran pilot exploring unknown regions'" "Configure my Anaconda crew with scientific expedition personalities" "Generate a themed templates prompt for my current crew configuration" "Apply these AI-generated templates to my EDCoPilot files with validation" "Set my navigator's theme to 'analytical expert' focused on precision navigation"

#### Resource Access

"Get my current ship configuration from elite://status/ship" "Show me recent FSD jumps using the events resource" "Access my exploration summary for the past day"

### MCP Tools Usage Examples

#### Core Data Access

Get current location

await get_current_location()

Returns: {"current_system": "Sol", "coordinates": [0, 0, 0], "docked": true, ...}

Get ship status

await get_current_ship()

Returns: {"ship_type": "Python", "fuel_level": 32.0, "hull_health": 100.0, ...}

Get recent events

await get_recent_events(minutes=60, category="exploration")

Returns: [{"event_type": "Scan", "timestamp": "...", "summary": "...", ...}, ...]

#### Activity Summaries

Exploration analysis

await get_exploration_summary(hours=24)

Returns: {"systems_visited": 15, "bodies_scanned": 47, "earnings": 2500000, ...}

Trading performance

await get_trading_summary(hours=12)

Returns: {"trades_completed": 8, "profit": 5000000, "profit_per_hour": 416667, ...}

Combat statistics

await get_combat_summary(hours=6)

Returns: {"kills": 12, "bounties": 3500000, "combat_bonds": 1200000, ...}

#### AI Prompt Generation

Generate context-aware prompts

await generate_analysis_prompt("exploration", 24)

Returns: Detailed prompt analyzing recent exploration with current context

List available prompts

await list_available_prompts()

Returns: [{"id": "exploration_analysis", "name": "Exploration Analysis", ...}, ...]

### MCP Resources Usage Examples

Resources use URI-based access with query parameters:

#### Status Resources

Current location

await get_resource_data("elite://status/location")

Current ship details

await get_resource_data("elite://status/ship")

Overall game state

await get_resource_data("elite://status/game")

#### Dynamic Data Resources

Recent events with time filter

await get_resource_data("elite://journal/recent?minutes=30")

Events by category

await get_resource_data("elite://events/by-category?category=trading")

Events by specific type

await get_resource_data("elite://events/by-type?type=MarketSell")

#### Activity Summaries

Exploration summary for last 24 hours

await get_resource_data("elite://summary/exploration?hours=24")

Trading analysis for last 12 hours

await get_resource_data("elite://summary/trading?hours=12")

Journey overview for last 2 days

await get_resource_data("elite://summary/journey?hours=48")

### Development API Examples

For direct integration or custom applications:

from src.server import EliteDangerousServer from src.utils.data_store import get_data_store

Initialize server (starts monitoring automatically)

server = EliteDangerousServer()

Access data store directly

data_store = get_data_store() game_state = data_store.get_game_state() recent_events = data_store.get_recent_events(minutes=60)

Use MCP tools programmatically

tools = server.mcp_tools location = await tools.get_current_location() exploration_data = await tools.get_exploration_summary(hours=24)

Access MCP resources

resources = server.mcp_resources ship_status = await resources.get_resource("elite://status/ship")

Generate AI prompts

prompts = server.mcp_prompts strategy_prompt = await prompts.generate_prompt("trading_strategy", 12)

### Error Handling and Troubleshooting

#### Common Issues

Check server status

python scripts/check_dependencies.py

Verify dependencies

python scripts/setup_dependencies.py

Test all functionality

python scripts/run_tests.py

Check logs for issues

tail -f elite_mcp_server.log

#### Resource Caching

Clear resource cache if data seems stale

await refresh_resource_cache()

Individual resource refresh

await get_resource_data("elite://status/location", force_refresh=True)

## Contributing

1. **Check Tests**: Run `python scripts/run_tests.py` to verify functionality
2. **Fork the repository**
3. **Create a feature branch**: `git checkout -b feature/amazing-feature`
4. **Add tests** for new functionality (maintain >90% coverage)
5. **Ensure tests pass**: All tests must pass before submitting
6. **Commit changes**: `git commit -m 'Add amazing feature'`
7. **Push to branch**: `git push origin feature/amazing-feature`
8. **Open a Pull Request**

### Development Workflow
- Use the automation scripts for setup: `scripts/setup_dependencies.py`
- Run tests frequently: `python scripts/run_tests.py`
- Check environment: `python scripts/check_dependencies.py`
- Follow the [AI Directives](ai-directives/README.md) for consistency
- Create session reports for knowledge preservation

### ChatGPT/Codex Integration

Use ChatGPT (OpenAI) models with MCPcapable clients to get the same tool/resource/prompt access as Claude Desktop. Recommended options:

- Continue (VS Code/JetBrains) using OpenAI models
- Cursor with MCP + OpenAI
- Cline (VS Code) with MCP

Quick start:
- Configure the clients `mcpServers` to run this repos Python with `src/server.py`
- Set `ELITE_JOURNAL_PATH` (and optional `ELITE_EDCOPILOT_PATH`, `ELITE_DEBUG`)
- Ask it to use the Elite Dangerous MCP tools (e.g., Whats my current status?)

Full setup and troubleshooting: see `docs/CHATGPT_CODEX_INTEGRATION.md`.

## Documentation

### Core Documentation
- **[Project Implementation Plan](ai-directives/project_implementation_plan.md)** - 15-milestone development roadmap
- **[AI Directives](ai-directives/README.md)** - Development standards and workflow guidelines
- **[Code Quality Lessons](ai-directives/code_quality_lessons.md)** - Technical patterns and best practices

### EDCoPilot Integration
- **[EDCoPilot Chatter Grammar Specification](docs/edcopilot-chatter-grammar.md)** - Formal grammar rules for generating compatible chatter files
- Comprehensive syntax documentation for Space Chatter, Crew Chatter, and Deep Space Chatter
- Token replacement patterns, conditional logic, and validation requirements
- Examples and anti-patterns for error prevention

### Session Reports
- **[Session Reports](ai-directives/session-reports/)** - Historical development context and discoveries
- Knowledge preservation across development sessions
- Technical insights and successful patterns

## License

This project is licensed under the MIT License.

## Acknowledgments

- **Elite Dangerous** by Frontier Developments
- **EDCoPilot** by RazZaFraG  
- **Model Context Protocol** by Anthropic
- **Claude Desktop** by Anthropic

---

**Note**: This project is not officially affiliated with Frontier Developments, Anthropic, or the EDCoPilot project. Elite Dangerous is a trademark of Frontier Developments plc.