Elite Dangerous Local AI Tie In MCP

《精英危险：本地AI联动MCP》

一个模型上下文协议（MCP）服务器，它实现了《精英危险》（Elite Dangerous）与Claude桌面版之间的实时集成，使您能够利用人工智能分析游戏数据，并动态生成EDCoPilot自定义内容。

特点/功能

实时日志监控自动监控《精英危险》（Elite Dangerous）日志文件，以实时捕获游戏事件

历史数据加载在启动时处理现有的日志文件（过去24小时内的），以便立即获取数据

历史数据查询 *新*使用自然语言（例如，“上个月到两周前”）或绝对日期，在灵活的时间范围内搜索您的完整游戏历史记录

Claude桌面集成提供MCP工具、资源和提示，用于AI驱动的游戏玩法分析

EDCoPilot 集成根据您当前的游戏状态，生成动态的自定义聊天内容、角色对话和语音扩展

动态主题系统 *新*基于人工智能的个性化主题，配备船舰专属的多船员支持，打造沉浸式角色扮演与动态角色发展体验

综合分析追踪探索进度、交易表现、战斗统计及旅程总结

灵活配置可配置的路径、事件限制和集成选项

Claude Desktop Working

无头EDCoPilot生成器

在不打开Claude Desktop的情况下生成EDCoPilot聊天文件。

• 命令： python scripts/generate_edcopilot.py
• 查看完整用法： docs/HEADLESS_CLI.md
• 示例：

- python scripts/generate_edcopilot.py （默认设置：最近7天；主题“沧桑老兵太空船长”；情境“布满老茧的双手，无垠的天际”） - 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

快速入门

自动设置（推荐）

为了获得最快的设置体验，请使用我们的自动化脚本：

# 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

先决条件

• Python 3.9及以上版本 （推荐使用 Python 3.11+）
• Git（一种分布式版本控制系统） 用于版本控制
• 《精英危险》（Elite Dangerous） 已安装并运行
• Claude 桌面版 应用程序
• EDCoPilot（假设为某产品或服务名称，可译为“ED导航助手”或根据具体上下文调整） （可选，用于语音集成）

手动安装

如果您更喜欢手动设置：

1. 克隆仓库：

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

1. 创建虚拟环境：

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

1. 安装依赖项：

   pip install -r requirements.txt

1. 验证安装：

   python scripts/check_environment.py

查看 测试指南 如需详细的设置和验证说明，请参阅。

测试与开发

可用脚本

• scripts/setup_dependencies.py - 自动化环境设置，包含包验证
• scripts/check_environment.py - 全面的环境验证
• scripts/run_tests.py - 运行完整的测试套件并生成覆盖率报告

运行测试

# 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

测试覆盖率

• 592项测试 与……一同通过/顺利过关 83%的代码覆盖率
• 实时监控 通过模拟日志事件和解决竞态条件问题进行了验证
• 事件处理 在17个类别中测试了213种事件类型
• 全面的活动报道 分类准确率高达98%（里程碑17）
• 历史数据检索 包含61项测试，涵盖日期解析、自然语言查询和范围过滤（里程碑18）
• 舰队航空母舰活动 包含8项针对CarrierStats、CarrierFinance以及船员/模块管理的测试（问题#18）
• 船队载货跟踪 包含9项针对货物转运事件和库存管理的测试（问题#15）
• 数据存储 已验证并发访问模式和线程安全性
• MCP服务器 经过全面的单元测试和集成测试验证
• MCP工具、资源和提示 在边缘情况下进行了广泛测试
• 动态主题系统 经过159项全面测试，涵盖性能、边界情况和集成场景
• 文件监控中的竞态条件 已测试并修复（问题#12）

文档

• 测试指南 - 全面的测试说明
• 日志事件参考 - 包含所有213种支持事件类型的完整参考 *新*
• 动态主题系统指南 - AI驱动的船员主题完整指南
• 无头命令行界面指南 - 无需Claude Desktop的独立EDCoPilot生成
• 脚本文档 - 自动化脚本详情
• 人工智能指令 - 人工智能助手开发指南

配置

Claude 桌面集成

步骤1：定位Claude桌面配置文件

Windows： %APPDATA%\Claude\claude_desktop_config.json macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json Linux（发音为“林克斯”）： ~/.config/Claude/claude_desktop_config.json

步骤2：添加MCP服务器配置

在您的Claude桌面配置文件中添加以下内容：

{
  "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"
      }
    }
  }
}

步骤3：更新路径配置

关键的将配置中的路径替换为您的实际系统路径：

1. 服务器路径 (args): 更新为您的实际仓库位置
2. Python 环境使用虚拟环境中Python可执行文件的完整路径：

- Windows: C:/path/to/project/venv/Scripts/python.exe - Linux/Mac（注：此处为直接翻译，保持原样，因为“Linux”和“Mac”都是计算机操作系统或平台的名称，无需进一步解释或转换）： C:/path/to/project/venv/bin/python

1. 日志路径 (ELITE_JOURNAL_PATH):

- Windows: C:/Users/[Username]/Saved Games/Frontier Developments/Elite Dangerous - Steam（注：Steam是一个数字发行服务平台，主要面向电子游戏，提供游戏下载、购买、评测等功能，此处直接保留原英文词汇，因为“Steam”在中文中通常不直接翻译，而是作为专有名词使用。）: C:/Users/[Username]/Saved Games/Frontier Developments/Elite Dangerous - 史诗般的与Steam相同 - Linux: ~/.local/share/Steam/steamapps/compatdata/359320/pfx/drive_c/users/steamuser/Saved Games/Frontier Developments/Elite Dangerous

1. EDCoPilot Path 翻译为中文是：“EDCoPilot 路径” （可选）：如果您使用EDCoPilot语音集成，请进行更新

步骤4：重启Claude桌面版

保存配置文件后，重启 Claude Desktop 以使更改生效。

第五步：验证连接

在 Claude Desktop 中，尝试提问：

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

如果配置正确，Claude 将使用 MCP 工具回复您当前的游戏状态。

### 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桌面集成示例

一旦连接到Claude Desktop，您就可以与您的Elite Dangerous数据进行交互：

#### 基本状态查询

"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?"

#### 活动分析

"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"

#### 基于人工智能的见解

"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"

#### 动态主题系统 *新*

"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"

#### 资源访问

"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工具使用示例

#### 核心数据访问

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": "...", ...}, ...]

#### 活动摘要

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提示生成

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资源使用示例

资源使用基于URI的访问方式，并带有查询参数：

#### 状态资源

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")

#### 动态数据资源

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")

#### 活动总结

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")

### 开发API示例

对于直接集成或自定义应用：

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)

### 错误处理和故障排除

#### 常见问题

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

#### 资源缓存

Clear resource cache if data seems stale

await refresh_resource_cache()

Individual resource refresh

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

## 做出贡献

1. **检查测试**跑 `python scripts/run_tests.py` 验证功能
1. **为仓库创建分支（或：克隆仓库）**
1. **创建一个特性分支**： `git checkout -b feature/amazing-feature`
1. **添加测试** 对于新功能（保持>90%的覆盖率）
1. **确保测试通过**提交前所有测试必须通过
1. **提交更改**： `git commit -m 'Add amazing feature'`
1. **推送到分支**: `git push origin feature/amazing-feature`
1. **提交一个拉取请求（或合并请求）**

### 开发工作流程

- 使用自动化脚本进行设置： `scripts/setup_dependencies.py`
- 经常运行测试： `python scripts/run_tests.py`
- 检查环境： `python scripts/check_dependencies.py`
- 遵循 [人工智能指令](ai-directives/README.md) 为了保持一致性
- 创建会话报告以保存知识

### ChatGPT/Codex 集成

使用支持MCP（多客户端协议）的客户端连接ChatGPT（OpenAI）模型，以获得与Claude桌面版相同的工具/资源/提示访问权限。推荐选项：

- 继续使用OpenAI模型（VS Code/JetBrains）
- MCP + OpenAI 的光标
- Cline（VS Code）与MCP结合使用

快速入门：

- 配置客户端 `mcpServers` 运行这个Python仓库（或项目） `src/server.py`
- 设置 `ELITE_JOURNAL_PATH` （以及可选的 `ELITE_EDCOPILOT_PATH`， `ELITE_DEBUG`)
- 询问它使用Elite Dangerous的MCP工具（例如，我的当前状态是什么？）

完整设置及故障排除：参见 `docs/CHATGPT_CODEX_INTEGRATION.md`.

## 文档

### 核心文档

- **[项目实施计划](ai-directives/project_implementation_plan.md)** - 15个里程碑式的发展路线图
- **[人工智能指令（或指南）](ai-directives/README.md)** - 开发标准和工作流程指南
- **[代码质量教训](ai-directives/code_quality_lessons.md)** - 技术模式和最佳实践

### EDCoPilot 集成

- **[EDCoPilot聊天语法规范](docs/edcopilot-chatter-grammar.md)** - 用于生成兼容聊天文件的正式语法规则
- 《太空聊天》、《乘员聊天》和《深空聊天》的全面语法文档
- 令牌替换模式、条件逻辑和验证要求
- 防止错误的示例与反面模式

### 会议报告

- **[会议报告](ai-directives/session-reports/)** - 历史发展背景与发现
- 在开发会议期间的知识保存
- 技术洞见与成功模式

## 许可证

这个项目遵循MIT许可证授权。

## 致谢

- **《精英危险》（Elite Dangerous）** 由Frontier Developments开发
- **EDCoPilot（可译为“ED飞行员助手”或根据具体上下文调整为更贴切的名称）** 由 RazZaFraG（注：这可能是一个用户名或昵称，根据上下文，这里直接保留原样）
- **模型上下文协议** 由Anthropic开发
- **Claude Desktop（中文可译为“Claude桌面版”）** 由Anthropic（公司）开发/推出

______________________________________________________________________

**注**这个项目并非正式隶属于Frontier Developments、Anthropic或EDCoPilot项目。Elite Dangerous是Frontier Developments plc的注册商标。