Skip to main content
Glama
Sighthesia

interactive-choice-mcp

by Sighthesia
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Interactive Choice MCP

An MCP Server that enables AI to provide options and launch an interactive interface for user selection when facing choice problems, then return the results. Inspired by mcp-feedback-enhanced, built with FastMCP.

  • Showcase: Showcase

Similar Projects

  • imhuso/cunzhi - A Rust + Tauri desktop application that intercepts AI from ending conversations prematurely. Features memory management for project-specific preferences and includes code search capabilities. More comprehensive but heavier than this project.

  • paulp-o/ask-user-questions-mcp - A lightweight TypeScript + Node.js MCP server focused on CLI-based interaction. Designed for multi-agent parallel coding workflows with question queuing and SSH support. More lightweight but only supports terminal interface.

  • fhyfhy17/panel-feedback - Panel Feedback brings AI interaction directly into your IDE's sidebar - seamlessly integrated, always accessible, never intrusive.

Differences: This project provides dual interface support (Web + Terminal) with balanced complexity, focusing on interactive selection scenarios.

(I discovered these projects after completing this one. I hope these excellent projects receive more visibility.)

📋 Table of Contents

Related MCP server: AskMeMCP

✨ Key Features

🎯 Core Capabilities

  • Interactive Choice Interface: AI presents options, users make selections through intuitive interfaces

  • Dual Interface Support: Web-based UI and Terminal UI (experimental)

  • Selection Modes: Single-select and multi-select modes

  • Option Annotations: Users can add annotations to options to provide correct feedback to AI

  • Automation Ready: AI can mark recommended options with timeout auto-submit

📦 Installation

Prerequisites

  • Python 3.12 or higher

  • uv package manager (recommended) or pip

🚀 Quick Start

Add the following configuration:

{
  "mcpServers": {
    "interactive-choice": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Sighthesia/interactive-choice-mcp",
        "interactive-choice-mcp"
      ]
    }
  }
}

  • This will automatically clone the project repository and install dependencies.

  • For best results, it is recommended to add the following content to your global prompt (still being adjusted, prompts are from cunzhi, currently focusing on optimization for pay-per-use AI assistants, suggestions are welcome):

    - When the requirements are not clear, use `provide_choice` to ask for clarification and provide predefined options.
- When there are multiple solutions, use `provide_choice` to ask instead of making assumptions on your own.
- When there is a need to update a solution or strategy, use `provide_choice` to ask instead of making assumptions on your own.
- Before completing a request, you must call `provide_choice` to request feedback.
- Without a clear confirmation through the use of `provide_choice` to ask and receive permission to complete the task or end the conversation, it is prohibited to end the dialogue or request on your own initiative.

Environment Variables (Optional)

You can override saved configurations by adding the following environment variables to the env section in your MCP configuration:

Environment Variable

Description

Possible Values

Default

CHOICE_WEB_HOST

Web server host

Any valid IP or hostname

127.0.0.1

CHOICE_WEB_PORT

Web server port

Any available port number

9999

CHOICE_LANG

Interface language

en, zh

Auto-detected by system language

CHOICE_LOG_LEVEL

Log level

DEBUG, INFO, WARNING, ERROR

INFO

CHOICE_LOG_FILE

Log file path

Any valid file path

Optional

CHOICE_MCP_DATA_DIR

Data storage dir

Any valid directory path

.mcp-data/

Configuration Example

Here is a complete MCP configuration example with environment variables:

{
  "mcpServers": {
    "interactive-choice": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Sighthesia/interactive-choice-mcp",
        "interactive-choice-mcp"
      ],
      "env": {
        "CHOICE_WEB_HOST": "127.0.0.1",
        "CHOICE_WEB_PORT": "8080",
        "CHOICE_LANG": "en",
        "CHOICE_LOG_LEVEL": "DEBUG",
        "CHOICE_LOG_FILE": "~/.mcp-data/interactive-choice.log",
        "CHOICE_MCP_DATA_DIR": "~/.mcp-data/interactive-choice"
      }
    }
  }
}

🤝 Contributing

Contributions are welcome! Whether it's reporting issues, requesting features, or submitting PRs, it's all greatly appreciated!

For AI-driven development, refer to AGENTS.md and openspec.

📍 Local Development Environment Setup

# Clone the repository
git clone https://github.com/Sighthesia/interactive-choice-mcp.git
cd interactive-choice-mcp

# Install dependencies
uv sync

# Verify installation
uv run pytest

  • You can configure to use a local development environment to run the MCP Server:

    {
  "mcpServers": {
    "interactive-choice": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/interactive-choice-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

    Tip: Replace /path/to/interactive-choice-mcp with the actual path, such as ~/interactive-choice-mcp.

🧪 Testing

For detailed testing information, please refer to tests/README.md.

The following are common test commands for development and debugging:

Running Interactive Tests

Temporarily run the Web server for interactive testing to verify user-side interaction effects:

  1. Open Web interaction interface and test the default single-select mode

uv run pytest tests/integration/test_interaction_web.py::TestWebInteractionManual::test_web_e2e_manual_interaction --interactive -v -s

  1. Open terminal interaction interface and test the default single-select mode

uv run pytest tests/integration/test_interaction_terminal.py::TestTerminalInteractionManual::test_terminal_e2e_manual_interaction --interactive -v -s

Running MCP Server Debugging

Run MCP Inspector to verify MCP Server tool input/output effects:

uv run mcp dev server.py

🏗️ Project Architecture

src/
├── core/                    # Core orchestration and business logic
│   ├── models.py           # Data models and schemas
│   ├── orchestrator.py     # Main orchestration logic
│   ├── validation.py       # Input validation
│   └── response.py         # Response generation
├── mcp/                    # MCP tool bindings
│   ├── tools.py           # MCP tool definitions
│   └── response_formatter.py
├── web/                    # Web interface
│   ├── server.py          # FastAPI web server
│   ├── bundler.py         # Asset bundling
│   └── templates.py       # HTML templates
├── terminal/               # Terminal interface
│   ├── ui.py              # Questionary-based UI
│   └── session.py         # Terminal session management
├── store/                  # Data persistence
│   └── interaction_store.py
└── infra/                  # Infrastructure
    ├── logging.py         # Logging configuration
    ├── i18n.py            # Internationalization
    └── storage.py         # File system operations

Future Considerations

  • Since various AI IDEs and CLIs tend to silently run AI commands, the terminal mode interaction experience may be limited and requires further consideration for feasibility

💖 Acknowledgments

📄 License

MIT License.

Available Tools

2 tools
poll_selectionC

Polls for the result of an ongoing interaction session that was switched from Terminal to Web.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full behavioral burden. It states 'polls' but does not clarify if it is blocking, how often to call, timeout behavior, or what happens if the session is invalid. No side effects or required permissions are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise, but it omits critical information. Efficiency is undercut by lack of substance, so a middle score is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter, presence of an output schema (content unknown), and a sibling tool, the description is incomplete. It does not explain the polling mechanism, expected output, or relationship to 'provide_choice'. Major gaps remain for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the 'session_id' parameter beyond its name. The agent gets no context on how to obtain or format this ID, reducing the tool's usability.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the action (polls), the object (result of an interaction session), and a context clue (switched from Terminal to Web). It distinguishes the tool from its sibling 'provide_choice' by focusing on polling rather than providing input. However, it is vague about what 'result' means.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus 'provide_choice' or any other alternative. There is no mention of prerequisites, conditions for polling, or how the session was initiated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

provide_choiceA

Use this tool to resolve ambiguities, confirm high-risk actions, or validate task completion.

USAGE RULES:
1. SUMMARY: The `prompt` argument MUST follow this structure:
   - A concise summary of actions taken and files modified.
   - What you need the user to decide or if they are satisfied with the result.
2. FEEDBACK INTEGRATION: If a user provides `option_annotations` or `additional_annotation`, treat them as new instructions, execute the changes, and call this tool AGAIN to re-verify.

TERMINAL WORKFLOW:
- If `action_status` == "pending_terminal_launch":
    1. IMMEDIATELY execute the `terminal_command` using the terminal tool.
    2. Monitor output for `[SWITCH_TO_WEB] session_id=xxx`. If found, call `poll_selection(session_id)`.
    3. If `[SELECTION_COMPLETE]` appears, parse the result and proceed.

Args:
    selection_mode: "single" or "multi".
    options: List of dicts (id, description). Always include a `recommended: true` option.
ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes
promptYes
optionsYes
selection_modeYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It transparently explains that the tool presents choices to the user, requires specific arguments, and triggers terminal commands if action_status is pending. However, it does not explicitly state whether the tool is non-destructive or has side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (USAGE RULES, TERMINAL WORKFLOW, Args) and front-loaded purpose. It is slightly verbose but every sentence serves a purpose, effectively communicating complex workflows.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and missing schema descriptions, the description is comprehensive: it covers tool purpose, usage rules, parameter details, terminal workflow integration, and links to sibling poll_selection, enabling correct agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by detailing the prompt structure (summary + decision request), options format (list of dicts with id/description, include recommended), and selection_mode values. It adds significant meaning beyond the schema, though options structure could be more precise.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: 'resolve ambiguities, confirm high-risk actions, or validate task completion.' This is a specific verb-resource combination that clearly distinguishes it from sibling poll_selection, which polls for selections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Detailed USAGE RULES, FEEDBACK INTEGRATION, and TERMINAL WORKFLOW provide explicit guidance on when and how to use the tool, including scenarios like pending_terminal_launch and integration with poll_selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.2.0
    • First observedpoll_selection
    • First observedprovide_choice
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

The two tools—poll_selection and provide_choice—have clearly distinct purposes: one presents choices to the user, the other retrieves results after a web switch. There is no overlap.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern in snake_case: 'poll_selection' and 'provide_choice', which is clear and predictable.

Tool Count3/5

With only 2 tools, the server feels thin for its stated purpose of interactive choices. While the existing tools are comprehensive, the set lacks additional tools for cancellation or session management, making it borderline.

Completeness4/5

The tool set covers the core flow of presenting choices and polling results, but is missing a cancellation or abort mechanism, which is a minor gap for an interactive system.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Interactive Service

    DanielZhao1990
    A
    license
    Not graded
    quality
    C
    maintenance
    An interface enabling high-frequency communication between AI tools (like Cursor and Windsurf) and users, allowing for option selection and information gathering through CLI, Web, or PyQt interfaces.
    28
    MIT

  • AskMeMCP

    thlandgraf
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to request human input through a web interface, allowing them to pause execution and wait for responses via interactive tools like single questions, multiple choice selections, hypothesis challenges, and decision workflows.
    22
    2
    MIT

  • AskMeMCP

    roman-vm
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to request human input through a web interface during execution. Supports single questions, multiple choice selections, hypothesis challenges, and decision workflows for human-in-the-loop interactions.
    22
    MIT

  • mcp-popup-ui

    jens-duttke
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to present interactive choices to users via browser popups, supporting single and multiple selections with optional custom input.
    2
    15
    3
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Sighthesia/interactive-choice-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server