MCP 服务器

Clarify MCP Server

Enables AI agents to ask clarification questions and receive structured user input through a Human-in-the-Loop interface.

README

Clarify MCP Server

A minimal Model Context Protocol (MCP) server that enables AI agents to ask clarification questions and receive structured user input through a simple Human-in-the-Loop interface.

Overview

This MCP server exposes a single tool ask_clarification that allows AI agents to ask structured questions and receive user input via MCP elicitation. It's compatible with MCP clients like Cursor, VS Code, Claude Desktop, and other MCP-enabled tools.

DEMO VIDEO:

Features

Simple Question-Answer Interface: Ask clarification questions and get concise answers
Multiple Choice Support: Optionally provide predefined choices for users to select from
Cross-Client Compatibility: Works with various MCP clients through adaptive elicitation strategies
Pydantic Integration: Uses Pydantic models for structured data validation

Installation

Prerequisites

Python 3.8 or higher
uv package manager (recommended) or pip

Using uv (Recommended)

# 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

Using 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

Usage

Running the Server

The server runs using stdio transport for local MCP client integration:

python hitl_server.py

Client Configuration

Cursor

Add to your Cursor MCP configuration (typically in settings):

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent on other platforms:

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

VS Code with MCP Extension

Configure through the MCP extension settings, pointing to the server executable.

Tool Reference

`ask_clarification`

Ask a single clarification question and capture a concise answer.

Parameters:

prompt (string, required): The human-visible question to ask
choices (list of strings, optional): Suggested answers for selection

Returns:

JSON object with fields:

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

Example Usage in 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"]
)

How It Works

Question Elicitation: The server uses FastMCP's elicitation capabilities to present questions to the user
Schema Generation: When choices are provided, generates JSON schemas with enums for client-side rendering
Answer Parsing: Handles various response formats including numeric selection ("1", "2") and text matching
Cross-SDK Compatibility: Tries multiple elicitation signatures to work across different FastMCP versions

Development

Project Structure

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

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests (if implemented)
pytest

Contributing

Contributions are welcome! Please ensure your code:

Follows PEP 8 style guidelines
Includes appropriate error handling
Works across different MCP client implementations
Maintains backward compatibility with existing integrations

Compatibility

Python: 3.8+
MCP SDK: Compatible with various FastMCP versions through adaptive signatures
Pydantic: Supports both v1 and v2 with compatibility shims
Clients: Tested with Cursor, Claude Desktop, and VS Code MCP extension

Troubleshooting

Server Not Starting

Ensure all dependencies are installed: pip install fastmcp pydantic
Check Python version: python --version (should be 3.8+)
Verify the virtual environment is activated

Client Can't Connect

Ensure the path in client configuration points to the correct hitl_server.py location
Use absolute paths in configuration files
Check that Python is available in the PATH when the client launches the server