STARWARCLOUD STARWAR.AI
返回市场
交互-mcp

交互-mcp

作者：DanielZhao199028 星标更新：2025-06-27
安装使用来源：spider==github.com

项目介绍

技术文档摘要

MCP交互服务

这是一个使用FastMCP库实现的MCP服务，旨在与AI工具（如Cursor、Windsurf等）进行交互。当AI工具在调用大型语言模型时需要用户输入或选项选择时，它们可以调用此MCP服务。

alt text alt text alt text

核心目的

该插件的核心目的是使AI工具（如Cursor和Windsurf）与用户之间能够进行高频次的通信和确认。通过以下方式显著提高了AI交互的效率和效果：

  1. 减少资源浪费：允许用户在AI投入可能错误的解决方案路径之前确认或重定向AI的方法，从而最小化浪费的API调用和计算资源。
  2. 最大化资源利用：每次调用Cursor或Windsurf的API都变得更加高效，因为AI可以在继续执行前先验证其理解和方法是否正确。
  3. 防止注意力分散：通过早期确认方法，插件有助于保持对正确解决方案路径的关注，而不是让注意力分散到错误的方法上。
  4. 支持互动决策：用户可以积极参与决策过程，提供即时反馈和指导给AI。
  5. 简化复杂任务：对于多步骤任务，插件确保在每个关键决策点上用户期望与AI执行之间的对齐。

功能

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

用户界面类型

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

CLI（命令行界面）

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

PyQt界面

  • 描述：使用PyQt提供现代图形用户界面
  • 优点：
    • 清晰、专业外观的对话框
    • 类似桌面应用程序的体验
    • 所有类型的用户易于使用
  • 缺点：
    • 每次只能显示一个对话框
    • 需要PyQt依赖项（安装较大）
  • 适合：桌面使用场景，视觉吸引力重要且每次只需要一个对话框

Web界面

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

使用指南

1. 开始使用（两种选项）

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

  1. 从GitHub Releases页面下载最新的预编译可执行文件。
  2. 不需要安装，只需下载并运行可执行文件。
  3. 您可以使用以下命令测试功能：
# 使用PyQt界面测试选项选择
.\dist\mcp-interactive.exe test select_option --ui pyqt

# 使用PyQt界面测试信息补充
.\dist\mcp-interactive.exe test request_additional_info --ui pyqt

# 您还可以指定文件路径来测试request_additional_info工具
.\dist\mcp-interactive.exe test request_additional_info --ui pyqt D:\Path\To\Your\File.md
  1. 跳至下面的第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（最小依赖项）
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），因此您只需安装一个文件。

使用uv（推荐，更快）

如果您已经安装了uv，可以使用以下命令创建虚拟环境并安装依赖项：

# 创建虚拟环境
uv venv

# 激活虚拟环境
# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# 根据UI类型安装依赖项
cd requirements

# CLI UI（最小依赖项）
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文件直接安装所有依赖项：

# 安装基础依赖项
uv pip install -e .

# 安装特定UI类型的依赖项
uv pip install -e ".[pyqt]"     # PyQt5 UI
uv pip install -e ".[web]"      # Web UI
uv pip install -e ".[all]"      # 所有UI类型

2. 启动程序

启动不同UI响应方法：

# 命令行界面（默认）
python main.py run --ui=cli

# Web界面
python main.py run --ui=web

# PyQt界面
python main.py run --ui=pyqt

其他服务启动选项：

# 使用默认设置启动服务（地址：127.0.0.1，端口：7888）
python main.py run

# 指定主机和端口
python main.py run --host 0.0.0.0 --port 8888

# 指定日志级别
python main.py run --log-level warning

3. 配置Cursor、Windsurf或Claude

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

Cursor配置：

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

Windsurf配置：

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

4. 配置AI交互规则

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

  1. 当AI不清楚任务或需要更多信息时，应调用MCP ai-interaction向用户请求澄清。
  2. 当AI有多条可能的解决方案路径时，应调用MCP ai-interaction让用户选择首选路径。
  3. 完成任务后，AI应调用MCP ai-interaction确认是否有其他任务需要执行。
  4. AI应将任务分解为多个阶段，并在开始新阶段前调用MCP ai-interaction询问用户是否需要加入额外的想法或考虑因素。
  5. AI应主动使用MCP确认关键决策，而不是做出假设。

这些规则确保高质量的互动式AI辅助，同时最大化每次API调用的价值。

其他功能

查看可用工具

python main.py list-tools

测试工具

# 测试选项选择工具
python main.py test select_option --ui=cli

# 测试信息补充工具
python main.py test request_additional_info --ui=cli

交互测试客户端

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

# 运行交互测试客户端
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传输协议，我们提供了一个命令行工具：

# 使用默认设置测试stdio连接
python mcp_client_stdio.py

# 指定UI类型
python mcp_client_stdio.py --ui=pyqt

# 测试特定工具
python mcp_client_stdio.py --test=select_option

更多详情，请参阅STDIO测试指南。

UI测试

# 测试PyQt界面
python test_ui.py --ui=pyqt

# 测试Web界面
python test_ui.py --ui=web

# 测试CLI界面
python test_ui.py --ui=cli

工具说明

选项选择（select_option）

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

参数：

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

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

{
    "selected_index": 0,     // 用户选择的索引，如果为自定义答案则为-1
    "selected_option": {},   // 用户选择的选项内容
    "custom_input": "",      // 用户的自定义输入，如果有
    "is_custom": false       // 是否为自定义答案
}

信息补充（request_additional_info）

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

参数：

  • prompt：请求信息的提示

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

配置文件

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

{
  "reminder": {
    "enable_reminder": true,
    "reminder_text": "**注意**：\n除非我明确说明没有新的任务，否则您绝不能终止对话。完成每个任务后，请调用mcp ai-interaction来请求或确认任务！"
  },
  "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工具集成，请按照以下步骤操作：

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

Claude集成

要将Claude集成到Anthropic的官方产品或第三方应用中：

  1. 在您的AI工具设置中配置stdio连接：

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

  2. 配置Claude在需要时使用交互服务，例如：

    • “当您需要用户输入或确认时，请使用MCP交互服务”
    • “对于多项选择选项，请调用select_option工具”
    • “为了收集额外的用户信息，请调用request_additional_info工具”

  3. Claude现在可以通过MCP服务直接呈现选项并请求额外信息。

示例

选项选择示例

from fastmcp import Client

async with Client("http://127.0.0.1:8000/sse") as client:
    options = [
        "选项1：使用TensorFlow实现",
        "选项2：使用PyTorch实现",
        {"title": "选项3：使用JAX实现", "description": "更适合研究目的"}
    ]
    result = await client.call_tool(
        "select_option", 
        {"options": options, "prompt": "请选择框架实现"}
    )
    selected_option = result.json
    print(f"用户选择了：{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": "请提供具体的项目需求"
        }
    )
    print(f"用户提供的信息：{additional_info.text}")

开发笔记

  • 如果您不需要开发或测试多种UI类型，建议仅安装一种UI依赖项
  • 如果需要添加新的依赖项，请将其添加到适当的依赖项文件中

当前开发状态

请注意以下实现状态：

  • Windows：CLI和PyQt UI版本完全可用。Web UI仍有一些需要解决的问题。
  • Linux/Mac：这些平台尚未经过彻底测试。您的体验可能会有所不同。

我们正在积极改进所有平台和UI类型之间的兼容性。

构建和分发

构建可执行文件

该项目包含一个脚本，用于构建Windows独立可执行文件：

# 构建Windows可执行文件
build_executable.bat

这将在dist目录下生成mcp-interactive.exe，您可以在没有Python安装的情况下运行它。

跨平台构建

要为不同的平台构建可执行文件：

Windows

# 使用批处理脚本
build_executable.bat

# 或手动PyInstaller命令
pyinstaller mcp-interactive.spec

macOS

# 确保已安装PyInstaller
pip install pyinstaller

# 使用spec文件构建
pyinstaller mcp-interactive.spec

Linux

# 确保已安装PyInstaller
pip install pyinstaller

# 使用spec文件构建
pyinstaller mcp-interactive.spec

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

通过GitHub分发

要使您构建的可执行文件可供下载：

  1. 为您的项目创建一个GitHub发布
  2. 将构建的可执行文件作为发布资产上传
  3. 提供清晰的文档，说明每个平台应使用哪个可执行文件

示例步骤：

  1. 导航到您的GitHub存储库
  2. 单击右侧边栏中的“Releases”
  3. 单击“创建新发布”
  4. 设置版本标签（例如，v1.0.0）
  5. 为您的发布添加标题和描述
  6. 拖放或上传不同平台的可执行文件
  7. 单击“发布发布”

用户可以从GitHub发布页面下载适合他们操作系统的适当版本。

许可证

本项目采用MIT许可证发布。