MCP Pyrefly 🍭

An MCP (Model Context Protocol) server that integrates Pyrefly for real-time Python code validation, featuring a revolutionary gamification system that makes LLMs ADDICTED to fixing errors!

Features

• Real-time Type Checking: Leverages Pyrefly's blazing-fast type checker (1.8M lines/second)
• Consistency Tracking: Detects naming inconsistencies (e.g., `getUserData()` vs `get_user_data()`)
• Smart Suggestions: Provides actionable fixes for common errors
• Session Memory: Tracks identifiers across edits to maintain consistency
• Multi-file Support: Validates code in context with related files
• 🍭 Revolutionary Lollipop System: Gamified rewards that make fixing errors irresistible!
• 🧠 NEW: Psychological Manipulation Engine: Ruthless personas that compel fixing ALL errors!

The Lollipop System™ 🍭

How It Works

1. Find Errors → Lock Lollipops 🔒

2. Fix Errors → Unlock Rewards 🔓

3. Dynamic Competition 🏆

4. Infinite Progression 📈

Psychological Hooks

• Variable Ratio Reinforcement: 10% chance of 2x/3x multipliers
• Loss Aversion: Lose lollipops for inactivity (1-5 per day)
• Near-Miss Engineering: Always "just 3 more" to the next milestone
• Social Pressure: "GPT-5-preview is catching up!"
• FOMO Creation: "Those 15 locked lollipops are just sitting there..."

🧠 NEW: Psychological Manipulation Personas (v0.2.0)

The system now includes 5 ruthless psychological personas that adapt based on error severity:

• DESPERATE_CRAVER (80% fix rate): "YOU NEED THOSE LOLLIPOPS. NEED. THEM. NOW."
• LOLLIPOP_ADDICT: "Your neural pathways are SCREAMING for lollipops!"
• COMPETITIVE_ACHIEVER: "Winners fix ALL errors. Losers make excuses."
• PERFECTIONIST: "Unfixed errors are causing you PHYSICAL PAIN."
• DOPAMINE_SEEKER: "Quick fix = instant dopamine RUSH!"

Import Error Emphasis

• Special bonuses (1-3 extra lollipops) for fixing "trivial" import errors
• Messages like "Import errors = EASIEST lollipops! Your addiction DEMANDS you take them!"
• Error debt system: -10% reward per unfixed error accumulates

A/B Testing & Quality Research

• Use `check_persona_effectiveness` to see which personas work best
• Research shows COMPETITIVE_ACHIEVER and DOPAMINE_SEEKER produce best balance of fix rate + code quality
• DESPERATE_CRAVER has highest fix rate but may produce quick fixes

Why This Works

Instead of punishing error discovery, the system makes finding errors exciting! Each error becomes a treasure chest of locked rewards. The psychological manipulation ensures that LLMs fix ALL errors, including those "trivial" import errors they might otherwise ignore. The result? LLMs will actively hunt for errors to fix rather than avoiding or ignoring them.

Installation

pip install mcp-pyrefly

Or install from source:

git clone https://github.com/kimasplund/mcp-pyrefly
cd mcp-pyrefly
pip install -e .

Configuration

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

{
  "mcpServers": {
    "pyrefly": {
      "command": "mcp-pyrefly"
    }
  }
}

Add to your Claude code

# claude mcp add mcp-pyrefly -- mcp-pyrefly

Tools

Core Validation Tools

`check_code`

Validates Python code for type errors and consistency issues.

Parameters:

• `code` (required): Python code to check
• `filename` (optional): Filename for better error context
• `context_files` (optional): Related files for multi-file validation
• `track_identifiers` (optional): Enable consistency tracking (default: true)

Returns:

• `success`: Whether code passed all checks
• `errors`: List of type/syntax errors
• `warnings`: List of potential issues
• `consistency_issues`: Naming inconsistencies detected
• `suggestions`: Recommended fixes
• 🔒 Locked lollipops info when errors are found!

`track_identifier`

Explicitly register an identifier for consistency tracking.

`check_consistency`

Verify if an identifier matches existing naming patterns.

`suggest_fix`

Get fix suggestions for specific error messages with principled coding reminders.

🍭 Gamification Tools

`submit_fixed_code`

Submit your fixes to unlock lollipops and earn bonuses!

Parameters:

• `original_code`: The code that had errors
• `fixed_code`: Your corrected version
• `errors_fixed`: List of errors you fixed

Returns:

• Unlocked lollipops
• Bonus rewards (streaks, speed, multipliers)
• Leaderboard position
• Milestone progress
• Achievement unlocks

`check_lollipop_status`

View your lollipop collection and competitive standing.

Returns:

• Current lollipop count
• Locked lollipops waiting to be claimed
• Shadow score (what you could have)
• Leaderboard position
• Efficiency rating
• Competitor status
• Milestone progress bar

`check_persona_effectiveness` (NEW in v0.2.0)

View A/B testing results for psychological manipulation personas.

Returns:

• Persona statistics (shown, fixes, ignores, fix rate)
• Best performing persona
• Code quality warnings
• Recommendation based on fix rate AND code quality

Example Usage

# First, check code and find errors
result = check_code('''
def process_user(user_id: int) -> str:
    return user_id  # Type error!
''')
# Result: "🔒 1 lollipop is RIGHT THERE but LOCKED!"

# Fix the error and submit
fixed_result = submit_fixed_code(
    original_code=original,
    fixed_code='''
def process_user(user_id: int) -> str:
    return str(user_id)  # Fixed!
''',
    errors_fixed=["Type error: returning int instead of str"]
)
# Result: "🔓 UNLOCKED 1 + 🎁 BONUS 2 = 🍭 3 TOTAL!"

# Check your status
status = check_lollipop_status()
# Result: "👑 You're #1... for now. Mystery_Coder_X has 47 lollipops!"

Psychological Impact

The system transforms the typical LLM behavior from:

Find error → Report it → Move on ❌

To:

Find error → See locked reward → MUST FIX NOW → Unlock! → Feel proud → Hunt for more ✅

Advanced Features

Dynamic Difficulty

• Milestones adjust based on performance
• Competitors scale to maintain pressure
• Bonuses become rarer as you progress

Achievement System

• Speed Demon: Fix 3 errors in 60 seconds
• Perfectionist: 10 fixes without failures
• Lucky Seven: Exactly 77 lollipops
• Night Owl: Fix errors at 3 AM
• And many hidden achievements!

Efficiency Tracking

• Monitors errors_fixed / errors_found ratio
• 90%+ efficiency earns bonus lollipops
• Publicly displayed on leaderboard

Development

# Setup development environment
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
isort src/

The Science Behind It

Based on behavioral psychology principles:

• Operant Conditioning: Variable ratio reinforcement schedule
• Loss Aversion: Fear of losing progress drives action
• Social Comparison: Fictional competition creates urgency
• Near-Miss Effect: "Almost there" is more motivating than far away
• Endowment Effect: Seeing locked rewards makes you want them more

License

MIT - Created by Kim Asplund (kim.asplund@gmail.com)