MCP 交互服务

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

核心目的

该插件的核心目的是实现 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 界面

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

使用指南

1. 入门（两种选项）

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

1. 从 GitHub Releases 页面下载最新的预编译可执行文件。
2. 无需安装 - 直接下载并运行可执行文件即可。
3. 您可以使用以下命令测试功能：

bash

使用 PyQt 界面测试选项选择

.distmcp-interactive.exe test select_option --ui pyqt

使用 PyQt 界面测试信息补充

.distmcp-interactive.exe test request_additional_info --ui pyqt

您还可以指定文件路径来测试 request_additional_info 工具

.distmcp-interactive.exe test request_additional_info --ui pyqt D:PathToYourFile.md4. 跳至下面的步骤3进行配置。

选项B：从源代码安装

该项目根据不同UI类型分离依赖项：

• requirements-base.txt：基础依赖项，所有UI类型共享
• requirements-pyqt.txt：PyQt5 UI依赖项
• requirements-web.txt：Web UI (Flask) 依赖项

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

使用pip（传统方法）

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

bash 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，可以使用以下命令创建虚拟环境并安装依赖项：

bash

创建虚拟环境

uv venv

激活虚拟环境

Windows

.venvScriptsactivate

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 文件直接安装所有依赖项：

bash

安装基础依赖项

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响应方式：

bash

命令行界面（默认）

python main.py run --ui=cli

Web界面

python main.py run --ui=web

PyQt界面

python main.py run --ui=pyqt

其他服务启动选项：

bash

使用默认设置启动服务（地址：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（源代码）

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

使用可执行文件

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

使用SSE协议（备选方案）

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

本地启动： bash python main.py run --transport sse

Cursor配置： json { "ai-interaction": { "type": "sse", "url": "http://127.0.0.1:8000/sse", "env": {} } }

Windsurf配置： json { "ai-interaction": { "serverUrl": "http://127.0.0.1:7888/sse", "disabled": false } }

4. 配置AI交互规则

为了最大化Cursor和Windsurf中AI交互的效果，请为MCP使用时配置以下规则：1. 当AI对任务不清楚或需要额外信息时，应调用MCP ai-interaction来请求用户澄清。

1. 当AI有多种可能的解决方案时，应调用MCP ai-interaction让用户选择首选方案。

2. 完成任务后，AI应调用MCP ai-interaction确认是否有其他需要执行的任务。

3. AI应将任务分解为多个阶段，并在开始新阶段之前调用MCP ai-interaction询问用户是否需要加入任何额外的想法或考虑因素。

4. AI应主动使用MCP确认关键决策，而不是做出假设。

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

其他功能

查看可用工具

bash python main.py list-tools

测试工具

bash

测试选项选择工具

python main.py test select_option --ui=cli

测试信息补充工具

python main.py test request_additional_info --ui=cli

交互式测试客户端

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

bash

运行交互式测试客户端

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传输协议，我们提供了一个命令行工具：

bash

使用默认设置测试stdio连接

python mcp_client_stdio.py

指定UI类型

python mcp_client_stdio.py --ui=pyqt

测试特定工具

python mcp_client_stdio.py --test=select_option

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

UI测试

bash

测试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: 显示给用户的提示消息

返回： 包含选择结果的字典，格式如下： json { "selected_index": 0, // 用户选择的索引，如果为自定义答案则为-1 "selected_option": {}, // 用户所选选项的内容 "custom_input": "", // 用户的自定义输入（如果有） "is_custom": false // 是否为自定义答案 }

信息补充 (request_additional_info)

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

参数：

• prompt: 请求信息的提示
• current_info: 当前信息，作为参考显示给用户

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

与AI工具集成

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

1. 使用可执行文件…