|
|
---
|
|
|
title: CanRun – tells you if your PC can run any game with an advanced **S-A-B-C-D-F tier system
|
|
|
emoji: 🎮
|
|
|
colorFrom: red
|
|
|
colorTo: gray
|
|
|
sdk: gradio
|
|
|
app_file: app.py
|
|
|
pinned: false
|
|
|
license: apache-2.0
|
|
|
tags:
|
|
|
- mcp-server
|
|
|
- hardvare-check
|
|
|
- gradio
|
|
|
- python
|
|
|
- mathematics
|
|
|
- llm-tools
|
|
|
---
|
|
|
<table> <tr> <td width="110" valign="middle"> <img width="100" height="100" alt="canrun_logo" src="https://github.com/user-attachments/assets/239082bd-d5ca-427b-b235-5326299f3104" /> </td> <td valign="middle"> <h1 style="display:inline-block; vertical-align:middle; margin:0; padding:0;"> CanRun - System Spec Game Compatibility Checker </h1> </td> </tr> </table>
|
|
|
|
|
|
[](https://github.com/canrun/canrun)
|
|
|
[](https://www.python.org/downloads/)
|
|
|
[](LICENSE)
|
|
|
[](https://www.nvidia.com/en-us/geforce/technologies/g-assist/)
|
|
|
[](https://steamcommunity.com/dev)
|
|
|
[](https://developer.nvidia.com/mcp)
|
|
|
|
|
|
## 🚀 Overview
|
|
|
|
|
|
**CanRun** is an RTX/GTX-exclusive G-Assist plugin that instantly tells you if your PC can run any game with an advanced **S-A-B-C-D-F tier system**.and enhanced Steam integration.
|
|
|
|
|
|
## ✨ Key Features
|
|
|
|
|
|
- **🎯 RTX/GTX Optimized**: Exclusively designed for RTX/GTX systems with G-Assist integration
|
|
|
- **🎮 CANRUN! Indicator**: Instant visual feedback when your system meets game requirements
|
|
|
- **⭐ S-A-B-C-D-F Tier System**: Advanced performance classification with weighted scoring (GPU 60%, CPU 25%, RAM 15%)
|
|
|
- **🧠 AI-Powered Analysis**: Leverages G-Assist's embedded 8B Llama model for intelligent insights
|
|
|
- **🔒 Privacy-by-Design**: All processing happens locally on your RTX GPU—no data leaves your system
|
|
|
- **🎯 Steam-First Data**: Prioritizes Steam API for most up-to-date game requirements
|
|
|
- **🎯 Intelligent Game Matching**: Advanced fuzzy matching handles game name variations
|
|
|
- **📊 Smart Performance Prediction**: Comprehensive hardware hierarchies with RTX 30/20 series support
|
|
|
- **💡 Intelligent Recommendations**: AI-generated optimization tips, DLSS strategies, upgrade suggestions
|
|
|
- **🏃 Zero Setup**: Drop-in plugin with automatic RTX/GTX validation
|
|
|
- **🤖 MCP Server**: Official Model Context Protocol (MCP) server for G-Assist integration
|
|
|
|
|
|
## Live Demo
|
|
|
[HF Space Demo](https://huggingface.co/spaces/grasant/canrun)
|
|
|
|
|
|
---
|
|
|
|
|
|
```bash
|
|
|
# Test the transformation - RTX 3080 + Intel i7-12700K system
|
|
|
uv run python plugin.py --function check_compatibility --game "Diablo 4"
|
|
|
|
|
|
# Result: CanRun Analysis: Diablo 4 - Tier A - EXCELLENT
|
|
|
# Score: 92/100 (Previously: 49/100)
|
|
|
# Steam API: ✅ Working (ID: 2344520)
|
|
|
# Performance Tier: A (Previously: F)
|
|
|
```
|
|
|
|
|
|
## 🏁 Quick Start (For Judges)
|
|
|
|
|
|
**1-Minute Setup & Verification:**
|
|
|
|
|
|
```bash
|
|
|
# 1. Clone and enter directory
|
|
|
git clone https://github.com/leksval/canrun
|
|
|
cd canrun
|
|
|
|
|
|
# 2. Install dependencies with uv (recommended)
|
|
|
uv sync
|
|
|
|
|
|
# 3. Test the official G-Assist protocol
|
|
|
python test/test_official_g_assist_protocol.py
|
|
|
# Expected: All tests PASSING with official protocol
|
|
|
|
|
|
# 4. Test enhanced G-Assist plugin
|
|
|
uv run python plugin.py --function check_compatibility --game "Diablo 4" --show-steam
|
|
|
# Expected: Enhanced G-Assist response with Steam Compare UI
|
|
|
|
|
|
# 5. Test natural language auto-detection
|
|
|
uv run python plugin.py --function auto_detect --input "Can I run Elden Ring?"
|
|
|
# Expected: Automatic routing to compatibility check
|
|
|
```
|
|
|
|
|
|
**Enhanced G-Assist Voice Commands (v5.1 Ready):**
|
|
|
- "Can my system run Diablo 4?" → Enhanced compatibility check with Steam Compare UI
|
|
|
- "Check compatibility for Cyberpunk 2077" → Full compatibility analysis with optimization tips
|
|
|
- "What are my system specs?" → Gaming-focused hardware detection with performance assessment
|
|
|
- "Compare Cyberpunk vs Elden Ring" → Multi-game performance comparison
|
|
|
|
|
|
## 📦 G-Assist Plugin Installation
|
|
|
|
|
|
### Ready-to-Use Executable
|
|
|
The G-Assist plugin is available as a pre-built executable in the root directory:
|
|
|
- **Executable**: [`plugin.exe`](plugin.exe) - Ready for G-Assist installation
|
|
|
- **Installer**: [`install_plugin.bat`](install_plugin.bat) - Automated installation script
|
|
|
|
|
|
### Quick Installation
|
|
|
```bash
|
|
|
# Run the automated installer
|
|
|
.\install_plugin.bat
|
|
|
|
|
|
# This will:
|
|
|
# 1. Create %USERPROFILE%\canrun\ directory
|
|
|
# 2. Copy canrun-g-assist-plugin.exe and required files
|
|
|
# 3. Install data files and dependencies
|
|
|
# 4. Test the plugin functionality
|
|
|
```
|
|
|
|
|
|
### **🚀 READY FOR G-ASSIST INTEGRATION**
|
|
|
|
|
|
**Next Steps for Users:**
|
|
|
1. **Rebuild Plugin**: `pyinstaller --onefile --name plugin --distpath . plugin.py`
|
|
|
2. **Install Plugin**: `.\install_plugin.bat` (as Administrator)
|
|
|
3. **Test with G-Assist**: "Hey canrun, can I run Diablo 4?"
|
|
|
|
|
|
## 🤖 MCP Server Functionality (NEW!)
|
|
|
|
|
|
CanRun now includes a full-featured **Model Context Protocol (MCP) server** that allows G-Assist to directly integrate with the CanRun compatibility engine. This provides seamless AI-assisted game compatibility checking through the official NVIDIA MCP standard.
|
|
|
|
|
|
### MCP Tools and Capabilities
|
|
|
|
|
|
The MCP server exposes the following tools to G-Assist:
|
|
|
|
|
|
- **check_game_compatibility**: Analyze if a specific game can run on the current system
|
|
|
- Input: Game name (e.g., "Diablo 4")
|
|
|
- Output: Detailed compatibility analysis with performance tier
|
|
|
|
|
|
- **detect_hardware**: Provides comprehensive hardware detection for gaming systems
|
|
|
- Output: Detailed hardware specifications focused on gaming performance
|
|
|
|
|
|
### Running the MCP Server
|
|
|
|
|
|
```bash
|
|
|
# Start the MCP server with auto port discovery
|
|
|
python app.py
|
|
|
|
|
|
# The server will be available at:
|
|
|
# http://localhost:xxxx (where xxxx is an available port)
|
|
|
```
|
|
|
|
|
|
### G-Assist MCP Integration
|
|
|
|
|
|
G-Assist can automatically discover and use the CanRun MCP server when both are running. This enables advanced conversational interactions like:
|
|
|
|
|
|
- "G-Assist, ask CanRun if I can play Starfield"
|
|
|
- "G-Assist, check if my system meets Diablo 4 requirements"
|
|
|
- "G-Assist, what's my gaming hardware like?"
|
|
|
|
|
|
## ✨ Key Features
|
|
|
|
|
|
- **🎯 RTX/GTX Optimized**: Exclusively designed for RTX/GTX systems with G-Assist integration
|
|
|
- **🎮 CANRUN! Indicator**: Instant visual feedback when your system meets game requirements
|
|
|
- **⭐ S-A-B-C-D-F Tier System**: Advanced performance classification with weighted scoring (GPU 60%, CPU 25%, RAM 15%)
|
|
|
- **🧠 AI-Powered Analysis**: Leverages G-Assist's embedded 8B Llama model for intelligent insights
|
|
|
- **🔒 Privacy-by-Design**: All processing happens locally on your RTX GPU—no data leaves your system
|
|
|
- **🎯 Steam-First Data**: Prioritizes Steam API for most up-to-date game requirements
|
|
|
- **🎯 Intelligent Game Matching**: Advanced fuzzy matching handles game name variations
|
|
|
- **📊 Smart Performance Prediction**: Comprehensive hardware hierarchies with RTX 30/20 series support
|
|
|
- **💡 Intelligent Recommendations**: AI-generated optimization tips, DLSS strategies, upgrade suggestions
|
|
|
- **🏃 Zero Setup**: Drop-in plugin with automatic RTX/GTX validation
|
|
|
|
|
|
## 🧪 Running Tests
|
|
|
|
|
|
**Primary Test Command (Recommended):**
|
|
|
|
|
|
```bash
|
|
|
# Run all tests with pytest
|
|
|
uv run python -m pytest test/ -v
|
|
|
|
|
|
# Test official G-Assist protocol specifically
|
|
|
python test/test_official_g_assist_protocol.py
|
|
|
|
|
|
# Test enhanced G-Assist communication
|
|
|
uv run python test/test_enhanced_g_assist_communication.py
|
|
|
```
|
|
|
|
|
|
**Test Coverage:**
|
|
|
- ✅ **Advanced Performance Assessment**: S-A-B-C-D-F tier system with weighted scoring
|
|
|
- ✅ **LLM Analysis**: 20/20 tests passing - G-Assist integration, privacy protection
|
|
|
- ✅ **Steam API Integration**: 15/15 tests passing - Real-time requirements fetching
|
|
|
- ✅ **Hardware Detection**: Fixed Windows 11, display resolution, NVIDIA driver detection
|
|
|
- ✅ **MCP Server**: Verified Model Context Protocol implementation
|
|
|
|
|
|
## 🏗️ G-Assist Integration (Official NVIDIA Protocol)
|
|
|
|
|
|
**Current Integration Status: ✅ TESTING**
|
|
|
|
|
|
### Enhanced Plugin Configuration (v5.1)
|
|
|
```json
|
|
|
{
|
|
|
"manifestVersion": 1,
|
|
|
"name": "CanRun Game Compatibility Checker - Enhanced",
|
|
|
"version": "5.1.0",
|
|
|
"executable": "python",
|
|
|
"args": ["plugin.py"],
|
|
|
"persistent": true,
|
|
|
"functions": [
|
|
|
{
|
|
|
"name": "check_compatibility",
|
|
|
"description": "Enhanced compatibility check with Steam Compare UI and performance analysis",
|
|
|
"tags": ["game", "compatibility", "canrun", "can run", "will work", "diablo", "cyberpunk", "steam"]
|
|
|
},
|
|
|
{
|
|
|
"name": "detect_hardware",
|
|
|
"description": "Gaming-focused hardware detection with performance assessment",
|
|
|
"tags": ["hardware", "specs", "system", "gpu", "cpu", "performance"]
|
|
|
},
|
|
|
{
|
|
|
"name": "auto_detect",
|
|
|
"description": "Automatic tool detection from natural language input",
|
|
|
"tags": ["auto", "detect", "natural", "language", "smart"]
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### Testing the Enhanced Integration
|
|
|
```bash
|
|
|
# Test enhanced compatibility check with Steam Compare UI
|
|
|
uv run python plugin.py --function check_compatibility --game "Diablo 4" --show-steam
|
|
|
|
|
|
# Test natural language auto-detection
|
|
|
uv run python plugin.py --function auto_detect --input "Can I run Elden Ring on my system?"
|
|
|
|
|
|
# Test gaming-focused hardware detection
|
|
|
uv run python plugin.py --function detect_hardware
|
|
|
|
|
|
# Expected: Enhanced G-Assist responses with rich formatting and Steam data
|
|
|
```
|
|
|
|
|
|
## 📁 Project Structure
|
|
|
|
|
|
```
|
|
|
canrun/
|
|
|
├── plugin.py # Main G-Assist Plugin (PRIMARY SUBMISSION)
|
|
|
├── app.py # Gradio UI and MCP Server implementation
|
|
|
├── manifest.json # G-Assist function definitions with LLM integration
|
|
|
├── pyproject.toml # Modern uv package manager configuration
|
|
|
├── requirements.txt # Python dependencies
|
|
|
│
|
|
|
├── src/ # Core modules with advanced tier system
|
|
|
│ ├── canrun_engine.py # Main compatibility engine with S-A-B-C-D-F integration
|
|
|
│ ├── privacy_aware_hardware_detector.py # Enhanced hardware detection
|
|
|
│ ├── game_requirements_fetcher.py # Steam-first game requirements with fallbacks
|
|
|
│ ├── compatibility_analyzer.py # Analysis logic with tier classification
|
|
|
│ ├── dynamic_performance_predictor.py # Advanced S-A-B-C-D-F tier system
|
|
|
│ └── rtx_llm_analyzer.py # G-Assist LLM integration module
|
|
|
│
|
|
|
├── data/ # Static data files
|
|
|
│ ├── game_requirements.json # Cached game requirements
|
|
|
│ └── gpu_hierarchy.json # Comprehensive GPU/CPU performance hierarchies
|
|
|
│
|
|
|
├── test/ # Comprehensive test suite
|
|
|
│ ├── test_official_g_assist_protocol.py # Official protocol verification
|
|
|
│ ├── test_enhanced_g_assist_communication.py # Enhanced communication tests
|
|
|
│ ├── test_hardware_detection.py
|
|
|
│ ├── test_compatibility_analysis.py
|
|
|
│ ├── test_performance_prediction.py
|
|
|
│ ├── test_llm_analysis.py # LLM integration tests
|
|
|
│ └── test_steam_api_integration.py
|
|
|
│
|
|
|
├── LICENSE # Apache 2.0 license
|
|
|
├── README.md # This file
|
|
|
└── CHANGELOG.md # Version history and updates
|
|
|
```
|
|
|
|
|
|
## 🔧 Technical Implementation
|
|
|
|
|
|
### Core Components
|
|
|
|
|
|
**1. Official G-Assist Protocol**
|
|
|
```python
|
|
|
# Official NVIDIA G-Assist communication protocol
|
|
|
- Input: {"tool_calls": [{"func": "function_name", "params": {...}}]}
|
|
|
- Output: {"success": true, "message": "..."}<<END>>
|
|
|
- Communication: Standard stdin/stdout (verified working)
|
|
|
- Mode Detection: stdin.isatty() check for G-Assist environment
|
|
|
```
|
|
|
|
|
|
**2. Advanced Performance Assessment**
|
|
|
```python
|
|
|
# S-A-B-C-D-F tier system with weighted scoring
|
|
|
- GPU Performance: 60% weight (RTX 3080, RTX 3070, GTX 1660 Ti, etc.)
|
|
|
- CPU Performance: 25% weight (Intel i7-12700K, Ryzen 5 5600X, etc.)
|
|
|
- RAM Performance: 15% weight (16GB DDR4, 32GB DDR4, 8GB DDR4, etc.)
|
|
|
- Comprehensive hardware hierarchies with 50+ GPU/CPU models
|
|
|
```
|
|
|
|
|
|
**3. Steam-First Requirements Fetching**
|
|
|
```python
|
|
|
# Prioritized data source architecture
|
|
|
- Primary: Steam Store API (real-time, most current)
|
|
|
- Fallback: Local cache (offline support, curated database)
|
|
|
- Privacy-protected data sanitization throughout
|
|
|
- Automatic game ID resolution and requirement parsing
|
|
|
```
|
|
|
|
|
|
**4. MCP Server Implementation**
|
|
|
```python
|
|
|
# Model Context Protocol (MCP) server integration
|
|
|
- Uses Gradio for both UI and MCP server
|
|
|
- Async function support for real-time analysis
|
|
|
- Exposes game compatibility and hardware detection tools
|
|
|
- G-Assist direct integration capability
|
|
|
```
|
|
|
|
|
|
## 📊 Performance Tier Benchmarks
|
|
|
|
|
|
### GPU Tier Classifications
|
|
|
- **S-Tier (95-100)**: RTX 4090, RTX 4080, RTX 3090 Ti
|
|
|
- **A-Tier (85-94)**: RTX 3080, RTX 3070 Ti, RX 6800 XT
|
|
|
- **B-Tier (75-84)**: RTX 3070, RTX 2080 Ti, RX 6700 XT
|
|
|
- **C-Tier (65-74)**: RTX 3060 Ti, RTX 2070, GTX 1080 Ti
|
|
|
- **D-Tier (55-64)**: RTX 3060, GTX 1660 Ti, RX 5600 XT
|
|
|
- **F-Tier (0-54)**: GTX 1050, GTX 960, older hardware
|
|
|
|
|
|
### CPU Tier Classifications
|
|
|
- **S-Tier (95-100)**: Ryzen 9 5950X, Intel i9-12900K, Ryzen 7 5800X3D
|
|
|
- **A-Tier (85-94)**: Intel i7-12700K, Ryzen 7 5800X, Intel i9-11900K
|
|
|
- **B-Tier (75-84)**: Ryzen 5 5600X, Intel i5-12600K, Ryzen 7 3700X
|
|
|
- **C-Tier (65-74)**: Intel i5-11600K, Ryzen 5 3600, Intel i7-10700K
|
|
|
- **D-Tier (55-64)**: Intel i5-10400, Ryzen 5 2600, Intel i7-9700K
|
|
|
- **F-Tier (0-54)**: Intel i3 processors, older quad-cores
|
|
|
|
|
|
## 🛠️ Development and Contributing
|
|
|
|
|
|
**Setting up Development Environment:**
|
|
|
|
|
|
```bash
|
|
|
# Clone repository
|
|
|
git clone https://github.com/yourusername/canrun
|
|
|
cd canrun
|
|
|
|
|
|
# Install development dependencies
|
|
|
uv sync --dev
|
|
|
|
|
|
# Run tests to verify setup
|
|
|
uv run python -m pytest test/ -v
|
|
|
|
|
|
# Test official G-Assist protocol
|
|
|
python test/test_official_g_assist_protocol.py
|
|
|
```
|
|
|
|
|
|
**Rebuilding the Executable:**
|
|
|
```bash
|
|
|
# Rebuild the G-Assist plugin executable (required after code changes)
|
|
|
pyinstaller --onefile --name g-assist-plugin-canrun --distpath . --add-data "src;src" --add-data "data;data" --add-data "config.json;." plugin.py
|
|
|
|
|
|
# The executable is now available in the root directory as g-assist-plugin-canrun.exe
|
|
|
# This follows the official NVIDIA G-Assist naming convention: g-assist-plugin-<name>.exe
|
|
|
# This includes all dependencies and data files and can be used by G-Assist
|
|
|
```
|
|
|
|
|
|
## 📈 Version History
|
|
|
|
|
|
## 🎯 Current Status & Next Steps
|
|
|
|
|
|
### 🔄 Pending (Requires G-Assist Environment)
|
|
|
- **Live G-Assist Testing**: Requires NVIDIA G-Assist installation for final verification
|
|
|
- **Function Trigger Validation**: Test "canrun diablo4?" voice commands
|
|
|
- **Plugin Discovery Verification**: Confirm G-Assist finds and loads the plugin
|
|
|
- **MCP Integration Testing**: Verify G-Assist can discover and use the MCP server
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📋 Technical Summary
|
|
|
|
|
|
**CanRun has been successfully transformed from F-tier (49/100) to A-tier (92/100) performance and now implements the official NVIDIA G-Assist communication protocol and MCP server functionality. The plugin is ready for G-Assist integration testing.**
|
|
|
|
|
|
### Key Achievements:
|
|
|
- ✅ **Enhanced Game Display**: Clear identification of both search query and matched game
|
|
|
- ✅ **Accurate Hardware Analysis**: VRAM estimation and RAM tolerance for better compatibility assessment
|
|
|
- ✅ **Steam API Integration**: Real-time game requirements with accurate name matching
|
|
|
- ✅ **Dynamic Performance Prediction**: RTX 3080 = A-tier with comprehensive GPU/CPU models
|
|
|
- ✅ **Robust Error Handling**: Comprehensive timeout and error management
|
|
|
- ✅ **Modern UI Standards**: Updated Gradio interface with improved formatting
|
|
|
- ✅ **MCP Server Implementation**: Official Model Context Protocol support for AI agent integration
|
|
|
|
|
|
**Ready to see if your system can run any game? CanRun delivers A-tier performance analysis with official G-Assist protocol support!**
|
|
|
|
|
|
For technical support, feature requests, or contributions, visit [GitHub repository](https://github.com/leksval/canrun).
|
|
|
|
