AI-powered prompt refinement with adaptive questioning and multi-provider support (6+ LLM backends)
The MCP server io.github.abhichandra21/promptheus provides AI-powered prompt refinement using adaptive questioning and multi-provider support, described as offering 6+ LLM backends. It is associated with prompt-engineering workflows and supports multiple LLM ecosystems.
๐ ๏ธ Key Features
AI-powered prompt refinement
Adaptive questioning
Multi-provider support (6+ LLM backends)
๐ Use Cases
Refining and optimizing prompts for LLMs
Iterative prompt improvement via adaptive questions
โก Developer Benefits
Multi-provider backend support (6+ LLM backends)
Topics align with common LLM tooling and ecosystems: claude, prompt, prompt-engineering, chatgpt, codex, gemini, claude-code, glm, groq, openai, qwen
โ ๏ธ Limitations
The provided data does not specify additional constraints, supported platforms, or available tools count.
# Interactive session
promptheus
# Single prompt
promptheus "Write a technical blog post"# Skip clarifying questions
promptheus -s "Explain Kubernetes"# Use web UI
promptheus web
Python library usage
python
from promptheus import refine_prompt
result = refine_prompt("Write a technical blog post", skip_questions=True)
print(result["refined_prompt"])
If you're already in an async application (e.g., FastAPI), call refine_prompt_async instead of the sync helper.
What is Promptheus?
Promptheus analyzes your prompts and refines them with:
Adaptive questioning: Smart detection of what information you need to provide
Multi-provider support: Works with Google, OpenAI, Anthropic, Groq, Qwen, and more
Interactive refinement: Iteratively improve outputs through natural conversation
Session history: Automatically track and reuse past prompts
promptheus "Write a blog post about async programming"# System asks: audience, tone, length, key topics# Generates refined prompt with all specifications
Code Analysis
bash
promptheus -s "Review this function for security issues"# Skips questions, applies direct enhancement
Interactive Session
bash
promptheus
/set provider anthropic
/set model claude-3-5-sonnet
# Process multiple prompts, switch providers/models with /commands
Pipeline Integration
bash
echo"Create a REST API schema" | promptheus | jq '.refined_prompt'cat prompts.txt | whileread line; do promptheus "$line"; done
Testing & Examples: See sample_prompts.md for test prompts demonstrating adaptive task detection (analysis vs generation).
Telemetry & Analytics
bash
# View telemetry summary (anonymous metrics about usage and performance)
promptheus telemetry summary
# Disable telemetry if desiredexport PROMPTHEUS_TELEMETRY_ENABLED=0
# Customize history storage locationexport PROMPTHEUS_HISTORY_DIR=~/.custom_promptheus
MCP Server
Promptheus includes a Model Context Protocol (MCP) server that exposes prompt refinement capabilities as standardized tools for integration with MCP-compatible clients.
What the MCP Server Does
The Promptheus MCP server provides:
Prompt refinement with Q&A: Intelligent prompt optimization through adaptive questioning
Prompt tweaking: Surgical modifications to existing prompts
Model/provider inspection: Discovery and validation of available AI providers
Environment validation: Configuration checking and connectivity testing
Starting the MCP Server
bash
# Start the MCP server
promptheus mcp
# Or run directly with Python
python -m promptheus.mcp_server
Prerequisites:
MCP package installed: pip install mcp (included in requirements.txt)
At least one provider API key configured (see Configuration)
Available MCP Tools
refine_prompt
Intelligent prompt refinement with optional clarification questions.
The MCP server supports a structured clarification workflow for optimal prompt refinement:
Step 1: Initial Refinement Request
json
{"tool":"refine_prompt","arguments":{"prompt":"Write a blog post about machine learning"}}
Step 2: Handle Clarification Response
json
{"type":"clarification_needed","task_type":"generation","message":"To refine this prompt effectively, I need to ask...","questions_for_ask_user_question":[{"question":"Who is your target audience?","header":"Q1","multiSelect":false,"options":[{"label":"Technical professionals","description":"Technical professionals"},{"label":"Business executives","description":"Business executives"}]}],"answer_mapping":{"q0":"Who is your target audience?"}}
Step 3: Collect User Answers
Use your MCP client's AskUserQuestion tool with the provided questions, then map answers to question IDs.
Step 4: Final Refinement with Answers
json
{"tool":"refine_prompt","arguments":{"prompt":"Write a blog post about machine learning","answers":{"q0":"Technical professionals"},"answer_mapping":{"q0":"Who is your target audience?"}}}
Response:
json
{"type":"refined","prompt":"Write a comprehensive technical blog post about machine learning fundamentals targeted at software engineers and technical professionals. Include practical code examples and architectural patterns...","next_action":"This refined prompt is now ready to use. If the user asked you to execute/run the prompt, use this refined prompt directly with your own capabilities..."}
AskUser Integration Contract
The MCP server operates in two modes:
Interactive Mode (when AskUserQuestion is available):
Automatically asks clarification questions via injected AskUserQuestion function
Returns refined prompt immediately after collecting answers
Seamless user experience within supported clients
Structured Mode (fallback for all clients):
Returns clarification_needed response with formatted questions
Client responsible for calling AskUserQuestion tool
Answers mapped back via answer_mapping dictionary
Question Format:
Each question in questions_for_ask_user_question includes:
question: The question text to display
header: Short identifier (Q1, Q2, etc.)
multiSelect: Boolean for multi-select options
options: Array of {label, description} for radio/checkbox questions
Answer Mapping:
Question IDs follow pattern: q0, q1, q2, etc.
Answers dictionary uses these IDs as keys: {"q0": "answer", "q1": "answer"}
answer_mapping preserves original question text for provider context
Troubleshooting MCP
MCP Package Not Installed
code
Error: The 'mcp' package is not installed. Please install it with 'pip install mcp'.
Fix:pip install mcp or install Promptheus with dev dependencies: pip install -e .[dev]
Missing Provider API Keys
json
{"type":"error","error_type":"ConfigurationError","message":"No provider configured. Please set API keys in environment."}
Diagnosis: Use list_providers or validate_environment tools to check configuration status
Provider Misconfiguration
json
{"type":"success","providers":{"google":{"configured":false,"error":"GOOGLE_API_KEY not found"},"openai":{"configured":true,"model":"gpt-4o"}}}
Fix: Set missing API keys in .env file or environment variables