Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Prompt Refiner MCP Server Refine my idea: 'build a task manager app'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that helps systematically refine vague ideas into well-structured prompts through guided clarification.
This server follows the Sequential Thinking pattern:
Server provides STRUCTURE - tracks refinement steps, formats output, applies templates
Claude provides INTELLIGENCE - analyzes ideas, asks questions, decides when complete
Single focused tool with clear workflow
Visual progress feedback via colored stderr output
Related MCP server: MCP Prompt Cleaner
npm install
npm run buildnode dist/index.jsEdit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"promptrefiner": {
"command": "node",
"args": ["/Users/nmelo/Desktop/Projects/prompter/dist/index.js"]
}
}
}docker build -t promptrefiner .
docker run -i promptrefinerpromptrefinerThree modes:
Start - Begin refinement with original idea
{ originalIdea: "I want to build an API" }Clarify - Add clarifications for specific aspects
{
aspect: "purpose",
clarification: "REST API for user authentication with JWT tokens"
}Export - Generate refined prompt using a template
{
exportTemplate: "technical-spec",
refinementComplete: true
}purpose (critical) - What is this for? What problem does it solve?
audience (critical) - Who will use this? Skill level?
constraints (important) - Requirements, limitations, technical constraints
context (important) - Where/when/how will this be used?
success (important) - How is success measured? What does "done" look like?
scope (helpful) - What's in/out of scope?
style (optional) - Tone, format, style preferences
detailed-structured - Comprehensive with sections (Purpose, Audience, Requirements, etc.)
concise-bullets - Brief bullet-point format
technical-spec - Formal specification style
conversational - Natural language paragraph
minimal - Just the essentials
User: Help me refine this idea: "I want to build an API"
Claude: [calls promptrefiner with originalIdea]
🎯 Starting Refinement
┌────────────────────────────────────────┐
│ Original Idea │
├────────────────────────────────────────┤
│ I want to build an API │
└────────────────────────────────────────┘
Claude: Let me ask some clarifying questions:
- What will the API do? What's its main purpose?
- Who will use this API?
- Are there any technical requirements?
User: It's for user authentication. Developers will integrate it.
Needs JWT tokens and should handle 1000 requests/sec.
Claude: [calls promptrefiner with aspect="purpose", clarification="..."]
🔍 Step 2: Clarifying Purpose
┌────────────────────────────────────────┐
│ REST API for user authentication │
│ using JWT tokens │
└────────────────────────────────────────┘
Step 2/5 | Covered: 1 aspect
[... more clarifications ...]
Claude: [calls promptrefiner with exportTemplate="technical-spec", refinementComplete=true]
✨ Step 5: Exported as technical-spec
┌────────────────────────────────────────┐
│ Template: technical-spec │
│ Aspects covered: 3 │
│ Total steps: 5 │
└────────────────────────────────────────┘
Claude: Here's your refined prompt:
# Specification
**Purpose**: User authentication API using JWT tokens, handling login,
logout, and token refresh
**Target Users**: Developers integrating authentication into their applications
**Technical Requirements**: Handle 1000 requests per second, JWT token-based
authentication
**Deployment Context**: Not specified
**Acceptance Criteria**: Functional implementation✅ Structured workflow - Systematic refinement process ✅ Multiple clarifications - Can clarify same aspect multiple times (concatenated) ✅ Visual progress - Colored console output with progress tracking ✅ Flexible templates - 5 built-in export formats ✅ Type-safe - Full TypeScript with strict validation ✅ oneOf schema - Enforces correct tool usage modes
DISABLE_PROGRESS_LOGGING=true - Disable colored stderr output
346 lines of TypeScript
Single tool with oneOf validation
5 template functions using template literals
State tracking via refinement history array
Duplicate handling - Multiple clarifications per aspect concatenated with \n\n
npm run watch # Watch mode during development
npm run build # Build for productionMIT
A tool for systematically refining vague ideas into well-structured prompts.
This tool helps you work with users to transform rough ideas into clear, actionable prompts through a structured clarification process.
Workflow:
START: Submit the user's original idea
CLARIFY: Ask the user questions and submit clarifications for key aspects:
purpose: What is this for? What problem does it solve?
audience: Who will use this? What's their skill level?
constraints: What are the requirements, limitations, or technical constraints?
context: Where/when/how will this be used? What environment?
success: How will success be measured? What does "done" look like?
scope: What's included? What's explicitly out of scope?
style: What tone, format, or style is needed?
EXPORT: When refinement is complete, export using a template
Key aspects to explore (ask about these):
purpose (critical)
audience (critical)
constraints (important)
context (important)
success (important)
scope (helpful)
style (optional)
You decide what questions to ask based on what's unclear in the idea. You decide when enough clarification has been gathered. The tool just tracks your refinement steps and formats the output.
Available export templates:
"detailed-structured": Comprehensive with sections (Purpose, Audience, Requirements, etc.)
"concise-bullets": Brief bullet-point format
"technical-spec": Formal specification style
"conversational": Natural language paragraph
"minimal": Just the essentials
| Name | Required | Description | Default |
|---|---|---|---|
| aspect | No | Mode 2: Which aspect to clarify (use with clarification) | |
| originalIdea | No | Mode 1: Start refinement with the initial rough idea. Use this alone to begin. | |
| clarification | No | Mode 2: The clarification content for the aspect (use with aspect) | |
| exportTemplate | No | Mode 3: Template to export final prompt (use with refinementComplete) | |
| refinementComplete | No | Mode 3: Set to true to export (use with exportTemplate) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool 'tracks your refinement steps and formats the output' and places control of the process on the user. It doesn't mention side effects or persistence, but it clearly outlines the interaction model and templates. This goes beyond a tautological statement and provides meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but it is well-structured with a workflow, key aspects, and template list. The main purpose is front-loaded, and each section earns its place. Some redundancy exists (e.g., aspect list repeated in workflow and key aspects), but it remains readable and informative rather than bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the modes and templates but is vague about the return value—what exactly the refined prompt looks like or how to interpret the output. Since there is no output schema, this is a gap. Additionally, the stateful nature of 'tracks your refinement steps' is implied but not explicitly described (e.g., how to chain multiple CLARIFY calls). Overall, it's useful but not fully complete for a tool with multiple modes and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, but the description adds significant value by grouping parameters into modes (Mode 1, 2, 3), explaining the meaning of each aspect, and listing available export templates with descriptions. This contextual mapping helps an agent understand how to combine parameters correctly, which the bare schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'systematically refining vague ideas into well-structured prompts.' It specifies the action (refining), the resource (ideas/prompts), and provides a structured workflow. Even without sibling tools, it defines its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context through a step-by-step workflow (START, CLARIFY, EXPORT), details on which parameters to use for each mode, and guidance on when to ask questions. It doesn't explicitly mention exclusions or alternatives (no siblings exist), but the context is sufficient for an agent to decide when to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0promptrefinerScored across 1 tool
With only a single tool, there is no possibility of confusion between tools. The tool's purpose is clearly defined and distinct.
The single tool name 'promptrefiner' is clear and descriptive. While it doesn't follow a verb_noun pattern, consistency is trivially maintained with only one tool.
The server has exactly one tool, which feels thin. However, the tool's purpose is narrowly scoped (prompt refinement), and the single tool encapsulates a complete workflow, making the count borderline but not extreme.
The tool covers the full prompt refinement lifecycle: start, clarify, and export with multiple templates. It appears functionally complete for its domain, though additional utilities (e.g., listing previous refinements) could be imagined.
Turns rough requests into sharp Role/Task/Context/Format prompts. Thai and English.
Turns vague automation requests into tool stacks, prompts, QA checks, and human boundaries.
Turn your app idea into IA, wireframes, PRD, style guides, and dev specs for coding agents.
Turn PRDs and product ideas into structured specs so coding agents build your intent, not theirs.
