使用说明

MCP互动服务

这是一个使用FastMCP库实现的MCP服务，专为与Cursor、Windsurf等AI工具交互而设计。当人工智能工具在调用大型语言模型时需要用户输入或选项选择时，它们可以调用此MCP服务。

核心目的

该插件的核心目的是实现AI工具（如Cursor和Windsurf）与用户之间的高频通信和确认。它通过以下方式显著提高了人工智能交互的效率和有效性：

减少资源浪费：通过允许用户在人工智能提交到潜在的错误解决方案路径之前确认或重定向人工智能的方法，该插件最大限度地减少了浪费的API调用和计算资源。
最大限度地利用资源：每一个对Cursor或Windsurf的API调用都会变得更有效率，因为人工智能可以在继续之前与用户验证其理解和方法。
防止注意力分散：通过尽早确认方法，该插件有助于保持对正确解决方案路径的关注，而不是将注意力转移到不正确的方法上。
实现交互式决策用户可以积极参与决策过程，为人工智能提供即时反馈和指导。
简化复杂任务：对于多步骤任务，该插件可确保用户期望与每个关键决策点的AI执行保持一致。

特性

选项选择：显示选项列表，供用户通过输入数字或提供自定义答案进行选择
信息补充：当AI模型需要更完整的信息时，它们可以要求用户直接输入补充信息
多个用户界面：支持CLI、Web和PyQt接口

UI类型

该项目支持三种不同的用户界面类型，每种类型都有自己的特点：

CLI（命令行界面）

描述：打开一个新的命令提示符窗口供用户交互
优势:
- 最小依赖性（不需要额外的包）
- 可以同时处理多个对话框窗口
- 在没有图形界面的环境中工作良好
- 重量轻，启动快
缺点:
- 基本视觉呈现
- 对于非技术用户来说可能不那么直观
最适合：服务器环境、资源有限的系统，或需要多个同时对话时

PyQt接口

描述：使用PyQt提供现代图形用户界面
优势:
- 干净、专业的对话
- 熟悉桌面应用程序经验
- 易于所有用户类型使用
缺点:
- 一次只能显示一个对话框
- 需要PyQt依赖项（更大的安装）
最适合：桌面使用，视觉吸引力很重要，一次只需要一个对话框

web界面

描述：在web浏览器中打开对话框
优势:
- 可以同时处理多个对话框窗口
- 可通过web浏览器从任何地方访问
- 现代、可定制的界面
缺点:
- 需要安装web浏览器
- 设置稍微复杂一些
最适合：远程访问场景、首选web界面的环境或需要多个同时对话的环境

使用指南

1.入门（两种选择）

选项A：使用预编译的可执行文件（建议用于Windows）

从下载最新的预编译可执行文件 GitHub发布页面。
无需安装-只需下载并运行可执行文件。
您可以使用以下命令测试功能：

# Test option selection with PyQt interface
.\dist\mcp-interactive.exe test select_option --ui pyqt

# Test information supplement with PyQt interface
.\dist\mcp-interactive.exe test request_additional_info --ui pyqt

# You can also specify a file path for testing the request_additional_info tool
.\dist\mcp-interactive.exe test request_additional_info --ui pyqt D:\Path\To\Your\File.md

跳到下面的步骤3进行配置。

选项B：从源代码安装

此项目根据不同的UI类型分离依赖关系：

requirements-base.txt：所有UI类型共享的基础依赖关系
requirements-pyqt.txt：PyQt5 UI依赖项
requirements-web.txt：Web UI（Flask）依赖关系

您可以选择使用传统的pip或更快的uv包管理器来安装依赖项。

使用pip（传统方法）

根据要使用的UI类型选择适当的依赖关系文件：

cd requirements
# CLI UI (minimal dependencies)
pip install -r requirements-base.txt

# PyQt5 UI
pip install -r requirements-pyqt.txt

# Web UI
pip install -r requirements-web.txt

注意：每个特定的UI依赖文件都已经包含对基本依赖关系的引用（通过 -r requirements-base.txt)，因此您只需要安装一个文件。

使用紫外线（推荐，更快）

如果你已经有了紫外线安装后，您可以使用以下命令创建虚拟环境并安装依赖项：

# Create a virtual environment
uv venv

# Activate the virtual environment
# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# Install dependencies based on UI type
cd requirements

# CLI UI (minimal dependencies)
uv pip install -r requirements-base.txt

# PyQt5 UI
uv pip install -r requirements-pyqt.txt

# Web UI
uv pip install -r requirements-web.txt

您还可以使用项目的pyproject.toml文件直接安装所有依赖项：

# Install base dependencies
uv pip install -e .

# Install specific UI type dependencies
uv pip install -e ".[pyqt]"     # PyQt5 UI
uv pip install -e ".[web]"      # Web UI
uv pip install -e ".[all]"      # All UI types

2.启动程序

启动不同的UI响应方法：

# Command line interface (default)
python main.py run --ui=cli

# Web interface
python main.py run --ui=web

# PyQt interface
python main.py run --ui=pyqt

其他服务启动选项：

# Start the service with default settings (address: 127.0.0.1, port: 7888)
python main.py run

# Specify host and port
python main.py run --host 0.0.0.0 --port 8888

# Specify log level
python main.py run --log-level warning

3.配置光标、风帆或克劳德

使用stdio协议（推荐）

stdio协议是最稳定和推荐的连接方法，通过标准输入/输出直接与Python脚本通信，具有以下优点：

更高的稳定性和可靠性
可以同时打开多个对话框
简单直接，无需处理网络连接问题
与系统集成更紧密，响应更快

配置示例：

使用Python（源代码）

{
  "ai-interaction": {
    "command": "python",
    "args": ["path/to/main.py", "run", "--transport", "stdio", "--ui", "cli"],
    "env": {}
  }
}

与可执行文件一起使用

{
  "ai-interaction": {
    "command": "D:/Path/To/Your/mcp-interactive.exe",
    "args": ["run", "--transport", "stdio", "--ui", "pyqt"],
    "env": {}
  }
}

使用SSE协议（替代方案）

如果需要通过网络连接到远程服务器，可以使用SSE协议：

本地启动：

python main.py run --transport sse

光标配置：

{
  "ai-interaction": {
    "type": "sse",
    "url": "http://127.0.0.1:8000/sse",
    "env": {}
  }
}

风帆配置：

{
  "ai-interaction": {
    "serverUrl": "http://127.0.0.1:7888/sse",
    "disabled": false
  }
}

4.配置AI交互规则

为了最大限度地提高Cursor和Windsurf中AI交互的有效性，请配置以下规则，以便AI在使用MCP时遵循：

当人工智能对任务不清楚或需要额外信息时，它应该调用MCP-AI交互来请求用户澄清。
当人工智能有多种可能的解决方案时，它应该调用MCP-AI交互，让用户选择首选方法。
在完成一个任务后，AI应该调用MCP-AI交互来确认是否还有其他任务需要执行。
人工智能应将任务分解为多个阶段，在开始新阶段之前，调用MCP-AI交互，询问用户是否需要纳入任何其他想法或考虑因素。
人工智能应主动使用MCP来确认关键决策，而不是做出假设。

这些规则确保了高质量的交互式人工智能辅助，同时使每个API调用的价值最大化。

其他功能

查看可用工具

python main.py list-tools

测试工具

# Test option selection tool
python main.py test select_option --ui=cli

# Test information supplement tool
python main.py test request_additional_info --ui=cli

交互式测试客户端

该项目包括一个交互式测试客户端，允许您使用不同的UI类型和方法测试MCP服务：

# Run the interactive test client
python mcp_client_en.py --host localhost --port 7888 --ui cli

选项：

--host：服务器主机（默认：localhost）
--port：服务器端口（默认值：7888）
--ui：要使用的UI类型（cli、pyqt、web）

客户提供：

使用MCP服务进行连接测试
选择要测试的UI类型
测试select_option和request_additional_info方法
每种方法都有多个参数预设
请求和响应的完全可视化

这对于以下情况特别有用：

调试UI交互问题
测试不同UI类型的行为
向用户演示服务
验证服务器功能

STDIO测试客户端

为了专门测试stdio传输协议，我们提供了一个命令行工具：

# Test stdio connection with default settings
python mcp_client_stdio.py

# Specify UI type
python mcp_client_stdio.py --ui=pyqt

# Test specific tools
python mcp_client_stdio.py --test=select_option

有关更多详细信息，请参阅 STDIO测试指南.

用户界面测试

# Test PyQt interface
python test_ui.py --ui=pyqt

# Test Web interface
python test_ui.py --ui=web

# Test CLI interface
python test_ui.py --ui=cli

工具说明

选项选择（select_Option）

此工具用于向用户呈现一组选项，并让他们通过输入数字或提供自定义答案进行选择。

参数：

options：选项列表，可以是字符串列表或字典列表
prompt：向用户显示提示消息

返回：包含选择结果的词典，格式如下：

{
    "selected_index": 0,     // Index of the user's selection, -1 if custom answer
    "selected_option": {},   // Content of the user's selected option
    "custom_input": "",      // User's custom input, if any
    "is_custom": false       // Whether it's a custom answer
}

信息补充（request_additional_info）

此工具用于向用户请求补充信息。

参数：

prompt：请求信息提示

返回：用户输入的补充信息（字符串）

配置文件

这 config.json 项目根目录中的文件可以配置各种选项：

{
  "reminder": {
    "enable_reminder": true,
    "reminder_text": "**Note**:\nUnless I explicitly state there are no new tasks, you must never terminate the conversation. After completing each task, call mcp ai-interaction to request or confirm tasks with me!"
  },
  "ui": {
    "default_ui_type": "pyqt"
  },
  "logging": {
    "level": "warning"
  }
}

配置选项：

reminder.enable_reminder：是否自动将提醒内容添加到工具返回结果中（默认值：true）
reminder.reminder_text：要添加的提醒文本内容
ui.default_ui_type：默认UI类型
logging.level：日志记录级别

与AI工具集成

要将此MCP服务与AI工具集成，请执行以下步骤：

使用可执行文件或Python源代码启动MCP服务：
- 使用可执行文件： mcp-interactive.exe run
- 使用Python源代码： python main.py run
在AI工具中配置MCP端点，根据需要选择stdio或SSE协议
当AI模型需要用户输入或选项选择时，调用相应的MCP工具

克劳德集成

要在Anthropic的官方产品或第三方应用程序中与Claude集成：

在AI工具设置中配置stdio连接：

{
  "mcp-interaction": {
    "command": "D:/Path/To/Your/mcp-interactive.exe",
    "args": ["run", "--transport", "stdio", "--ui", "pyqt"],
    "env": {}
  }
}

配置Claude在需要时使用交互服务，说明如下：
- “当您需要用户输入或确认时，请使用MCP交互服务”
- 对于多项选择，请调用select_option工具
- 要收集其他用户信息，请调用request_additional_info工具
Claude现在可以直接通过MCP服务提供选项并请求其他信息。

例子

选项选择示例

from fastmcp import Client

async with Client("http://127.0.0.1:8000/sse") as client:
    options = [
        "Option 1: Implement with TensorFlow",
        "Option 2: Implement with PyTorch",
        {"title": "Option 3: Implement with JAX", "description": "Better for research purposes"}
    ]
    result = await client.call_tool(
        "select_option", 
        {"options": options, "prompt": "Please select a framework implementation"}
    )
    selected_option = result.json
    print(f"User selected: {selected_option}")

信息补充示例

from fastmcp import Client

async with Client("http://127.0.0.1:8000/sse") as client:
    additional_info = await client.call_tool(
        "request_additional_info",
        {
            "prompt": "Please provide specific project requirements"
        }
    )
    print(f"User provided information: {additional_info.text}")

开发说明

除非您需要开发或测试多种UI类型，否则建议只安装一个UI依赖项
如果需要添加新的依赖项，请将其添加到相应的依赖项文件中

发展现状

请注意以下实施情况：

视窗：CLI和PyQt UI版本功能齐全。Web UI仍然有一些问题需要解决。
Linux/Mac：这些平台尚未经过彻底测试。你的经历可能会有所不同。

我们正在积极努力提高所有平台和UI类型的兼容性。

建筑和配电

构建可执行文件

此项目包括一个为Windows构建独立可执行文件的脚本：

# Build the Windows executable
build_executable.bat

这将创建 mcp-interactive.exe 在 dist 无需安装Python即可运行的目录。

跨平台建筑

要为不同平台构建可执行文件，请执行以下操作：

视窗

# Using the batch script
build_executable.bat

# Or manual PyInstaller command
pyinstaller mcp-interactive.spec

macOS

# Ensure PyInstaller is installed
pip install pyinstaller

# Build using the spec file
pyinstaller mcp-interactive.spec

Linux

# Ensure PyInstaller is installed
pip install pyinstaller

# Build using the spec file
pyinstaller mcp-interactive.spec

注意：您必须在目标平台上构建（您不能从Windows等构建macOS可执行文件）

通过GitHub发布

要使构建的可执行文件可供下载，请执行以下操作：

为您的项目创建GitHub版本
将构建的可执行文件作为发布资产上传
为每个平台提供明确的可执行文件

示例步骤：

导航到您的GitHub存储库
点击右侧边栏中的“发布”
点击“创建新版本”
设置版本标记（例如v1.0.0）
为您的发布添加标题和描述
拖放或上传适用于不同平台的可执行文件
点击“发布发布”

然后，用户可以从GitHub发布页面下载适合其操作系统的版本。

许可证

该项目在MIT许可证下发布。