AI导哈

模型上下文协议服务器

一个最小化的模型上下文协议（MCP）服务器，使AI代理能够通过简单的人机交互界面提出澄清问题并接收结构化用户输入。

  • by ifmelate
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ifmelate/clarify-mcp

使用说明

澄清MCP服务器

一个最小的模型上下文协议（MCP）服务器，使AI代理能够通过简单的人机交互界面提出澄清问题并接收结构化的用户输入。

概述

此MCP服务器公开了一个工具 ask_clarification 这允许AI代理提出结构化问题，并通过MCP启发接收用户输入。它与MCP客户端兼容，如Cursor、VS Code、Claude Desktop和其他启用MCP的工具。

演示视频：

特性

  • 简单问答界面：提出澄清问题并获得简洁的答案
  • 多项选择支持：可选地提供预定义选项供用户选择
  • 跨客户端兼容性：通过适应性启发策略与各种MCP客户合作
  • Pydantic集成：使用Pydantic模型进行结构化数据验证

安装

先决条件

  • Python 3.8或更高版本
  • uv 包管理器（推荐）或 pip

使用紫外线（推荐）

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # On Linux/macOS
# or
.venv\Scripts\activate  # On Windows

# Install dependencies
uv pip install fastmcp pydantic

使用pip

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # On Linux/macOS
# or
.venv\Scripts\activate  # On Windows

# Install dependencies
pip install fastmcp pydantic

用法

运行服务器

服务器使用stdio传输运行，用于本地MCP客户端集成：

python hitl_server.py

客户端配置

在启用MCP的客户端配置中注册此服务器。具体配置因客户而异：

光标

添加到光标MCP配置中（通常在设置中）：

{
  "mcpServers": {
    "mcp-clarify": {
      "command": "python",
      "args": ["/absolute/path/to/hitl_server.py"],
      "transport": "stdio"
    }
  }
}

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或其他平台上的同等产品：

{
  "mcpServers": {
    "mcp-clarify": {
      "command": "python",
      "args": ["/absolute/path/to/hitl_server.py"]
    }
  }
}

带有MCP扩展的VS代码

通过MCP扩展设置进行配置，指向服务器可执行文件。

工具参考

ask_clarification

提出一个澄清问题，并获得简洁的答案。

参数：

  • prompt （string，必填）：要问的人类可见问题
  • choices （字符串列表，可选）：建议选择的答案

退货：

带字段的JSON对象：

{
  "question": "The original question text",
  "answer": "User's answer"
}

AI Agent中的示例用法：

# Simple question
result = await ask_clarification(
    prompt="What is the target latency SLA for this API?"
)

# Multiple choice question
result = await ask_clarification(
    prompt="Which environment should we deploy to?",
    choices=["development", "staging", "production"]
)

运作原理

  1. 问题启发：服务器使用FastMCP的启发功能向用户提出问题
  2. 模式生成：提供选项后，生成带有枚举的JSON模式以供客户端呈现
  3. 解析答案：处理各种响应格式，包括数字选择（“1”、“2”）和文本匹配
  4. 跨SDK兼容性：尝试在不同的FastMCP版本中使用多个启发签名

发展

项目结构

mcp-clarify/
├── hitl_server.py       # Main server implementation
├── README.md            # This file
├── requirements.txt     # Python dependencies
├── pyproject.toml       # Python project metadata
├── LICENSE              # MIT License
├── CONTRIBUTING.md      # Contribution guidelines
├── CODE_OF_CONDUCT.md   # Code of conduct
├── SECURITY.md          # Security policy
└── .github/             # GitHub-specific files
    ├── workflows/       # CI/CD workflows
    ├── ISSUE_TEMPLATE/  # Issue templates
    └── PULL_REQUEST_TEMPLATE.md

运行测试

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests (if implemented)
pytest

贡献

欢迎投稿！请确保您的代码：

  • 遵循PEP 8风格指南
  • 包括适当的错误处理
  • 适用于不同的MCP客户端实现
  • 保持与现有集成的向后兼容性

兼容性

  • python: 3.8+
  • MCP-SDK：通过自适应签名与各种FastMCP版本兼容
  • 派丹蒂克：通过兼容垫片支持v1和v2
  • 客户：使用Cursor、Claude Desktop和VS Code MCP扩展进行了测试

故障排除

服务器未启动

  • 确保安装了所有依赖项： pip install fastmcp pydantic
  • 检查Python版本： python --version （应为3.8+）
  • 验证虚拟环境是否已激活

客户端无法连接

  • 确保客户端配置中的路径指向正确的 hitl_server.py 位置
  • 在配置文件中使用绝对路径
  • 检查客户端启动服务器时PATH中是否有Python

激励不起作用

  • 验证您的MCP客户端支持启发（查看客户端文档）
  • 先尝试一个更简单的问题（无选择参数）
  • 检查客户端日志中的错误消息

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

贡献

欢迎投稿！请阅读我们的 贡献指南 和 行为准则 在提交pull请求之前。

相关 MCP