AI Interaction Tool

What is AI Interaction Tool about?

The tool offers a modern PyQt5 interface that lets users compose messages, attach files, folders, and multiple images, then returns the content in a predefined tag format for seamless integration with AI agents via MCP.

How to use AI Interaction Tool?

1. Clone the repository and install the Python dependencies listed in requirements.txt.
2. Configure the MCP server in Claude Desktop (or another MCP‑compatible client) by pointing the command to python mcp_server.py.
3. Run the UI with the command python main.py --ui (or python mcp_server.py to start the server only).
4. When the popup appears, type your message, attach files/folders/images, toggle the “Save images” option if needed, and submit.
5. The tool returns a structured response containing the message, attached paths, workspace identifier, and a <AI_INTERACTION_CONTINUE_CHAT> flag.

Key features of AI Interaction Tool

• Interactive UI popup built with PyQt5
• Drag‑and‑drop and multi‑image attachment with preview and removal
• Secure local storage of images in user_images/
• File and folder attachment with workspace‑aware relative paths
• Multi‑language support (English & Vietnamese)
• Tag‑based output format compatible with system‑prompt rules
• Automatic cleanup of unused images when the save option is disabled
• Configurable “Maximum Cognitive Power” flag for AI agents

Use cases of AI Interaction Tool

• Supplying complex, multi‑file context to an AI assistant (e.g., code reviews, design critiques)
• Collecting user‑provided screenshots or diagrams to enrich AI responses
• Enabling a conversational loop where the AI can request additional files or images
• Integrating with Claude Desktop, Cursor IDE, or any MCP‑compatible platform for seamless workflow automation

FAQ from the AI Interaction Tool

Q: Do I need an internet connection for the UI? A: No. All operations, including image handling, are performed locally.

Q: Which image formats are supported? A: PNG, JPG, JPEG, GIF, BMP, and WEBP.

Q: How does the tool ensure privacy? A: Images are stored only in the local user_images/ directory; no external uploads occur.

Q: Can I disable image persistence? A: Yes. Uncheck the “Save images” checkbox; the tool will auto‑clean up attached images after the session.

Q: What if the UI does not appear? A: Verify that PyQt5 is installed correctly and that your Python version is 3.8 or newer.

Q: How do I integrate the tool with an AI agent? A: Copy the content of rule_for_ai_EN.txt or rule_for_ai_VI.txt into the agent’s custom instructions. The agent will then parse the tags produced by the tool.

AI Interaction Tool - MCP Server

Modern AI interaction tool with advanced UI and powerful features for Model Context Protocol (MCP)

🚀 Core Features

🎯 Main Capabilities

• Interactive UI Popup for content input and conversation control
• File/Folder Attachment from workspace with validation and preview
• 🖼️ Image Attachment System with drag & drop, multi-image support
• Multi-language Support (English/Vietnamese)
• Maximum Cognitive Power activation for peak AI performance
• Tag-based Output Format integrated with system prompt rules
• Workspace-aware Path Processing for cross-project compatibility

🔧 New in v2.2.0 (Latest)

• 🖼️ Image Attachment Support with drag & drop functionality
• 🛡️ Security Enhanced - secure path storage in user_images directory
• 💾 Persistent Image State - checkbox state saves correctly
• 🎯 Multi-image Management - attach, preview, and remove multiple images
• 🔄 Database Auto-cleanup - automatic image cleanup when disabled

🔧 Previous v2.1.0

• Enhanced UI/UX with modern PyQt5 interface
• Structured Tag-based Output for perfect AI agent integration
• Debounce Configuration with smart auto-save mechanisms
• Cursor IDE Integration with comprehensive setup guide

📋 Installation & Setup Guide

📥 Step 1: Clone Repository

git clone https://github.com/your-username/AI-interaction.git
cd AI-interaction

🐍 Step 2: Install Python

• Requirement: Python 3.8+
• Download from python.org
• Or use package manager:

  # Windows with Chocolatey
  choco install python
  
  # macOS with Homebrew
  brew install python
  
  # Ubuntu/Debian
  sudo apt update && sudo apt install python3 python3-pip
  

📦 Step 3: Install Dependencies

# Using pip
pip install -r requirements.txt

# Or using uv (recommended for performance)
pip install uv
uv pip install -r requirements.txt

⚙️ Step 4: Configure MCP Server in Claude Desktop

Add the following configuration to Claude Desktop config file:

Config file paths:

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

Configuration content:

{
  "mcpServers": {
    "AI_interaction": {
      "command": "python",
      "args": ["E:/MCP-servers-github/AI-interaction/mcp_server.py"],
      "stdio": true,
      "enabled": true
    }
  }
}

⚠️ Important: Replace E:/MCP-servers-github/AI-interaction/mcp_server.py with the absolute path to mcp_server.py on your system.

🧠 Step 5: Configure AI Agent Rules (REQUIRED)

For proper AI agent operation with ai_interaction tool, you MUST setup custom instructions:

📋 How to Add Custom Instructions:

1. Open Claude Desktop or access Claude web interface
2. Find "Custom Instructions" or "Add custom instructions" in settings
3. Copy entire content from one of the rule files:
   • 🇻🇳 Vietnamese: rule_for_ai_VI.txt
   • 🇺🇸 English: rule_for_ai_EN.txt
4. Paste into custom instructions field and save

🎯 Why This is Necessary:

• ✅ Behavioral Framework: Rules define how AI agent processes ai_interaction output
• ✅ Thinking Protocols: Activates high-level thinking patterns for quality responses
• ✅ Ultra-Enhancement Modes: 10 cognitive modes for maximum performance
• ✅ Tag Processing: Reads and processes control tags like <AI_INTERACTION_CONTINUE_CHAT>
• ✅ Continue Logic: Auto-recall ai_interaction when continue_chat=true

📁 Rule Files Location:

AI-interaction/
├── rule_for_ai_VI.txt    # Vietnamese rules 
├── rule_for_ai_EN.txt    # English rules
└── ...

⚡ Quick Setup Commands:

# View Vietnamese rules content
cat rule_for_ai_VI.txt

# View English rules content  
cat rule_for_ai_EN.txt

# Copy to clipboard (Windows)
type rule_for_ai_VI.txt | clip

# Copy to clipboard (macOS)
cat rule_for_ai_VI.txt | pbcopy

# Copy to clipboard (Linux)
cat rule_for_ai_VI.txt | xclip -selection clipboard

🚀 Step 6: Configure Cursor IDE (Recommended)

Cursor is the recommended IDE for AI development with this tool:

📋 Cursor Setup Steps:

1. Download Cursor: https://cursor.sh/
2. Install and open workspace: Open AI-interaction folder
3. Configure MCP in Cursor:
   • Open Command Palette (Cmd/Ctrl + Shift + P)
   • Search "Configure MCP Servers"
   • Add AI_interaction server config
4. Setup custom instructions:
   • Copy content from rule_for_ai_VI.txt or rule_for_ai_EN.txt
   • Paste into "Custom Instructions" field in custom mode Agent:

🎯 Cursor Advantages:

• ✅ Native MCP Support: Built-in integration with MCP servers
• ✅ AI-First IDE: Optimized for AI development workflows
• ✅ Real-time Suggestions: Context-aware code completion
• ✅ Advanced Debugging: Enhanced debugging for MCP tools
• ✅ Performance: Faster than traditional IDEs for AI projects

🚀 Step 7: Launch and Test

!!! -----> In your terminal: python E:\MCP-servers-github\AI-interaction\main.py --ui

⚠️ Important: Replace E:/MCP-servers-github/AI-interaction/mcp_server.py with the absolute path to mcp_server.py on your system. ---> AUTO SHOW UI:

1. Restart Claude Desktop/Cursor after configuring MCP server
2. Test connection by calling ai_interaction tool
3. Test UI popup to verify functionality
4. Validate rule integration through AI agent responses

📦 Package Structure

AI-interaction/
├── ai_interaction_tool/       # Main interaction tool package
│   ├── core/                 # Core dialog and configuration
│   │   ├── dialog.py         # InputDialog with PyQt5 UI
│   │   └── config.py         # Configuration management
│   ├── ui/                   # Interface and styling
│   │   ├── file_dialog.py    # File attachment dialogs
│   │   ├── file_tree.py      # File system tree view
│   │   ├── image_attachment.py # 🖼️ Image attachment with drag & drop
│   │   └── styles.py         # Modern UI styling
│   ├── utils/                # Utilities and multi-language
│   │   ├── translations.py   # Multi-language support
│   │   └── file_utils.py     # File operation utilities
│   ├── engine.py             # Main entry point
│   ├── description.py        # Detailed tool description
│   └── __init__.py           # Package exports
├── user_images/              # 🛡️ Secure image storage directory
├── main.py                   # Legacy entry point
├── mcp_server.py             # MCP server implementation
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Project configuration
└── README.md                # This file

🎮 Usage Guide

Available Tools in MCP Server

1. ai_interaction: Main Interactive Tool

• Function: Creates UI popup for user input with file/image attachment
• Output: Structured tag-based format with image support
• Integration: Perfect integration with system prompt rules
• Use cases:
  • Input complex content with formatting
  • Attach files/folders from workspace
  • 🖼️ Attach images with drag & drop functionality
  • 📷 Multi-image support with preview and management
  • Control AI thinking modes and reasoning levels

Basic Usage Examples

# Programmatic usage
from ai_interaction_tool import ai_interaction

# Launch interactive interface
result = ai_interaction()
print(result)  # Structured output with tags

🖼️ Image Attachment Features

📷 Core Image Capabilities

• Drag & Drop Support: Drag images directly into the UI
• Multi-image Management: Attach, preview, and remove multiple images
• Format Support: PNG, JPG, JPEG, GIF, BMP, WEBP
• Secure Storage: Images stored safely in user_images/ directory
• Base64 Encoding: Automatic conversion for AI processing
• Preview System: Click images to view larger versions
• Persistent State: Save images option with checkbox persistence

🎯 How to Use Image Attachment

1. Attach Button: Click "📷 Attach Images" to select files
2. Drag & Drop: Drag images from file explorer directly to UI
3. Paste Support: Paste images from clipboard (Ctrl+V)
4. Multiple Images: Attach as many images as needed
5. Remove Images: Click X button on individual image previews
6. Clear All: Use "🗑️ Clear Images" to remove all at once
7. Save Toggle: Check/uncheck "Save images" to control persistence

🛡️ Security & Privacy

• Local Only: All images stored locally in user_images/
• No External Access: No uploads or external connections
• Relative Paths: Only relative paths stored in config for security
• User Control: Users control what images to attach and save
• Auto-cleanup: Images automatically cleaned when save disabled

Output Format

AI Interaction Tool uses clean tag-based format:

User message content with natural line breaks

<AI_INTERACTION_ATTACHED_FILES>
FOLDERS:
- workspace_name/relative/path/to/folder

FILES:
- workspace_name/relative/path/to/file.js
</AI_INTERACTION_ATTACHED_FILES>

<AI_INTERACTION_WORKSPACE>workspace_name</AI_INTERACTION_WORKSPACE>
<AI_INTERACTION_CONTINUE_CHAT>true/false</AI_INTERACTION_CONTINUE_CHAT>

Note: When images are attached, they are automatically converted to base64 format and included in the response for AI processing.

🔧 Troubleshooting

Common Issues

1. "Command not found" error

   • Check Python is installed and in PATH
   • Verify absolute path in MCP config

2. "Module not found" error

   • Run pip install -r requirements.txt
   • Check virtual environment if using one

3. UI not displaying

   • Ensure PyQt5 is installed correctly
   • Check display settings and desktop environment

4. File attachment not working

   • Verify file permissions and access rights
   • Check workspace path configuration

5. 🖼️ Image attachment issues

   • Ensure PyQt5 is properly installed for image processing
   • Check user_images/ directory permissions
   • Verify image formats: PNG, JPG, JPEG, GIF, BMP, WEBP supported
   • Clear config if images not loading: Remove last_attached_images from config.json

6. MCP Connection Issues in Cursor

   • Verify MCP server configuration in Cursor settings
   • Check process running with ps aux | grep mcp_server
   • Restart Cursor after config changes

Debug Mode

To debug issues, run server directly:

python mcp_server.py

For Cursor debugging:

# Check MCP server logs in Cursor
# Open Developer Tools → Console
# Look for MCP connection messages

🔄 Version History

• v2.2.0 (Latest): 🖼️ Image Attachment System - Complete image support with drag & drop, multi-image management, security enhancements, and persistent state
• v2.1.0: Enhanced UI/UX, Cursor IDE integration, Debounce config system
• v2.0.0: Refactored architecture with modern PyQt5 UI
• v1.x: Core functionality and basic features

🎯 v2.2.0 Detailed Changes:

• ✅ Image Attachment UI: Full drag & drop interface with preview system
• ✅ Multi-format Support: PNG, JPG, JPEG, GIF, BMP, WEBP compatibility
• ✅ Security Hardening: Secure path storage, local-only processing
• ✅ Database Management: Auto-cleanup, persistent storage, state management
• ✅ UX Improvements: Click-to-enlarge, remove buttons, checkbox persistence
• ✅ Performance: Optimized image loading with base64 conversion
• ✅ Bug Fixes: Checkbox state persistence, config loading issues resolved

🎯 Integration Workflow & System Architecture

🔄 Complete Integration Flow:

[User Input] → [ai_interaction Tool] → [Tag-based Output] → [AI Agent Rules] → [Enhanced Response]
     ↑                                                                              ↓
     └─────────────── [Auto-recall if continue_chat=true] ←─────────────────────────┘

🧠 Cognitive Enhancement System:

• Standard Mode: High-level thinking with 1+ thinking blocks
• Ultra-Enhancement Mode: 10 breakthrough cognitive modes simultaneously
  • Quantum Cognitive Mode
  • Meta-Cognitive Orchestration
  • Expert Persona Simulation
  • Time-Dilated Processing
  • Systems-Level Integration
  • Psychological Priming Mode
  • Maximum Cognitive Resource Allocation
  • Adversarial Self-Testing Mode
  • Obsessive Quality Standards
  • Breakthrough Innovation Mode

📊 Output Tag System:

<AI_INTERACTION_CONTINUE_CHAT>true/false</AI_INTERACTION_CONTINUE_CHAT>
<AI_INTERACTION_ATTACHED_FILES>
FOLDERS:
- workspace_name/relative/path/folder
FILES:  
- workspace_name/relative/path/file.ext
</AI_INTERACTION_ATTACHED_FILES>
<AI_INTERACTION_WORKSPACE>workspace_name</AI_INTERACTION_WORKSPACE>

💡 Advanced Features & Best Practices

🎨 UI/UX Enhancements:

• Responsive Design: Adaptive sizing with minimum 800x700 resolution
• Multi-language Support: Seamless EN/VI switching with persistent config
• Modern PyQt5 Styling: Semantic color system with button properties
• File Drag-Drop: Intuitive file attachment with validation
• Context Menu: Right-click operations for file management
• Debounce Saving: Smart config persistence with QTimer optimization

🔧 Technical Specifications:

• Python: 3.8+ required with PyQt5 dependencies
• Memory: Minimum 512MB RAM for UI components
• Storage: ~50MB for tool installation and config
• Platform: Cross-platform (Windows/macOS/Linux) with native styling
• Performance: Event-driven architecture with minimal CPU usage

📈 Performance Optimization:

• Lazy Loading: Components load only when needed
• Efficient Config: JSON-based with automatic compression
• Resource Management: Proper cleanup and memory management
• Caching Strategy: Workspace state persistence for faster startup

🛡️ Security & Privacy

🔒 Security Features:

• Local Processing: All file operations are local only, no uploads
• Path Validation: Robust security checks for file access
• Sandboxed Execution: Tool runs in controlled environment
• No Data Collection: Zero telemetry or external data transmission

🔐 Privacy Protection:

• Config Encryption: Local config with secure storage options
• File Access Control: User-controlled file attachment permissions
• Workspace Isolation: Project boundaries are enforced
• Audit Trail: Optional logging for security monitoring

🌟 System Requirements & Compatibility

💻 Minimum System Requirements:

OS: Windows 10+ / macOS 10.14+ / Ubuntu 18.04+
Python: 3.8 or higher
RAM: 512MB available
Storage: 100MB free space
Display: 1024x768 minimum resolution

🎯 Recommended Setup:

OS: Windows 11 / macOS 12+ / Ubuntu 20.04+
Python: 3.10+ with virtual environment
RAM: 2GB available  
Storage: 500MB free space
Display: 1920x1080 or higher
GPU: Optional for enhanced UI rendering

🔧 Compatibility Matrix:

Component	Version	Status	Notes
Python	3.8-3.11	✅ Tested	Recommended 3.10+
PyQt5	5.15+	✅ Required	Core UI framework
Claude Desktop	Latest	✅ Optimized	MCP integration
Cursor IDE	Latest	🚀 Recommended	AI-first development
VS Code	Any	✅ Compatible	Alternative IDE option

🤝 Contributing

Note: This is a private repository. Only the owner has push access.

For suggestions or issues:

1. Create detailed issue reports
2. Provide reproduction steps
3. Include system information
4. Attach relevant logs or screenshots

📚 Documentation & Resources

📖 Documentation Files:

• rule_for_ai_VI.txt - Vietnamese agent behavior rules
• rule_for_ai_EN.txt - English agent behavior rules
• SYSTEM_PROMPT_Claude-4-sonnet-max.txt - Full system prompt example
• pyproject.toml - Project configuration and dependencies

🔗 Useful Links:

• Model Context Protocol (MCP) Documentation
• Claude Desktop Official Guide
• Cursor IDE Official Site
• PyQt5 Documentation
• Python Virtual Environments

💡 Related Projects:

- https://github.com/KhaiHuynhVN/mcp-server-agent-comm

📄 License & Legal

📜 License:

MIT License

Copyright (c) 2025 DemonVN - AI Interaction Tool

⚖️ Legal Notes:

• Tool complies with local processing requirements
• No personal data collection
• Respects user privacy and data sovereignty
• Compatible with enterprise security policies

🎯 Special Thanks:

• Model Context Protocol team for standardized interface
• Claude Desktop integration ecosystem
• Cursor IDE team for AI-first development tools
• Open source Python community
• Beta testers and early adopters

🔥 Inspiration:

Project inspired by the need for seamless AI interaction tools with modern UX principles and professional-grade architecture.

---

🚀 Happy Coding with AI Interaction Tool!

For support, issues, or feature requests, please open an issue on the GitHub repository.