{"id":40444867,"url":"https://github.com/efremidze/swift-patterns-mcp","last_synced_at":"2026-03-05T07:03:41.277Z","repository":{"id":332668023,"uuid":"1132658106","full_name":"efremidze/swift-patterns-mcp","owner":"efremidze","description":"An MCP server providing curated Swift and SwiftUI best practices from leading iOS sources.","archived":false,"fork":false,"pushed_at":"2026-02-19T22:01:26.000Z","size":1471,"stargazers_count":5,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-20T01:54:15.285Z","etag":null,"topics":["claude-code","ios","mcp","mcp-server","model-context-protocol","patreon","swift","swiftui"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/efremidze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"efremidze","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-01-12T09:17:18.000Z","updated_at":"2026-02-19T22:01:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"f8a6c4df-dbae-4e4e-9b62-9b9a502f8713","html_url":"https://github.com/efremidze/swift-patterns-mcp","commit_stats":null,"previous_names":["efremidze/swift-mcp","efremidze/swift-patterns-mcp"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/efremidze/swift-patterns-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efremidze%2Fswift-patterns-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efremidze%2Fswift-patterns-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efremidze%2Fswift-patterns-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efremidze%2Fswift-patterns-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/efremidze","download_url":"https://codeload.github.com/efremidze/swift-patterns-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/efremidze%2Fswift-patterns-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29872804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T21:05:00.265Z","status":"ssl_error","status_checked_at":"2026-02-26T20:57:13.669Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","ios","mcp","mcp-server","model-context-protocol","patreon","swift","swiftui"],"created_at":"2026-01-20T16:56:40.810Z","updated_at":"2026-02-26T21:19:47.627Z","avatar_url":"https://github.com/efremidze.png","language":"TypeScript","funding_links":["https://github.com/sponsors/efremidze"],"categories":["📦 Other"],"sub_categories":[],"readme":"# swift-patterns-mcp\n\n[![MCP Badge](https://lobehub.com/badge/mcp/efremidze-swift-patterns-mcp)](https://lobehub.com/mcp/efremidze-swift-patterns-mcp)\n\nAn MCP server providing curated Swift and SwiftUI best practices from leading iOS developers — with intelligent search, persistent memory, and optional premium integrations.\n\n## Want an Agent Skill?\n\nIf you want a **lightweight, portable Swift/SwiftUI best-practices package** without runtime tooling, check out:\n\n**[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.\n\n**Key difference:**\n- **swift-patterns-skill** = Static guidance (portable, no runtime)\n- **swift-patterns-mcp** = Dynamic tooling (search, retrieval, premium features)\n\n**Note:** This repo is an MCP server only. It does **not** ship an Agent Skill (`SKILL.md`) or skill references.\n\n## What does this MCP provide?\n\n**swift-patterns-mcp** delivers runtime tools for accessing Swift/SwiftUI best practices:\n\n- 🔎 **Search \u0026 retrieval** across curated sources\n- 🧠 **Persistent memory** with cross-session recall\n- 🔄 **Auto-refreshing content** from RSS feeds and GitHub\n- 🎯 **Intelligent filtering** by quality and relevance\n- 🔐 **Premium integrations** (optional Patreon support)\n\n### Ideal for:\n\n- **Active Development**: \"How do I implement pull-to-refresh in SwiftUI?\" answered instantly without leaving your IDE\n- **Architecture Decisions**: Compare MVVM vs. TCA patterns with concrete examples from trusted sources\n- **Staying Current**: Access the latest patterns and best practices as they're published by leading iOS developers\n- **Team Standards**: Build a searchable reference of approved patterns for your organization\n- **AI-Powered Workflows**: Enable agents to query \"Show me Sundell's approach to dependency injection\" with consistent, quality responses\n\n## 🌟 Features\n\n- 🎓 **Expert Knowledge Base**: Patterns from Swift by Sundell, Antoine van der Lee, Nil Coalescing, and more\n- 🔍 **Intelligent Search**: Query by topic, pattern, or specific iOS concept\n- 💾 **Persistent Memory**: Cross-session recall with Memvid storage\n- 🧠 **Semantic Search**: Optional AI-powered fallback for better conceptual matches\n- 📚 **Multiple Sources**: Aggregates knowledge from trusted educators\n- 🔄 **Auto-Updates**: Content refreshes automatically from RSS feeds\n- ⚡ **Fast Performance**: Efficient caching and indexed search\n\n## Content Sources\n\n### Free Sources\n\nThese sources are publicly available but benefit from MCP's fetching, caching, and search capabilities:\n\n| Source | Content Type | Updates |\n|--------|--------------|---------|\n| **Swift by Sundell** | Articles, patterns, best practices | Weekly |\n| **SwiftLee** | Tutorials, tips, deep dives | Weekly |\n| **Nil Coalescing** | SwiftUI patterns, Swift tips | Weekly |\n| **Point-Free** | Open-source libraries, patterns | On release |\n\n### Premium Sources\n\nPremium content requires OAuth authentication and active subscriptions:\n\n| Source | What You Get | Authentication |\n|--------|--------------|-------|\n| **Patreon** | Premium content from supported creators | OAuth 2.0 |\n\nAccess 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.\n\n## 📋 Prerequisites\n\n- **Node.js** 18.0.0 or higher\n- **MCP-Compatible AI Assistant**: Claude Desktop, Cursor, Windsurf, VS Code with Copilot, or Claude Code\n\n## 🚀 Quick Start\n\n### Run Setup\n\n```bash\nnpx -y swift-patterns-mcp@latest\n```\n\nIn an interactive terminal, this opens the setup wizard.  \nWhen launched by an MCP client (non-interactive stdio), it runs as the MCP server automatically.\n\n### Interactive Setup Wizard\n\n```bash\nnpx -y swift-patterns-mcp@latest setup\n```\n\nIf installed globally, you can also run:\n\n```bash\nswift-patterns-mcp setup\n```\n\nThe wizard helps you choose:\n- Config scope (local project vs global)\n- MCP client (Cursor, Claude Code, Windsurf, VS Code)\n- Optional Patreon setup prompt\n\n### Non-interactive Setup (CI/Scripts)\n\n```bash\n# Cursor\nnpx -y swift-patterns-mcp@latest setup --cursor --global\nnpx -y swift-patterns-mcp@latest setup --cursor --local\n\n# Claude Code\nnpx -y swift-patterns-mcp@latest setup --claude --global\n\n# Windsurf\nnpx -y swift-patterns-mcp@latest setup --windsurf --global\n\n# VS Code\nnpx -y swift-patterns-mcp@latest setup --vscode --local\n\n# All clients\nnpx -y swift-patterns-mcp@latest setup --all --global\n```\n\nUse `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.  \nUse `--cursor`, `--claude`, `--windsurf`, `--vscode`, or `--all` to skip the client prompt.\n\n### Configure Your AI Assistant\n\n#### Cursor\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=swift-patterns\u0026config=eyJjb21tYW5kIjoibnB4IC15IHN3aWZ0LXBhdHRlcm5zLW1jcEBsYXRlc3QifQ%3D%3D)\n\nOr manually add to **Cursor Settings** → **Tools** → **MCP Servers**:\n\n`.cursor/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"swift-patterns\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"swift-patterns-mcp@latest\"]\n    }\n  }\n}\n```\n\nAlternatively, add to `~/.cursor/mcp.json`. See [Cursor documentation](https://docs.cursor.com) for details.\n\n#### Claude Code\n\nRun in your terminal:\n\n```bash\nclaude mcp add swift-patterns -- npx -y swift-patterns-mcp@latest\n```\n\nOr manually add to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"swift-patterns\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"swift-patterns-mcp@latest\"]\n    }\n  }\n}\n```\n\nRestart Claude Code and run `/mcp` to verify. See [Claude Code MCP documentation](https://docs.claude.ai/claude-code) for details.\n\n#### Windsurf\n\nAdd to `.windsurf/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"swift-patterns\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"swift-patterns-mcp@latest\"]\n    }\n  }\n}\n```\n\nRestart Windsurf to activate. See [Windsurf MCP documentation](https://docs.windsurf.com) for details.\n\n#### VS Code\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"swift-patterns\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"swift-patterns-mcp@latest\"]\n      }\n    }\n  }\n}\n```\n\nOpen `.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.\n\n### Test It Out\n\nTry these queries:\n\n```\n\"Show me SwiftUI animation patterns\"\n\"What does Sundell say about testing?\"\n\"Explain navigation patterns in SwiftUI\"\n```\n\n## 🔧 Configuration\n\nConfiguration is automatically created at `~/.swift-patterns-mcp/config.json`:\n\n```json\n{\n  \"sources\": {\n    \"sundell\": { \"enabled\": true },\n    \"vanderlee\": { \"enabled\": true },\n    \"nilcoalescing\": { \"enabled\": true },\n    \"pointfree\": { \"enabled\": true },\n    \"patreon\": { \"enabled\": false, \"configured\": false }\n  },\n  \"prefetchSources\": true,\n  \"semanticRecall\": {\n    \"enabled\": false,\n    \"minLexicalScore\": 0.35,\n    \"minRelevanceScore\": 70\n  },\n  \"memvid\": {\n    \"enabled\": true,\n    \"autoStore\": true,\n    \"useEmbeddings\": false,\n    \"embeddingModel\": \"bge-small\"\n  }\n}\n```\n\nNote: `configured` only applies to premium sources. Free sources are treated as configured by default.\n\n### Persistent Memory with Memvid\n\nMemvid 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.\n\n**Features:**\n- 💾 **Persistent Storage**: Patterns stored in `~/.swift-patterns-mcp/swift-patterns-memory.mv2`\n- 🔁 **Cross-Session Recall**: Find patterns from previous searches after server restart\n- 🧠 **Semantic Search**: Optional embedding-based similarity search\n- 🚀 **Automatic Storage**: Patterns stored during searches\n- ⚡ **Fast Retrieval**: Built-in BM25 + optional vector search\n\n**Configuration:**\n\n```json\n{\n  \"memvid\": {\n    \"enabled\": true,              // Enable Memvid persistent memory\n    \"autoStore\": true,            // Automatically store patterns during searches\n    \"useEmbeddings\": false,       // Use semantic embeddings (requires model download)\n    \"embeddingModel\": \"bge-small\" // Options: \"bge-small\", \"openai-small\"\n  }\n}\n```\n\n**When to enable:**\n- You want patterns to persist across server restarts\n- You frequently search for similar topics\n- You need cross-session semantic memory\n\n**Note:** Memvid complements MiniSearch (fast in-session search) and semantic recall (in-session fallback). All three work together:\n1. **MiniSearch**: Fast lexical search within current session\n2. **Semantic recall**: Activates for poor lexical results (in-session)\n3. **Memvid**: Cross-session persistent memory and recall\n\n### Semantic Recall (Optional AI Enhancement)\n\nSemantic 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.\n\n**Features:**\n- 🧠 Automatically activates when keyword search scores are low\n- 🎯 Uses sentence transformers to understand meaning beyond keywords\n- 📊 Quality filtering to index only high-relevance patterns\n- ⚡ Efficient embedding caching\n\n**Configuration:**\n\n```json\n{\n  \"semanticRecall\": {\n    \"enabled\": false,              // Enable semantic recall\n    \"minLexicalScore\": 0.35,       // Activate when keyword search \u003c 0.35\n    \"minRelevanceScore\": 70        // Only index patterns with score \u003e= 70\n  }\n}\n```\n\n**When to enable:**\n- Your queries use conceptual terms that don't match exact keywords\n- You want more intelligent, context-aware search results\n- You're okay with slightly slower first-time searches (embeddings need to compute)\n\n**Note:** Requires downloading a ~50MB transformer model on first use. Embeddings are cached for performance.\n\n### Environment Variables (Optional)\n\n#### Patreon\n\nAll three variables are required for Patreon content fetching:\n\n| Variable | Description |\n|----------|-------------|\n| `PATREON_CLIENT_ID` | OAuth client ID from your Patreon app |\n| `PATREON_CLIENT_SECRET` | OAuth client secret from your Patreon app |\n| `YOUTUBE_API_KEY` | Enables searching YouTube videos from Patreon creators. [Get API key](https://console.cloud.google.com/apis/credentials) |\n\nAdd to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"swift-patterns\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"swift-patterns-mcp@latest\"],\n      \"env\": {\n        \"PATREON_CLIENT_ID\": \"your_client_id\",\n        \"PATREON_CLIENT_SECRET\": \"your_client_secret\",\n        \"YOUTUBE_API_KEY\": \"your_youtube_api_key\"\n      }\n    }\n  }\n}\n```\n\n## 💡 Usage Examples\n\n### Basic Queries\n\n```\n\"How can I use lazy var in @Observable classes?\"\n\"Show me modern SwiftUI animation best practices using symbolEffect (with button + state examples)\"\n\"Explain common SwiftUI navigation patterns (NavigationStack, NavigationPath, enum routing) and when to use each\"\n```\n\n### Advanced Queries\n\n```\n\"Build a coordinator-style architecture for SwiftUI: MVVM + dependency injection + type-safe routing\"\n\"Give me a clean infinite scrolling implementation: pagination, dedupe, cancellation, and loading states\"\n\"Explain how @Observable improves SwiftUI performance vs ObservableObject, then refactor my view model to @Observable\"\n```\n\n### With Patreon Integration\n\n```\n\"Build a SwiftUI parallax + sticky header screen like a profile page (include reusable component version)\"\n\"Show me how to build a photo editor flow: PhotosPicker -\u003e crop -\u003e filters -\u003e export/share\"\n\"Give me 5 advanced SwiftUI micro-interactions (toasts, sheets, draggable cards, haptics) with production-ready code\"\n```\n\n## 🔐 Premium Integration (Optional)\n\n### Patreon Setup\n\nAccess premium content from iOS creators you support:\n\n```bash\nswift-patterns-mcp patreon setup\n```\n\nFollow the interactive wizard to:\n1. Verify environment variables are configured\n2. Complete OAuth authentication\n3. Fetch and verify content from your subscriptions\n\n📖 **Detailed Guide**: [Patreon Setup Documentation](docs/PATREON_SETUP.md)\n\n#### Requirements\n\n- Active Patreon account with at least one iOS creator subscription\n- Patreon Creator account (free - no need to launch a creator page)\n- 10 minutes for one-time OAuth setup\n\n#### Why Creator Account?\n\nPatreon 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.\n\n#### What You Get\n\n- ✅ Access to premium tutorials and patterns from creators you support\n- ✅ Automatic extraction of code from downloadable content\n- ✅ Quality filtering and advanced search\n- ✅ Multi-creator support\n- ✅ Private, secure authentication\n\n## ⚙️ Commands\n\n```bash\n# List all content sources and status\nswift-patterns-mcp sources\n\n# Interactive onboarding/configuration wizard\nswift-patterns-mcp setup\n\n# Patreon integration\nswift-patterns-mcp patreon setup     # Connect your Patreon account\nswift-patterns-mcp patreon status    # Check connection status\nswift-patterns-mcp patreon reset     # Clear authentication data\n```\n\n## 🗃️ How It Works\n\n```mermaid\ngraph LR\n    A[AI Assistant] --\u003e B[swift-patterns-mcp Server]\n    B --\u003e C[Free Sources]\n    B --\u003e D[Premium Sources]\n    C --\u003e E[Swift by Sundell RSS]\n    C --\u003e F[Antoine van der Lee RSS]\n    C --\u003e G[Nil Coalescing RSS]\n    C --\u003e H[Point-Free GitHub]\n    D --\u003e I[Patreon API]\n```\n\n1. **Query**: Receives a query through the MCP protocol\n2. **Processing**: Searches enabled sources based on the query\n3. **Content Retrieval**: Fetches and parses content from RSS feeds, APIs, and cached data\n4. **Quality Filtering**: Applies configurable quality thresholds\n5. **Response**: Returns formatted, relevant patterns and examples\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**Node version incompatible**\n```bash\nnode --version  # Should be \u003e= 18.0.0\n```\n\n**Sources not returning results**\n```bash\nswift-patterns-mcp sources\nls ~/.swift-patterns-mcp/config.json\n```\n\n### Patreon Integration Issues\n\n**OAuth redirect not working**\n- Ensure redirect URI is exactly: `http://localhost:3000/patreon/callback`\n- Check no other process is using port 3000\n- Verify OAuth credentials are correctly set\n\n**No premium content showing**\n- Confirm you have active Patreon subscriptions to iOS creators\n- Check status: `swift-patterns-mcp patreon status`\n- Re-authenticate: `swift-patterns-mcp patreon setup`\n\n## 🗺️ Roadmap\n\n### Current (v1.x)\n- [x] Core MCP server\n- [x] Swift by Sundell RSS\n- [x] Antoine van der Lee RSS\n- [x] Nil Coalescing RSS\n- [x] Patreon OAuth\n- [x] Point-Free GitHub\n- [ ] Advanced filtering\n\n### Future (v2.x)\n- [ ] Additional premium sources\n- [ ] More free sources\n- [ ] Code validation\n\n## 🤝 Contributing\n\nWe welcome contributions! See our [contributing guidelines](CONTRIBUTING.md).\n\n## 📄 License\n\nMIT License - Copyright (c) 2026 Lasha Efremidze\n\n## 🙏 Credits\n\n**Created by** [Lasha Efremidze](https://github.com/efremidze)\n\n**Content Sources**\n- [John Sundell](https://swiftbysundell.com) - Swift by Sundell\n- [Antoine van der Lee](https://www.avanderlee.com) - SwiftLee\n- [Nil Coalescing](https://nilcoalescing.com) - SwiftUI patterns and Swift tips\n- [Point-Free](https://www.pointfree.co) - Advanced Swift education\n\n**Built with** [Model Context Protocol](https://modelcontextprotocol.io)\n\n**Made with ❤️ for the Swift community**\n\n[⭐ 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)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fefremidze%2Fswift-patterns-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fefremidze%2Fswift-patterns-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fefremidze%2Fswift-patterns-mcp/lists"}