mcp-server-ai_interaction

AI 交互工具 - MCP 服务

为 Model Context Protocol（MCP）打造的现代 AI 交互工具，拥有先进的 UI 和强大功能

🚀 核心功能

🎯 主要能力

• 交互式 UI 弹窗，用于输入内容和控制对话
• 文件/文件夹附件，支持从工作区添加，并提供验证和预览
• 🖼️ 图像附件系统，支持拖放和多图像
• 多语言支持（英语/越南语）
• 激活最大认知能力，实现 AI 性能巅峰
• 基于标签的输出格式，集成系统提示词规则
• 工作区感知路径处理，支持跨项目兼容

🔧 v2.2.0 新增功能（最新）

• 🖼️ 图像附件支持，提供拖放功能
• 🛡️ 增强安全性——在 user_images 目录中安全存储路径
• 💾 持久化图像状态——复选框状态可正确保存
• 🎯 多图像管理——可添加、预览和移除多张图像
• 🔄 数据库自动清理——禁用时自动清理图像

🔧 之前的 v2.1.0

• 增强 UI/UX，采用现代 PyQt5 界面
• 结构化的基于标签的输出，可完美集成 AI Agent
• 防抖配置，提供智能自动保存机制
• Cursor IDE 集成，附带全面的设置指南

📋 安装与设置指南

📥 步骤 1：克隆仓库

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

🐍 步骤 2：安装 Python

• 要求：Python 3.8+
• 从 python.org 下载
• 或使用包管理器：

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

📦 步骤 3：安装依赖项

# Using pip
pip install -r requirements.txt

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

⚙️ 步骤 4：在 Claude Desktop 中配置 MCP 服务

将以下配置添加到 Claude Desktop 配置文件中：

配置文件路径：

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

配置内容：

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

⚠️ 重要提示：将 E:/MCP-servers-github/AI-interaction/mcp_server.py 替换为你系统中 mcp_server.py 的绝对路径。

🧠 步骤 5：配置 AI Agent 规则（必需）

若要让 AI Agent 正常使用 ai_interaction 工具，必须设置自定义指令：

📋 如何添加自定义指令：

1. 打开 Claude Desktop，或访问 Claude 网页界面
2. 在设置中**找到“自定义指令”**或“添加自定义指令”
3. 复制其中一个规则文件的全部内容：
   • 🇻🇳 越南语：rule_for_ai_VI.txt
   • 🇺🇸 英语：rule_for_ai_EN.txt
4. 粘贴到自定义指令字段并保存

🎯 为何必须设置：

• ✅ 行为框架：规则定义了 AI Agent 如何处理 ai_interaction 输出
• ✅ 思考协议：激活高级思维模式，以提供高质量回复
• ✅ 超增强模式：提供 10 种认知模式，实现最佳性能
• ✅ 标签处理：读取并处理 <AI_INTERACTION_CONTINUE_CHAT> 等控制标签
• ✅ 继续逻辑：当 continue_chat=true 时自动再次调用 ai_interaction

📁 规则文件位置：

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

⚡ 快速设置命令：

# 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

🚀 步骤 6：配置 Cursor IDE（推荐）

推荐使用 Cursor 作为搭配此工具进行 AI 开发的 IDE：

📋 Cursor 设置步骤：

1. 下载 Cursor：https://cursor.sh/
2. 安装并打开工作区：打开 AI-interaction 文件夹
3. 在 Cursor 中配置 MCP：
   • 打开命令面板（Cmd/Ctrl + Shift + P）
   • 搜索 "Configure MCP Servers"
   • 添加 AI_interaction 服务配置
4. 设置自定义指令：
   • 复制 rule_for_ai_VI.txt 或 rule_for_ai_EN.txt 中的内容
   • 粘贴到自定义模式 Agent 中的 "Custom Instructions" 字段：

🎯 Cursor 的优势：

• ✅ 原生 MCP 支持：内置与 MCP 服务的集成
• ✅ AI 优先的 IDE：针对 AI 开发工作流进行优化
• ✅ 实时建议：具备上下文感知能力的代码补全
• ✅ 高级调试：增强对 MCP 工具的调试能力
• ✅ 性能：对于 AI 项目，速度比传统 IDE 更快

🚀 第 7 步：启动并测试

!!! -----> 在终端中：python E:\MCP-servers-github\AI-interaction\main.py --ui

⚠️ 重要：将 E:/MCP-servers-github/AI-interaction/mcp_server.py 替换为系统中 mcp_server.py 的绝对路径。 ---> 自动显示 UI：

1. 配置 MCP 服务后，重启 Claude Desktop/Cursor
2. 调用 ai_interaction 工具测试连接
3. 测试 UI 弹窗以验证功能
4. 通过 AI Agent 的响应验证规则集成

📦 软件包结构

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

🎮 使用指南

MCP 服务中的可用工具

1. ai_interaction：主要交互工具

• 功能：创建 UI 弹窗，供用户输入并附加文件/图片
• 输出：支持图片的结构化标签格式
• 集成：与系统提示词规则完美集成
• 使用场景：
  • 输入带格式的复杂内容
  • 从工作区附加文件/文件夹
  • 🖼️ 通过拖放功能附加图片
  • 📷 支持多张图片，并提供预览和管理功能
  • 控制 AI 思考模式和推理级别

基本使用示例

# Programmatic usage
from ai_interaction_tool import ai_interaction

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

🖼️ 图片附件功能

📷 核心图片功能

• 支持拖放：将图片直接拖入 UI
• 多图管理：附加、预览和移除多张图片
• 格式支持：PNG、JPG、JPEG、GIF、BMP、WEBP
• 安全存储：图片安全地存储在 user_images/ 目录中
• Base64 编码：自动转换，以便 AI 处理
• 预览系统：点击图片可查看更大版本
• 持久状态：提供保存图片选项，并通过复选框保留设置

🎯 如何使用图片附件

1. 附加按钮：点击 "📷 Attach Images" 选择文件
2. 拖放：将文件资源管理器中的图片直接拖到 UI 中
3. 粘贴支持：从剪贴板粘贴图片（Ctrl+V）
4. 多张图片：按需附加任意数量的图片
5. 移除图片：点击单张图片预览上的 X 按钮
6. 全部清除：使用 "🗑️ Clear Images" 一次性移除所有图片
7. 保存切换：勾选/取消勾选 "Save images" 以控制是否保留图片

🛡️ 安全与隐私

• 仅限本地：所有图片均存储在本地 user_images/ 目录中
• 无外部访问：不会上传图片或建立外部连接
• 相对路径：配置中仅存储相对路径，以确保安全
• 用户控制：由用户决定附加和保存哪些图片
• 自动清理：禁用保存后会自动清理图片

输出格式

AI Interaction 工具采用简洁的标签格式：

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>

注意：附加图片后，系统会自动将其转换为 Base64 格式，并包含在响应中以供 AI 处理。

🔧 故障排除

常见问题

1. “找不到命令”错误

   • 检查是否已安装 Python，且已添加到 PATH
   • 验证 MCP 配置中的绝对路径

2. “找不到模块”错误

   • 运行 pip install -r requirements.txt
   • 如果使用了虚拟环境，请检查虚拟环境

3. 界面未显示

   • 确保已正确安装 PyQt5
   • 检查显示设置和桌面环境

4. 文件附件无法使用

   • 验证文件权限和访问权限
   • 检查工作区路径配置

5. 🖼️ 图像附件问题

   • 确保已正确安装用于图像处理的 PyQt5
   • 检查 user_images/ 目录权限
   • 验证图像格式：支持 PNG、JPG、JPEG、GIF、BMP、WEBP
   • 如果图像无法加载，请清除配置：从 config.json 中移除 last_attached_images

6. Cursor 中的 MCP 连接问题

   • 验证 Cursor 设置中的 MCP 服务配置
   • 使用 ps aux | grep mcp_server 检查进程是否正在运行
   • 更改配置后重启 Cursor

调试模式

要调试问题，请直接运行服务：

python mcp_server.py

在 Cursor 中调试：

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

🔄 版本历史

• v2.2.0（最新）：🖼️ 图像附件系统 - 全面支持图像，包括拖放、多图像管理、安全增强和状态持久化
• v2.1.0：增强 UI/UX、集成 Cursor IDE、Debounce 配置系统
• v2.0.0：重构架构，采用现代 PyQt5 UI
• v1.x：核心功能和基础特性

🎯 v2.2.0 详细变更：

• ✅ 图像附件 UI：完整的拖放界面，带预览系统
• ✅ 多格式支持：兼容 PNG、JPG、JPEG、GIF、BMP、WEBP
• ✅ 安全强化：安全路径存储，仅在本地处理
• ✅ 数据库管理：自动清理、持久化存储、状态管理
• ✅ UX 改进：点击放大、移除按钮、复选框状态持久化
• ✅ 性能：通过 base64 转换优化图像加载
• ✅ Bug 修复：修复了复选框状态持久化和配置加载问题

🎯 集成工作流与系统架构

🔄 完整集成流程：

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

🧠 认知增强系统：

• 标准模式：使用 1+ 个思维块进行高阶思考
• 超级增强模式：同时启用 10 种突破性认知模式
  • 量子认知模式
  • 元认知编排
  • 专家角色模拟
  • 时间膨胀处理
  • 系统级集成
  • 心理预设模式
  • 最大认知资源分配
  • 对抗性自我测试模式
  • 严苛的质量标准
  • 突破性创新模式

📊 输出标签系统：

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

💡 高级功能与最佳实践

🎨 UI/UX 增强：

• 响应式设计：自适应尺寸，最低分辨率为 800x700
• 多语言支持：可无缝切换 EN/VI，并持久化配置
• 现代 PyQt5 样式：采用语义化配色系统和按钮属性
• 文件拖放：直观的文件附件功能，带验证
• 上下文菜单：用于文件管理的右键操作
• 防抖保存：通过 QTimer 优化，实现智能配置持久化

🔧 技术规格：

• Python：需要 3.8+ 版本及 PyQt5 依赖项
• 内存：UI 组件至少需要 512MB RAM
• 存储：工具安装和配置约需 50MB
• 平台：跨平台（Windows/macOS/Linux），支持原生样式
• 性能：事件驱动架构，CPU 使用率低

📈 性能优化：

• 延迟加载：仅在需要时加载组件
• 高效配置：基于 JSON，并自动压缩
• 资源管理：妥善清理并管理内存
• 缓存策略：持久化工作区状态，加快启动速度

🛡️ 安全与隐私

🔒 安全功能：

• 本地处理：所有文件操作仅在本地进行，不会上传
• 路径验证：对文件访问进行严格的安全检查
• 沙盒执行：工具在受控环境中运行
• 不收集数据：不进行任何遥测或外部数据传输

🔐 隐私保护：

• 配置加密：本地配置支持安全存储选项
• 文件访问控制：由用户控制文件附件权限
• 工作区隔离：强制执行项目边界
• 审计跟踪：可选择启用日志记录，以进行安全监控

🌟 系统要求与兼容性

💻 最低系统要求：

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

🎯 推荐配置：

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

🔧 兼容性矩阵：

组件	版本	状态	备注
Python	3.8-3.11	✅ 已测试	推荐使用 3.10+
PyQt5	5.15+	✅ 必需	核心 UI 框架
Claude Desktop	最新版	✅ 已优化	MCP 集成
Cursor IDE	最新版	🚀 推荐	AI 优先的开发
VS Code	任意版本	✅ 兼容	可选 IDE

🤝 参与贡献

注意：这是一个私有代码库。只有所有者拥有推送权限。

如有建议或问题：

1. 提交详细的问题报告
2. 提供复现步骤
3. 提供系统信息
4. 附上相关日志或屏幕截图

📚 文档与资源

📖 文档文件：

• rule_for_ai_VI.txt - 越南语 Agent 行为规则
• rule_for_ai_EN.txt - 英语 Agent 行为规则
• SYSTEM_PROMPT_Claude-4-sonnet-max.txt - 完整的系统提示词示例
• pyproject.toml - 项目配置和依赖项

🔗 实用链接：

• Model Context Protocol（MCP）文档
• Claude Desktop 官方指南
• Cursor IDE 官方网站
• PyQt5 文档
• Python 虚拟环境

💡 相关项目：

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

📄 许可证与法律信息

📜 许可证：

MIT License

Copyright (c) 2025 DemonVN - AI Interaction Tool

⚖️ 法律说明：

• 工具符合本地处理要求
• 不收集个人数据
• 尊重用户隐私和数据主权
• 兼容企业安全策略

🎯 特别感谢：

• Model Context Protocol 团队提供标准化接口
• Claude Desktop 集成生态系统
• Cursor IDE 团队提供 AI 优先的开发工具
• 开源 Python 社区
• Beta 测试人员和早期采用者

🔥 灵感来源：

本项目的灵感来自对流畅 AI 交互工具的需求，并遵循现代 UX 原则和专业级架构。

---

🚀 祝你使用 AI Interaction Tool 编码愉快！

如需支持、反馈问题或请求功能，请在 GitHub 代码库中提交 issue。