# 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

```bash
npm install
npm run build
```

## Usage

### Run Locally

```bash
node dist/index.js
```

### Add to Claude Desktop

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

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

### Docker (Optional)

```bash
docker build -t promptrefiner .
docker run -i promptrefiner
```

## How It Works

### The Tool: `promptrefiner`

**Three modes:**

1. **Start** - Begin refinement with original idea
   ```typescript
   { originalIdea: "I want to build an API" }
   ```

2. **Clarify** - Add clarifications for specific aspects
   ```typescript
   {
     aspect: "purpose",
     clarification: "REST API for user authentication with JWT tokens"
   }
   ```

3. **Export** - Generate refined prompt using a template
   ```typescript
   {
     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

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

## License

MIT