README - mcp-server-reasoner-thinking by khaihuynhvn

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:

Open Claude Desktop or access Claude web interface
Find "Custom Instructions" or "Add custom instructions" in settings
Copy entire content from one of the rule files:
- 🇻🇳 Vietnamese: rule_for_ai_VI.txt
- 🇺🇸 English: rule_for_ai_EN.txt
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:

Download Cursor: https://cursor.sh/
Install and open workspace: Open AI-interaction folder
Configure MCP in Cursor:
- Open Command Palette (Cmd/Ctrl + Shift + P)
- Search "Configure MCP Servers"
- Add AI_interaction server config
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

Restart Claude Desktop/Cursor after configuring MCP server
Test connection by calling ai_interaction tool
Test UI popup to verify functionality
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

Attach Button: Click "📷 Attach Images" to select files
Drag & Drop: Drag images from file explorer directly to UI
Paste Support: Paste images from clipboard (Ctrl+V)
Multiple Images: Attach as many images as needed
Remove Images: Click X button on individual image previews
Clear All: Use "🗑️ Clear Images" to remove all at once
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

"Command not found" error
- Check Python is installed and in PATH
- Verify absolute path in MCP config
"Module not found" error
- Run pip install -r requirements.txt
- Check virtual environment if using one
UI not displaying
- Ensure PyQt5 is installed correctly
- Check display settings and desktop environment
File attachment not working
- Verify file permissions and access rights
- Check workspace path configuration
🖼️ 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
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:

Create detailed issue reports
Provide reproduction steps
Include system information
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:

💡 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.