mindvalley-products-mcp/README.md

Model Context Protocol (MCP) server providing AI assistants with structured data on Mindvalley's educational offerings - products, masterclasses, programs, and certifications

# Mindvalley Products MCP Server

[![npm version](https://badge.fury.io/js/mindvalley-products-mcp.svg)](https://badge.fury.io/js/mindvalley-products-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js CI](https://github.com/mazemax/mindvalley-products-mcp/workflows/CI%2FCD/badge.svg)](https://github.com/mazemax/mindvalley-products-mcp/actions)

A Model Context Protocol (MCP) server that provides AI assistants with structured access to Mindvalley's educational offerings, including products, masterclasses, programs, and certifications.

## ✨ Features

- 🚀 **4 MCP Tools** - Access products, masterclasses, programs, and certifications
- 🔒 **Read-Only & Safe** - Non-destructive operations with static data
- ⚡ **Fast Performance** - No external API calls, instant responses
- 🎯 **Smart Filtering** - Optional parameters for targeted queries
- 🔧 **Easy Integration** - Works with Claude Desktop, Cursor IDE, and custom clients
- 📚 **Complete Documentation** - Comprehensive examples and guides

## 🚦 Quick Start

### Installation

```bash
# Install globally for easy access
npm install -g mindvalley-products-mcp

# Or install locally in your project
npm install mindvalley-products-mcp
```

### Usage with Claude Desktop

1. **Add to Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "mindvalley-products": {
      "command": "npx",
      "args": ["mindvalley-products-mcp"]
    }
  }
}
```

2. **Restart Claude Desktop** and start asking questions like:
   - "What products does Mindvalley offer?"
   - "Show me masterclasses with Jim Kwik"
   - "What programs are in the Mind category?"

## 🛠️ Available Tools

### 1. **products** - Mindvalley Core Products
Get information about Mindvalley's subscription products and pricing.

```typescript
// Get all products
products()

// Get specific product
products({ name: "Mindvalley Membership" })
```

**Response includes**: Product names, descriptions, pricing (monthly/annual), checkout URLs

### 2. **masterclasses** - Free Masterclasses
Access current Mindvalley masterclasses with registration links.

```typescript
// Get all masterclasses
masterclasses()

// Filter by title
masterclasses({ title: "Superbrain" })
```

**Response includes**: Masterclass titles, hosts, descriptions, registration URLs

### 3. **programs** - Educational Programs
Browse Mindvalley's learning programs organized by category.

```typescript
// Get all programs (by category)
programs()

// Get programs in specific category
programs({ category: "Mind" })
```

**Available categories**: Mind, Body, Soul, Career, Entrepreneurship, Relationships, Parenting

### 4. **certifications** - Coaching Certifications
Information about Mindvalley's professional certifications.

```typescript
// Get all certifications
certifications()

// Filter by name
certifications({ name: "Life Coach" })
```

**Response includes**: Certification names, providers, duration, requirements, signup URLs

## 📖 Integration Guides

### Claude Desktop
Detailed setup guide: [`examples/claude-desktop/README.md`](examples/claude-desktop/README.md)

### Cursor IDE
Integration instructions: [`examples/cursor/README.md`](examples/cursor/README.md)

### Custom MCP Client
Programmatic usage example: [`examples/mcp-client/README.md`](examples/mcp-client/README.md)

## 💡 Example Use Cases

### Personal Learning Planning
> **User**: "I want to improve my memory and focus. What does Mindvalley offer?"
> 
> **AI Response**: Based on your interests, I found several relevant options:
> 
> **Masterclass (Free)**: Superbrain Masterclass with Jim Kwik - "Unlock Your Memory & Brain Power"
> 
> **Program**: Superbrain by Jim Kwik - Full program for memory improvement
> 
> **Also relevant**: "Becoming Focused and Indistractable" by Nir Eyal in the Career category

### Product Comparison
> **User**: "Compare Mindvalley Membership vs Membership Pro"
> 
> **AI Response**: Here's the comparison:
> 
> **Mindvalley Membership** ($499/year or $99/month)
> - All-access subscription to 100+ quests and meditations
> 
> **Mindvalley Membership Pro** ($698/year only)  
> - Everything in Membership plus live coaching sessions
> - Additional $199/year for live coaching access

### Certification Research
> **User**: "I want to become a certified coach. What options does Mindvalley have?"
> 
> **AI Response**: Mindvalley offers several coaching certifications through Evercoach:
> 
> **Certified Life Coach** (4 months) - $200 refundable deposit
> **Certified Business Coach** (4 months) - For corporate/executive coaching
> **Certified Hypnotherapist** (16 weeks) - Led by Paul McKenna

## 🔧 Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/mazemax/mindvalley-products-mcp.git
cd mindvalley-products-mcp

# Install dependencies
pnpm install

# Build the server
pnpm run build

# Run tests
pnpm test

# Start development mode (with hot-reload)
pnpm run dev
```

### Project Structure

```
mindvalley-products-mcp/
├── src/
│   ├── tools/              # MCP tool implementations
│   │   ├── products.ts
│   │   ├── masterclasses.ts
│   │   ├── programs.ts
│   │   └── certifications.ts
│   └── resources/          # Static data source
│       └── mindvalley_data.json
├── examples/               # Integration examples
│   ├── claude-desktop/
│   ├── cursor/
│   └── mcp-client/
├── dist/                   # Built server files
└── docs/                   # Additional documentation
```

### Adding New Tools

1. Create a new file in `src/tools/`
2. Export `schema`, `metadata`, and default function
3. XMCP automatically discovers and registers the tool

```typescript
import { z } from "zod";
import data from "../resources/mindvalley_data.json";

export const schema = {
  filter: z.string().optional().describe("Filter parameter"),
};

export const metadata = {
  name: "new-tool",
  description: "Description of what the tool does",
  annotations: {
    title: "New Tool",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
  },
};

export default async function newTool({ filter }: { filter?: string }) {
  // Implementation
  return { content: [{ type: "text", text: JSON.stringify(result) }] };
}
```

## 🔍 Troubleshooting

### Common Issues

**❌ "Command not found: mindvalley-products-mcp"**
```bash
# Verify installation
npm list -g mindvalley-products-mcp

# Reinstall if needed
npm install -g mindvalley-products-mcp
```

**❌ "Server failed to start"**
```bash
# Check Node.js version (requires >=20.0.0)
node --version

# Test the server directly
npx mindvalley-products-mcp

# Check for error messages in AI assistant logs
```

**❌ "Tools not available in AI assistant"**
- Restart your AI assistant after configuration changes
- Verify JSON syntax in MCP configuration file
- Check that the server path is correct

### Testing the Server

Test the server independently before integration:

```bash
# Test if server starts correctly
npx mindvalley-products-mcp

# Run the test suite
cd examples/mcp-client
node example.js
```

### Configuration Validation

Verify your MCP configuration:

```bash
# Check Claude Desktop config
cat "~/Library/Application Support/Claude/claude_desktop_config.json" | jq

# Test configuration syntax
node -e "console.log(JSON.parse(require('fs').readFileSync('config.json')))"
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Quick Contribution Steps

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Run tests: `pnpm test`
5. Commit: `git commit -m 'Add amazing feature'`
6. Push: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Types of Contributions

- 🐛 **Bug fixes** - Fix issues and improve stability
- ✨ **New features** - Add new tools or enhance existing ones
- 📖 **Documentation** - Improve guides and examples
- 🧪 **Tests** - Add or improve test coverage
- 🔄 **Data updates** - Keep Mindvalley information current

## 📊 Data Source

All data is sourced from publicly available Mindvalley information and stored in `src/resources/mindvalley_data.json`. The data includes:

- **Products**: Official pricing and checkout URLs
- **Masterclasses**: Current free masterclass offerings
- **Programs**: Categorized learning content
- **Certifications**: Professional certification programs

> **Note**: Data is static and updated manually. For the most current information, always verify with official Mindvalley sources.

## 🛡️ Security & Privacy

- **No API Keys**: No external API calls or authentication required
- **Public Data Only**: Contains only publicly available information
- **No User Data**: No personal information is collected or stored
- **Safe Operations**: All tools are read-only and non-destructive

For security concerns, please see our [Security Policy](SECURITY.md).

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **NPM Package**: https://www.npmjs.com/package/mindvalley-products-mcp
- **GitHub Repository**: https://github.com/mazemax/mindvalley-products-mcp
- **Issue Tracker**: https://github.com/mazemax/mindvalley-products-mcp/issues
- **MCP Protocol**: https://modelcontextprotocol.io
- **Mindvalley**: https://www.mindvalley.com

## 🙏 Acknowledgments

- **Model Context Protocol** - For the excellent protocol specification
- **XMCP Framework** - For the development framework
- **Mindvalley** - For the educational content (this is an unofficial project)
- **Community** - For feedback, contributions, and support

---

**Made with ❤️ by [Max Saad](https://github.com/mazemax)**

*This is an unofficial project and is not affiliated with or endorsed by Mindvalley.*