ifmelate/clarify-mcp

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

Register this server in your MCP-enabled client configuration. The exact configuration varies by client:

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

1. Question Elicitation: The server uses FastMCP's elicitation capabilities to present questions to the user
2. Schema Generation: When choices are provided, generates JSON schemas with enums for client-side rendering
3. Answer Parsing: Handles various response formats including numeric selection ("1", "2") and text matching
4. 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

Elicitation Not Working

• Verify your MCP client supports elicitation (check client documentation)
• Try with a simpler question first (no choices parameter)
• Check client logs for error messages

License

MIT License - See LICENSE file for details

Support

For issues and questions:

• Open an issue on GitHub
• Check existing issues for similar problems
• Review the MCP specification for protocol details

Contributing

Contributions are welcome! Please read our and before submitting pull requests.