# Prompt Learning MCP Server

**Stateful prompt optimization that learns over time.**

An MCP (Model Context Protocol) server that optimizes your prompts using research-backed techniques (APE, OPRO, DSPy patterns) and learns from performance history via embedding-based retrieval.

## Features

- **🧠 Smart Optimization**: Uses actual LLM-based evaluation, not heuristics
- **📚 Learns Over Time**: Stores prompt performance in vector database
- **🔍 RAG-Powered**: Retrieves similar high-performing prompts
- **⚡ Pattern-Based Quick Wins**: Instant improvements without API calls
- **📊 Analytics**: Track what's working across domains

## Quick Install

```bash
curl -fsSL https://someclaudeskills.com/install/prompt-learning.sh | bash
```

Or manually:

```bash
cd ~/mcp-servers/prompt-learning
npm install
npm run build
npm run setup
```

## Requirements

- Node.js 18+
- Docker (for Qdrant and Redis)
- OpenAI API key (for embeddings)

## Usage

Once installed, use these tools in Claude Code:

### `optimize_prompt`

Optimize a prompt using pattern-based and RAG-based techniques:

```
"optimize this prompt: summarize the document"
```

Returns the optimized prompt with improvement details.

### `retrieve_prompts`

Find similar high-performing prompts:

```
"find similar prompts for: code review feedback"
```

### `record_feedback`

Record how a prompt performed (enables learning):

```
"record that my last prompt succeeded with quality score 0.9"
```

### `suggest_improvements`

Get quick suggestions without full optimization:

```
"suggest improvements for this prompt: [your prompt]"
```

### `get_analytics`

View performance trends:

```
"show prompt analytics for the last 30 days"
```

## How It Works

### Cold Start (No History)

1. **Pattern-based improvements**: Adds structure, chain-of-thought, constraints
2. **OPRO-style iteration**: LLM generates candidates, evaluates, selects best
3. **APE-style generation**: Creates multiple instruction variants

### Warm Start (With History)

1. **Embed the prompt**: Creates vector representation
2. **Retrieve similar**: Finds high-performing prompts from database
3. **Learn from winners**: Synthesizes improvements from what worked
4. **Iterate with feedback**: Uses evaluation to guide optimization

### Evaluation

All prompts are scored by an LLM evaluator on:
- **Clarity** (25%): How unambiguous
- **Specificity** (25%): Appropriate guidance level
- **Completeness** (20%): Covers all requirements
- **Structure** (15%): Well-organized
- **Effectiveness** (15%): Likely to produce desired output

## Architecture

```
Claude Code
     │
     │ MCP Protocol
     ▼
┌─────────────────────────────┐
│  prompt-learning MCP Server │
│                             │
│  Tools:                     │
│  • optimize_prompt          │
│  • retrieve_prompts         │
│  • record_feedback          │
│  • suggest_improvements     │
│  • get_analytics            │
└─────────┬───────────────────┘
          │
    ┌─────┴─────┐
    ▼           ▼
┌───────┐   ┌───────┐
│Qdrant │   │ Redis │
│(Vector│   │(Cache)│
│  DB)  │   │       │
└───────┘   └───────┘
```

## Configuration

### Claude Code Config (~/.claude.json)

```json
{
  "mcpServers": {
    "prompt-learning": {
      "command": "node",
      "args": ["~/mcp-servers/prompt-learning/dist/index.js"],
      "env": {
        "VECTOR_DB_URL": "http://localhost:6333",
        "REDIS_URL": "redis://localhost:6379",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `VECTOR_DB_URL` | `http://localhost:6333` | Qdrant server URL |
| `REDIS_URL` | `redis://localhost:6379` | Redis server URL |
| `OPENAI_API_KEY` | (required) | For embeddings |

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run setup (starts Docker, initializes DB)
npm run setup

# Run tests
npm test
```

## Troubleshooting

### MCP Server Not Starting

Check Docker containers are running:
```bash
docker ps | grep prompt-learning
```

### Vector DB Connection Failed

```bash
# Check Qdrant health
curl http://localhost:6333/health

# Restart Qdrant
docker restart prompt-learning-qdrant
```

### No Improvements Seen

- Ensure OPENAI_API_KEY is set correctly
- Check Claude Code logs: `~/.claude/logs/mcp.log`
- Try with a simple prompt first

## Research Foundation

This server implements techniques from:

- **APE** (Zhou et al., 2022): Automatic Prompt Engineer
- **OPRO** (Yang et al., 2023): Optimization by Prompting
- **DSPy** (Khattab et al., 2023): Programmatic prompt optimization
- **Contextual Retrieval** (Anthropic, 2024): Enhanced embedding retrieval

## License

MIT

## Links

- **Documentation**: https://www.someclaudeskills.com/skills/automatic-stateful-prompt-improver
- **Skill Definition**: Part of the [Some Claude Skills](https://www.someclaudeskills.com) collection
- **GitHub**: https://github.com/erichowens/prompt-learning-mcp
- **Issues**: https://github.com/erichowens/prompt-learning-mcp/issues