npm package: @swift-learning/mcp
Description: MCP server for Swift/SwiftUI learning with curated patterns from top iOS developers. Optional Patreon integration for premium content.
Author: Lasha Efremidze
Latest version: 1.0.0

# swift-mcp

> Curated Swift/SwiftUI patterns from top iOS developers

An MCP (Model Context Protocol) server that brings best practices from leading iOS developers to your AI coding assistant. Works out-of-the-box with free sources, with optional premium content via Patreon.

## ✨ Features

### 🆓 Always Available (Free)
- **Swift by Sundell** - In-depth articles and patterns from John Sundell
- **Antoine van der Lee** - Practical iOS development tips and performance guides
- **Kavsoft** - Advanced SwiftUI UI and animation tutorials (Coming soon)
- **Point-Free** - Open source Swift libraries and architecture patterns (Coming soon)

### 💎 Optional Premium
- **Patreon Integration** - Access content from iOS creators you support
  - High-quality pattern extraction
  - Automatic code zip extraction
  - Smart relevance filtering
  - Multi-creator support

## 🚀 Quick Start

### Installation

```bash
npm install -g @swift-learning/mcp
```

### Basic Setup (Free Sources)

```bash
# Start using immediately - no setup needed!
# Free sources work out of the box
```

### Optional: Add Patreon

```bash
# Enable premium content from your Patreon subscriptions
swift-mcp setup --patreon
```

### Use with AI Assistants

#### Cursor

Add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "swift": {
      "command": "npx",
      "args": ["-y", "@swift-learning/mcp@latest"]
    }
  }
}
```

#### Claude Code

```bash
claude mcp add swift -- npx -y @swift-learning/mcp@latest
```

## 💡 Example Usage

### Basic (Free Sources)

**You**: "Show me SwiftUI animation patterns"

**AI**: Returns curated patterns from Sundell, van der Lee, with:
- Pattern descriptions
- Code examples
- Quality scores
- Direct links to full articles

### With Patreon Enabled

**You**: "Show me advanced async/await patterns from my Patreon"

**AI**: Returns:
- Premium content from creators you support
- Extracted code from zip files
- High-quality filtered results
- Complete project examples

### Search Specific Source

**You**: "What does Sundell say about testing?"

**AI**: Returns only Swift by Sundell articles about testing

## 📚 Content Sources

### Free Sources (No Setup Required)

| Source | Content Type | Topics Covered |
|--------|--------------|----------------|
| **Swift by Sundell** | Articles, Patterns | Testing, Architecture, Best Practices |
| **Antoine van der Lee** | Tutorials, Tips | Performance, Debugging, Tooling |
| **Kavsoft** | YouTube Videos | SwiftUI, Animations, UI Design |
| **Point-Free** | OSS Libraries | Functional Programming, TCA |

### Premium Sources (Optional)

| Source | Setup | What You Get |
|--------|-------|--------------|
| **Patreon** | OAuth | Content from creators you support |
| **GitHub Sponsors** | OAuth | Coming soon |

## ⚙️ Configuration

### View Available Sources

```bash
swift-mcp source list
```

Output:
```
Free Sources (Always Available)
✅ Swift by Sundell
✅ Antoine van der Lee
✅ Kavsoft (YouTube)
✅ Point-Free (OSS)

Premium Sources (Optional)
⬜ Patreon (Setup required)
⬜ GitHub Sponsors (Coming soon)
```

### Enable/Disable Sources

```bash
# Enable Patreon (requires setup first)
swift-mcp setup --patreon

# Disable a source
swift-mcp source disable kavsoft

# Re-enable a source
swift-mcp source enable kavsoft
```

## 🔧 Patreon Setup

### Prerequisites

1. Active Patreon account
2. Subscribed to iOS creator(s)
3. Patreon OAuth app (automated setup helps with this)

### Setup Process

```bash
swift-mcp setup --patreon
```

This will:
1. Open browser for Patreon OAuth
2. Connect your subscriptions
3. Analyze content quality
4. Enable premium patterns

**Time**: ~5 minutes (one-time)

### What You Get

After setup:
- ✅ All your Patreon subscriptions in one place
- ✅ Automatic quality filtering (scores 0-100)
- ✅ Code extraction from zip files
- ✅ Smart topic detection
- ✅ Search across all creators

## 📖 Available MCP Tools

### Core Tools (Always Available)

#### `get_swift_pattern`
Get Swift/SwiftUI patterns from free sources
```typescript
{
  topic: "swiftui" | "testing" | "async-await" | etc,
  source: "all" | "sundell" | "vanderlee",
  minQuality: 60 // 0-100
}
```

#### `search_swift_content`
Search all enabled sources
```typescript
{
  query: "your search query",
  requireCode: true // Only return results with code
}
```

#### `list_content_sources`
View all sources and their status

### Patreon Tools (When Enabled)

#### `get_patreon_patterns`
Get high-quality patterns from your subscriptions
```typescript
{
  topic: "animation",
  minQuality: 70,
  requireCode: true
}
```

#### `setup_patreon`
Start Patreon setup process

## 🎯 Why This Approach?

### ✅ Works Immediately
- Free sources available instantly
- No setup required to start learning
- High-quality curated content

### ✅ Optional Premium
- Patreon is a powerful add-on, not a requirement
- Get more value from subscriptions you already have
- One-time 5-minute setup

### ✅ Future-Proof
- Easy to add more sources
- Plugin architecture
- No vendor lock-in

### ✅ Quality First
- Intelligent relevance scoring
- Code detection
- Topic categorization
- Expert curation

## 🔒 Privacy & Security

### Free Sources
- Public RSS feeds
- No authentication needed
- No data stored

### Patreon
- OAuth 2.0 (secure)
- Tokens stored in system keychain
- Only accesses YOUR subscriptions
- Content cached locally
- Nothing uploaded to cloud

## 🛠️ Development

### Setup

```bash
git clone https://github.com/efremidze/swift-mcp.git
cd swift-mcp
npm install
npm run build
```

### Project Structure

```
swift-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── config/
│   │   └── sources.ts        # Source management
│   ├── sources/
│   │   ├── free/             # Free sources
│   │   │   ├── sundell.ts
│   │   │   ├── vanderlee.ts
│   │   │   ├── kavsoft.ts
│   │   │   └── pointfree.ts
│   │   └── premium/          # Premium sources
│   │       ├── patreon.ts
│   │       └── github-sponsors.ts
│   └── tools/                # MCP tool handlers
└── docs/                     # Documentation
```

### Adding a New Source

1. Create source file in `src/sources/free/` or `src/sources/premium/`
2. Implement source interface
3. Add to `AVAILABLE_SOURCES` in `src/config/sources.ts`
4. Update MCP tools in `src/index.ts`

## 📊 Quality Metrics

All patterns include:
- **Relevance Score** (0-100) - How relevant to iOS development
- **Has Code** - Boolean indicator
- **Topics** - Automatic categorization
- **Source** - Attribution to original author

## 🤝 Contributing

Contributions welcome! Areas we'd love help with:

- [ ] YouTube API integration for Kavsoft
- [ ] GitHub Sponsors support
- [ ] More free source integrations
- [ ] Improved relevance scoring
- [ ] Better code extraction
- [ ] Documentation improvements

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📝 License

MIT License - See [LICENSE](LICENSE)

## 🙏 Acknowledgments

This project brings together content from:
- [John Sundell](https://www.swiftbysundell.com/) - Swift by Sundell
- [Antoine van der Lee](https://www.avanderlee.com/) - iOS development tips
- [Kavsoft](https://www.youtube.com/@Kavsoft) - SwiftUI tutorials
- [Point-Free](https://www.pointfree.co/) - Functional Swift

All content is properly attributed with links to original sources.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/efremidze/swift-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/efremidze/swift-mcp/discussions)
- **Documentation**: [Full Docs](https://github.com/efremidze/swift-mcp/tree/main/docs)

## 🗺️ Roadmap

### v1.0 (Current)
- ✅ Swift by Sundell integration
- ✅ Antoine van der Lee integration
- ✅ Patreon OAuth support
- ✅ Quality filtering
- ✅ Code detection

### v1.1 (Next)
- [ ] Kavsoft YouTube integration
- [ ] Point-Free OSS integration
- [ ] Improved code extraction
- [ ] Better caching

### v2.0 (Future)
- [ ] GitHub Sponsors
- [ ] Gumroad integration
- [ ] Local AI embeddings
- [ ] Semantic search

---

**Built with ❤️ by the iOS community, for the iOS community**

*Standing on the shoulders of giants: John Sundell, Antoine van der Lee, Kavsoft, Point-Free, and many more*