winoooops/chill-mcp-server

Claude Chill MCP Server

A modular MCP (Model Context Protocol) server that delivers inspirational quotes and motivational high-fives with fresh online content. Perfect for coding breaks and achievement celebrations! 🧘‍♂️✨

✨ Features

• 🎯 Global Slash Commands: Custom /quote, /highfive, /chill commands in ALL Claude Code projects
• 🌐 Online-First Content: Dynamic quotes from ZenQuotes.io, Affirmations.dev, and community sources
• 🔄 Smart Fallback: Reliable curated content when APIs are unavailable
• 📚 Multiple Categories: Tech, philosophy, inspirational quotes
• 🎮 Intensity Levels: Mild, epic, legendary motivational responses
• 🏗️ Modular Architecture: Clean, maintainable codebase with services and modules
• 🚀 Multiple Access Methods: Slash commands, MCP prompts, natural language, quick scripts

🚀 Quick Start

One-Command Setup

git clone <your-repo-url>
cd claude-chill-mcp-server
./setup.sh

The setup script will:

• ✅ Install dependencies and build the server
• ✅ Configure with Claude Code's MCP system
• ✅ Install global slash commands (work in ALL projects)
• ✅ Provide usage instructions and troubleshooting

Manual Setup

# Install and build
npm install && npm run build

# Configure with Claude CLI
claude mcp add chill node $(pwd)/dist/index.js

# Install global slash commands
npm run install:commands

# Restart Claude Code

💫 Usage Methods

🎯 Global Slash Commands (Recommended)

Available in ALL your Claude Code projects:

/quote tech                    # Get tech quote
/quote philosophy             # Get philosophy quote  
/highfive epic debugging      # Epic debugging celebration
/highfive legendary coding    # Legendary coding achievement
/chill                        # Surprise motivation

🔧 MCP Slash Commands (Auto-discovered)

/mcp__chill__quote category=tech
/mcp__chill__highfive intensity=legendary context=problem-solving
/mcp__chill__random_quote
/mcp__chill__chill

💬 Natural Language

Just ask naturally:

"Give me a tech quote for motivation"
"I need an epic high-five for solving this bug!"
"Give me some coding inspiration"

⚡ Quick Access Scripts

Use npm scripts for clipboard-powered requests:

npm run chill           # Copy inspirational quote request
npm run chill:tech      # Copy tech quote request
npm run chill:highfive  # Copy high-five request

🎮 Commands Reference

Slash Commands

Parameters

Quote Categories: tech, philosophy, inspirational

High-Five Intensities:

• mild - Encouraging for everyday wins
• epic - High-energy for significant achievements
• legendary - Cosmic compliments for extraordinary moments

High-Five Contexts: coding, problem-solving, debugging, general

🌐 Dynamic Content System

Online Sources (Primary)

• ZenQuotes.io: 3,237+ inspirational quotes (free, no API key)
• Affirmations.dev: Developer-focused positive affirmations
• GitHub Dataset: Community-contributed affirmations

Content Strategy

• Primary: Always tries online content first for maximum freshness
• Backup: Curated static content when APIs fail
• Smart Selection: Randomly chooses between available sources
• 100% Reliable: Always works even without internet

Example Enhanced Outputs

External Quote:

🔥⚡ CODE MASTERY! Here's wisdom for your journey: "The best way to predict the future is to invent it." — Alan Kay

External Affirmation:

👑 LEGENDARY! You are capable of amazing things and your potential is limitless!

Curated Compliment:

🌟🚀 PHENOMENAL HUMAN! You're crushing it beyond measure!

🏗️ Modular Architecture

Directory Structure

src/
├── index.ts                    # Main MCP server entry point  
├── services/                   # Business logic & external APIs
│   ├── quote-service.ts        # Quote fetching & management
│   └── motivational-service.ts # High-five content & APIs
└── modules/                    # Feature handlers
    ├── quote-module.ts         # Quote tools & prompts
    └── highfive-module.ts      # High-five tools & prompts

Benefits

• 🔧 Maintainable: Clear separation of concerns, easy to extend
• 📈 Scalable: Add new APIs in services, new features in modules
• 🛠️ Developer-Friendly: Focused editing, code reuse, TypeScript safety
• 🔍 Debuggable: Isolated issues, clear error paths

🔧 Development

Build Commands

npm run build          # Build for production
npm run dev            # Development with auto-rebuild
npm start              # Run built server
npm test               # Test the build

Customization

Add New Slash Commands:

1. Create .md file in templates/claude-commands/
2. Follow the format:

   ---
   description: Command description
   argument-hint: [arg1|arg2] [optional-arg]
   ---
   
   Your command prompt here$ARGUMENTS
   

3. Run npm run install:commands

Add New External APIs:

1. Add API method to appropriate service
2. Update service logic to include new source
3. No changes needed in modules or main server!

Extend Functionality:

1. Create new module in src/modules/
2. Implement tool/prompt handlers
3. Import and initialize in main server

🚨 Troubleshooting

Slash Commands Not Working

# Check if global commands exist
ls -la ~/.claude/commands/

# Reinstall commands
npm run install:commands

# Restart Claude Code completely
# Check /help for "(user)" labels

MCP Server Issues

# Verify server is configured
claude mcp list
# Should show: chill: node /path/to/dist/index.js

# Rebuild if needed
npm run build

# Check server status in Claude Code
/status

API Content Not Showing

• External APIs work ~95% of the time when internet is available
• Server automatically falls back to curated content
• Check Claude Code console for API status logs

📦 Repository Structure

claude-chill-mcp-server/
├── src/                      # Modular source code
│   ├── index.ts              # Main MCP server entry point  
│   ├── services/             # Business logic & external APIs
│   └── modules/              # Feature handlers
├── dist/                     # Compiled JavaScript
├── templates/claude-commands/ # Slash command templates
├── package.json              # Dependencies and scripts
├── setup.sh                  # Automated setup script
└── README.md                 # This comprehensive guide

🎯 Pro Tips

1. Use /help to see all available commands with "(user)" labels
2. Tab completion works for both custom and MCP slash commands
3. Try different intensities - mild for encouragement, legendary for celebration
4. Mix contexts - use coding for implementation, debugging for problem-solving
5. Natural language fallback - just ask Claude normally if commands don't work

🌟 What's Next

Your chill vibes are now:

• ✅ Globally available across all Claude Code projects
• ✅ Dynamically powered by online motivational content
• ✅ Architecturally sound with clean, modular code
• ✅ Reliably backed up with curated static content
• ✅ Developer-friendly with multiple access methods

Ready to experience enhanced chill vibes? Try /quote tech or /highfive epic coding right now! 🎉

📄 License

MIT License - feel free to use and modify for your own Claude Code setup!

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add quotes, improve functionality, or enhance the architecture
4. Submit a pull request

Transform your coding sessions with dynamic motivation and architectural excellence! 🧘‍♂️✨