Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/efremidze/swift-patterns-mcp

An MCP server providing curated Swift and SwiftUI best practices from leading iOS sources.
https://github.com/efremidze/swift-patterns-mcp

claude-code ios mcp mcp-server model-context-protocol patreon swift swiftui

Last synced: 4 months ago
JSON representation

An MCP server providing curated Swift and SwiftUI best practices from leading iOS sources.

Awesome Lists containing this project

README 

          
# swift-patterns-mcp



[![MCP Badge](https://lobehub.com/badge/mcp/efremidze-swift-patterns-mcp)](https://lobehub.com/mcp/efremidze-swift-patterns-mcp)



An MCP server providing curated Swift and SwiftUI best practices from leading iOS developers — with intelligent search, persistent memory, and optional premium integrations.



## Want an Agent Skill?



If you want a **lightweight, portable Swift/SwiftUI best-practices package** without runtime tooling, check out:



**[swift-patterns-skill](https://github.com/efremidze/swift-patterns-skill)**: Designed as a portable Agent Skill focused on Swift/SwiftUI patterns, architecture guidance, and decision-making frameworks.



**Key difference:**

- **swift-patterns-skill** = Static guidance (portable, no runtime)

- **swift-patterns-mcp** = Dynamic tooling (search, retrieval, premium features)



**Note:** This repo is an MCP server only. It does **not** ship an Agent Skill (`SKILL.md`) or skill references.



## What does this MCP provide?



**swift-patterns-mcp** delivers runtime tools for accessing Swift/SwiftUI best practices:



- 🔎 **Search & retrieval** across curated sources

- 🧠 **Persistent memory** with cross-session recall

- 🔄 **Auto-refreshing content** from RSS feeds and GitHub

- 🎯 **Intelligent filtering** by quality and relevance

- 🔐 **Premium integrations** (optional Patreon support)



### Ideal for:



- **Active Development**: "How do I implement pull-to-refresh in SwiftUI?" answered instantly without leaving your IDE

- **Architecture Decisions**: Compare MVVM vs. TCA patterns with concrete examples from trusted sources

- **Staying Current**: Access the latest patterns and best practices as they're published by leading iOS developers

- **Team Standards**: Build a searchable reference of approved patterns for your organization

- **AI-Powered Workflows**: Enable agents to query "Show me Sundell's approach to dependency injection" with consistent, quality responses



## 🌟 Features



- 🎓 **Expert Knowledge Base**: Patterns from Swift by Sundell, Antoine van der Lee, Nil Coalescing, and more

- 🔍 **Intelligent Search**: Query by topic, pattern, or specific iOS concept

- 💾 **Persistent Memory**: Cross-session recall with Memvid storage

- 🧠 **Semantic Search**: Optional AI-powered fallback for better conceptual matches

- 📚 **Multiple Sources**: Aggregates knowledge from trusted educators

- 🔄 **Auto-Updates**: Content refreshes automatically from RSS feeds

- ⚡ **Fast Performance**: Efficient caching and indexed search



## Content Sources



### Free Sources



These sources are publicly available but benefit from MCP's fetching, caching, and search capabilities:



| Source | Content Type | Updates |

|--------|--------------|---------|

| **Swift by Sundell** | Articles, patterns, best practices | Weekly |

| **SwiftLee** | Tutorials, tips, deep dives | Weekly |

| **Nil Coalescing** | SwiftUI patterns, Swift tips | Weekly |

| **Point-Free** | Open-source libraries, patterns | On release |



### Premium Sources



Premium content requires OAuth authentication and active subscriptions:



| Source | What You Get | Authentication |

|--------|--------------|-------|

| **Patreon** | Premium content from supported creators | OAuth 2.0 |



Access exclusive content from top iOS educators: **Kavsoft**, **SwiftUI Codes**, **sucodee** and many more. Get tutorials, code samples, and expert guidance directly from creators you support.



## 📋 Prerequisites



- **Node.js** 18.0.0 or higher

- **MCP-Compatible AI Assistant**: Claude Desktop, Cursor, Windsurf, VS Code with Copilot, or Claude Code



## 🚀 Quick Start



### Run Setup



```bash

npx -y swift-patterns-mcp@latest

```



In an interactive terminal, this opens the setup wizard.  

When launched by an MCP client (non-interactive stdio), it runs as the MCP server automatically.



### Interactive Setup Wizard



```bash

npx -y swift-patterns-mcp@latest setup

```



If installed globally, you can also run:



```bash

swift-patterns-mcp setup

```



The wizard helps you choose:

- Config scope (local project vs global)

- MCP client (Cursor, Claude Code, Windsurf, VS Code)

- Optional Patreon setup prompt



### Non-interactive Setup (CI/Scripts)



```bash

# Cursor

npx -y swift-patterns-mcp@latest setup --cursor --global

npx -y swift-patterns-mcp@latest setup --cursor --local



# Claude Code

npx -y swift-patterns-mcp@latest setup --claude --global



# Windsurf

npx -y swift-patterns-mcp@latest setup --windsurf --global



# VS Code

npx -y swift-patterns-mcp@latest setup --vscode --local



# All clients

npx -y swift-patterns-mcp@latest setup --all --global

```



Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.  

Use `--cursor`, `--claude`, `--windsurf`, `--vscode`, or `--all` to skip the client prompt.



### Configure Your AI Assistant



#### Cursor



[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=swift-patterns&config=eyJjb21tYW5kIjoibnB4IC15IHN3aWZ0LXBhdHRlcm5zLW1jcEBsYXRlc3QifQ%3D%3D)



Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**:



`.cursor/mcp.json`:

```json

{

  "mcpServers": {

    "swift-patterns": {

      "command": "npx",

      "args": ["-y", "swift-patterns-mcp@latest"]

    }

  }

}

```



Alternatively, add to `~/.cursor/mcp.json`. See [Cursor documentation](https://docs.cursor.com) for details.



#### Claude Code



Run in your terminal:



```bash

claude mcp add swift-patterns -- npx -y swift-patterns-mcp@latest

```



Or manually add to `.mcp.json`:



```json

{

  "mcpServers": {

    "swift-patterns": {

      "command": "npx",

      "args": ["-y", "swift-patterns-mcp@latest"]

    }

  }

}

```



Restart Claude Code and run `/mcp` to verify. See [Claude Code MCP documentation](https://docs.claude.ai/claude-code) for details.



#### Windsurf



Add to `.windsurf/mcp.json`:



```json

{

  "mcpServers": {

    "swift-patterns": {

      "command": "npx",

      "args": ["-y", "swift-patterns-mcp@latest"]

    }

  }

}

```



Restart Windsurf to activate. See [Windsurf MCP documentation](https://docs.windsurf.com) for details.



#### VS Code



Add to `.vscode/mcp.json`:



```json

{

  "mcp": {

    "servers": {

      "swift-patterns": {

        "command": "npx",

        "args": ["-y", "swift-patterns-mcp@latest"]

      }

    }

  }

}

```



Open `.vscode/mcp.json` and click **Start** next to the swift-patterns server. See [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/mcp) for details.



### Test It Out



Try these queries:



```

"Show me SwiftUI animation patterns"

"What does Sundell say about testing?"

"Explain navigation patterns in SwiftUI"

```



## 🔧 Configuration



Configuration is automatically created at `~/.swift-patterns-mcp/config.json`:



```json

{

  "sources": {

    "sundell": { "enabled": true },

    "vanderlee": { "enabled": true },

    "nilcoalescing": { "enabled": true },

    "pointfree": { "enabled": true },

    "patreon": { "enabled": false, "configured": false }

  },

  "prefetchSources": true,

  "semanticRecall": {

    "enabled": false,

    "minLexicalScore": 0.35,

    "minRelevanceScore": 70

  },

  "memvid": {

    "enabled": true,

    "autoStore": true,

    "useEmbeddings": false,

    "embeddingModel": "bge-small"

  }

}

```



Note: `configured` only applies to premium sources. Free sources are treated as configured by default.



### Persistent Memory with Memvid



Memvid provides persistent semantic memory that improves recall across sessions. Unlike in-memory caching, Memvid stores patterns in a single-file database that persists between server restarts.



**Features:**

- 💾 **Persistent Storage**: Patterns stored in `~/.swift-patterns-mcp/swift-patterns-memory.mv2`

- 🔁 **Cross-Session Recall**: Find patterns from previous searches after server restart

- 🧠 **Semantic Search**: Optional embedding-based similarity search

- 🚀 **Automatic Storage**: Patterns stored during searches

- ⚡ **Fast Retrieval**: Built-in BM25 + optional vector search



**Configuration:**



```json

{

  "memvid": {

    "enabled": true,              // Enable Memvid persistent memory

    "autoStore": true,            // Automatically store patterns during searches

    "useEmbeddings": false,       // Use semantic embeddings (requires model download)

    "embeddingModel": "bge-small" // Options: "bge-small", "openai-small"

  }

}

```



**When to enable:**

- You want patterns to persist across server restarts

- You frequently search for similar topics

- You need cross-session semantic memory



**Note:** Memvid complements MiniSearch (fast in-session search) and semantic recall (in-session fallback). All three work together:

1. **MiniSearch**: Fast lexical search within current session

2. **Semantic recall**: Activates for poor lexical results (in-session)

3. **Memvid**: Cross-session persistent memory and recall



### Semantic Recall (Optional AI Enhancement)



Semantic recall provides AI-powered semantic search as a fallback when keyword search returns poor results. It uses transformer embeddings to understand query intent and find conceptually similar patterns.



**Features:**

- 🧠 Automatically activates when keyword search scores are low

- 🎯 Uses sentence transformers to understand meaning beyond keywords

- 📊 Quality filtering to index only high-relevance patterns

- ⚡ Efficient embedding caching



**Configuration:**



```json

{

  "semanticRecall": {

    "enabled": false,              // Enable semantic recall

    "minLexicalScore": 0.35,       // Activate when keyword search < 0.35

    "minRelevanceScore": 70        // Only index patterns with score >= 70

  }

}

```



**When to enable:**

- Your queries use conceptual terms that don't match exact keywords

- You want more intelligent, context-aware search results

- You're okay with slightly slower first-time searches (embeddings need to compute)



**Note:** Requires downloading a ~50MB transformer model on first use. Embeddings are cached for performance.



### Environment Variables (Optional)



#### Patreon



All three variables are required for Patreon content fetching:



| Variable | Description |

|----------|-------------|

| `PATREON_CLIENT_ID` | OAuth client ID from your Patreon app |

| `PATREON_CLIENT_SECRET` | OAuth client secret from your Patreon app |

| `YOUTUBE_API_KEY` | Enables searching YouTube videos from Patreon creators. [Get API key](https://console.cloud.google.com/apis/credentials) |



Add to your MCP client config:



```json

{

  "mcpServers": {

    "swift-patterns": {

      "command": "npx",

      "args": ["-y", "swift-patterns-mcp@latest"],

      "env": {

        "PATREON_CLIENT_ID": "your_client_id",

        "PATREON_CLIENT_SECRET": "your_client_secret",

        "YOUTUBE_API_KEY": "your_youtube_api_key"

      }

    }

  }

}

```



## 💡 Usage Examples



### Basic Queries



```

"How can I use lazy var in @Observable classes?"

"Show me modern SwiftUI animation best practices using symbolEffect (with button + state examples)"

"Explain common SwiftUI navigation patterns (NavigationStack, NavigationPath, enum routing) and when to use each"

```



### Advanced Queries



```

"Build a coordinator-style architecture for SwiftUI: MVVM + dependency injection + type-safe routing"

"Give me a clean infinite scrolling implementation: pagination, dedupe, cancellation, and loading states"

"Explain how @Observable improves SwiftUI performance vs ObservableObject, then refactor my view model to @Observable"

```



### With Patreon Integration



```

"Build a SwiftUI parallax + sticky header screen like a profile page (include reusable component version)"

"Show me how to build a photo editor flow: PhotosPicker -> crop -> filters -> export/share"

"Give me 5 advanced SwiftUI micro-interactions (toasts, sheets, draggable cards, haptics) with production-ready code"

```



## 🔐 Premium Integration (Optional)



### Patreon Setup



Access premium content from iOS creators you support:



```bash

swift-patterns-mcp patreon setup

```



Follow the interactive wizard to:

1. Verify environment variables are configured

2. Complete OAuth authentication

3. Fetch and verify content from your subscriptions



📖 **Detailed Guide**: [Patreon Setup Documentation](docs/PATREON_SETUP.md)



#### Requirements



- Active Patreon account with at least one iOS creator subscription

- Patreon Creator account (free - no need to launch a creator page)

- 10 minutes for one-time OAuth setup



#### Why Creator Account?



Patreon requires OAuth apps to be registered by creators. You don't need to launch a creator page or become an active creator - just register as one to create an OAuth app for personal use.



#### What You Get



- ✅ Access to premium tutorials and patterns from creators you support

- ✅ Automatic extraction of code from downloadable content

- ✅ Quality filtering and advanced search

- ✅ Multi-creator support

- ✅ Private, secure authentication



## ⚙️ Commands



```bash

# List all content sources and status

swift-patterns-mcp sources



# Interactive onboarding/configuration wizard

swift-patterns-mcp setup



# Patreon integration

swift-patterns-mcp patreon setup     # Connect your Patreon account

swift-patterns-mcp patreon status    # Check connection status

swift-patterns-mcp patreon reset     # Clear authentication data

```



## 🗃️ How It Works



```mermaid

graph LR

    A[AI Assistant] --> B[swift-patterns-mcp Server]

    B --> C[Free Sources]

    B --> D[Premium Sources]

    C --> E[Swift by Sundell RSS]

    C --> F[Antoine van der Lee RSS]

    C --> G[Nil Coalescing RSS]

    C --> H[Point-Free GitHub]

    D --> I[Patreon API]

```



1. **Query**: Receives a query through the MCP protocol

2. **Processing**: Searches enabled sources based on the query

3. **Content Retrieval**: Fetches and parses content from RSS feeds, APIs, and cached data

4. **Quality Filtering**: Applies configurable quality thresholds

5. **Response**: Returns formatted, relevant patterns and examples



## 🔧 Troubleshooting



### Common Issues



**Node version incompatible**

```bash

node --version  # Should be >= 18.0.0

```



**Sources not returning results**

```bash

swift-patterns-mcp sources

ls ~/.swift-patterns-mcp/config.json

```



### Patreon Integration Issues



**OAuth redirect not working**

- Ensure redirect URI is exactly: `http://localhost:3000/patreon/callback`

- Check no other process is using port 3000

- Verify OAuth credentials are correctly set



**No premium content showing**

- Confirm you have active Patreon subscriptions to iOS creators

- Check status: `swift-patterns-mcp patreon status`

- Re-authenticate: `swift-patterns-mcp patreon setup`



## 🗺️ Roadmap



### Current (v1.x)

- [x] Core MCP server

- [x] Swift by Sundell RSS

- [x] Antoine van der Lee RSS

- [x] Nil Coalescing RSS

- [x] Patreon OAuth

- [x] Point-Free GitHub

- [ ] Advanced filtering



### Future (v2.x)

- [ ] Additional premium sources

- [ ] More free sources

- [ ] Code validation



## 🤝 Contributing



We welcome contributions! See our [contributing guidelines](CONTRIBUTING.md).



## 📄 License



MIT License - Copyright (c) 2026 Lasha Efremidze



## 🙏 Credits



**Created by** [Lasha Efremidze](https://github.com/efremidze)



**Content Sources**

- [John Sundell](https://swiftbysundell.com) - Swift by Sundell

- [Antoine van der Lee](https://www.avanderlee.com) - SwiftLee

- [Nil Coalescing](https://nilcoalescing.com) - SwiftUI patterns and Swift tips

- [Point-Free](https://www.pointfree.co) - Advanced Swift education



**Built with** [Model Context Protocol](https://modelcontextprotocol.io)



**Made with ❤️ for the Swift community**



[⭐ Star this repo](https://github.com/efremidze/swift-patterns-mcp) • [🐛 Report Bug](https://github.com/efremidze/swift-patterns-mcp/issues) • [✨ Request Feature](https://github.com/efremidze/swift-patterns-mcp/issues)