Prompt Refiner MCP Server

A Model Context Protocol server that helps systematically refine vague ideas into well-structured prompts through guided clarification.

Philosophy

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

Installation

npm install
npm run build

Usage

Run Locally

node dist/index.js

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "promptrefiner": {
      "command": "node",
      "args": ["/Users/nmelo/Desktop/Projects/prompter/dist/index.js"]
    }
  }
}

Docker (Optional)

docker build -t promptrefiner .
docker run -i promptrefiner

How It Works

The Tool: promptrefiner

Three modes:

1. Start - Begin refinement with original idea

   { originalIdea: "I want to build an API" }
   

2. Clarify - Add clarifications for specific aspects

   {
     aspect: "purpose",
     clarification: "REST API for user authentication with JWT tokens"
   }
   

3. Export - Generate refined prompt using a template

   {
     exportTemplate: "technical-spec",
     refinementComplete: true
   }
   

Aspects to Clarify

• 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

Templates

1. detailed-structured - Comprehensive with sections (Purpose, Audience, Requirements, etc.)
2. concise-bullets - Brief bullet-point format
3. technical-spec - Formal specification style
4. conversational - Natural language paragraph
5. minimal - Just the essentials

Example Session

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

Features

✅ 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

Environment Variables

• DISABLE_PROGRESS_LOGGING=true - Disable colored stderr output

Architecture

• 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

Development

npm run watch      # Watch mode during development
npm run build      # Build for production

License

MIT