swift-mcp

Um servidor MCP que traz as melhores práticas dos principais desenvolvedores iOS diretamente para seu assistente de IA.

Documentação

swift-patterns-mcp

Release

Um servidor MCP que fornece práticas recomendadas de Swift e SwiftUI, selecionadas por desenvolvedores iOS líderes — com busca inteligente, memória persistente e integrações premium opcionais.

Quer uma Skill de Agente?

Se você deseja um pacote leve e portátil de práticas recomendadas de Swift/SwiftUI sem ferramentas em tempo de execução, confira:

swift-patterns-skill: Projetado como uma Skill de Agente portátil, focada em padrões Swift/SwiftUI, orientação de arquitetura e estruturas de tomada de decisão.

Diferença principal:

swift-patterns-skill = Orientação estática (portátil, sem tempo de execução)
swift-patterns-mcp = Ferramentas dinâmicas (busca, recuperação, recursos premium)

Nota: Este repositório é apenas um servidor MCP. Ele não inclui uma Skill de Agente (SKILL.md) nem referências de skill.

O que este MCP oferece?

swift-patterns-mcp fornece ferramentas em tempo de execução para acessar práticas recomendadas de Swift/SwiftUI:

🔎 Busca e recuperação em fontes selecionadas
🧠 Memória persistente com recall entre sessões
🔄 Conteúdo com atualização automática a partir de feeds RSS e GitHub
🎯 Filtragem inteligente por qualidade e relevância
🔐 Integrações premium (suporte opcional ao Patreon)

Ideal para:

Desenvolvimento Ativo: "Como implemento pull-to-refresh em SwiftUI?" respondido instantaneamente sem sair da sua IDE
Decisões de Arquitetura: Compare padrões MVVM vs. TCA com exemplos concretos de fontes confiáveis
Manter-se Atualizado: Acesse os padrões e práticas mais recentes conforme são publicados por desenvolvedores iOS líderes
Padrões de Equipe: Construa uma referência pesquisável de padrões aprovados para sua organização
Fluxos de Trabalho com IA: Permita que agentes consultem "Mostre-me a abordagem do Sundell para injeção de dependência" com respostas consistentes e de qualidade

🌟 Recursos

🎓 Base de Conhecimento Especializada: Padrões de Swift by Sundell, Antoine van der Lee, Nil Coalescing e mais
🔍 Busca Inteligente: Consulte por tópico, padrão ou conceito específico de iOS
💾 Memória Persistente: Recall entre sessões com armazenamento Memvid
🧠 Busca Semântica: Fallback opcional com IA para melhores correspondências conceituais
📚 Múltiplas Fontes: Agrega conhecimento de educadores confiáveis
🔄 Atualizações Automáticas: O conteúdo é atualizado automaticamente a partir de feeds RSS
⚡ Desempenho Rápido: Cache eficiente e busca indexada

Fontes de Conteúdo

Fontes Gratuitas

Estas fontes são publicamente acessíveis, mas se beneficiam dos recursos de busca, cache e recuperação do MCP:

Fonte	Tipo de Conteúdo	Atualizações
Swift by Sundell	Artigos, padrões, práticas recomendadas	Semanal
SwiftLee	Tutoriais, dicas, análises aprofundadas	Semanal
Nil Coalescing	Padrões SwiftUI, dicas de Swift	Semanal
Point-Free	Bibliotecas de código aberto, padrões	No lançamento

Fontes Premium

O conteúdo premium requer autenticação OAuth e assinaturas ativas:

Fonte	O que Você Obtém	Autenticação
Patreon	Conteúdo premium de criadores apoiados	OAuth 2.0

Acesse conteúdo exclusivo dos principais educadores iOS: Kavsoft, SwiftUI Codes, sucodee e muitos outros. Obtenha tutoriais, exemplos de código e orientação especializada diretamente dos criadores que você apoia.

📋 Pré-requisitos

Node.js 18.0.0 ou superior
Assistente de IA Compatível com MCP: Claude Desktop, Cursor, Windsurf, VS Code com Copilot ou Claude Code

🚀 Início Rápido

Executar Configuração

npx -y swift-patterns-mcp@latest

Em um terminal interativo, isso abre o assistente de configuração.
Quando iniciado por um cliente MCP (stdio não interativo), ele executa automaticamente como servidor MCP.

Assistente de Configuração Interativo

npx -y swift-patterns-mcp@latest setup

Se instalado globalmente, você também pode executar:

swift-patterns-mcp setup

O assistente ajuda você a escolher:

Escopo da configuração (projeto local vs. global)
Cliente MCP (Cursor, Claude Code, Windsurf, VS Code)
Prompt opcional de configuração do Patreon

Configuração Não Interativa (CI/Scripts)

# 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) ou --local (-l) para pular o prompt de localização.
Use --cursor, --claude, --windsurf, --vscode ou --all para pular o prompt de cliente.

Configure Seu Assistente de IA

Cursor

Ou adicione manualmente em Configurações do Cursor → Ferramentas → Servidores MCP:

.cursor/mcp.json:

{
  "mcpServers": {
    "swift-patterns": {
      "command": "npx",
      "args": ["-y", "swift-patterns-mcp@latest"]
    }
  }
}

Alternativamente, adicione a ~/.cursor/mcp.json. Consulte a documentação do Cursor para detalhes.

Claude Code

Execute no seu terminal:

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

Ou adicione manualmente a .mcp.json:

{
  "mcpServers": {
    "swift-patterns": {
      "command": "npx",
      "args": ["-y", "swift-patterns-mcp@latest"]
    }
  }
}

Reinicie o Claude Code e execute /mcp para verificar. Consulte a documentação MCP do Claude Code para detalhes.

Windsurf

Adicione a .windsurf/mcp.json:

{
  "mcpServers": {
    "swift-patterns": {
      "command": "npx",
      "args": ["-y", "swift-patterns-mcp@latest"]
    }
  }
}

Reinicie o Windsurf para ativar. Consulte a documentação MCP do Windsurf para detalhes.

VS Code

Adicione a .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "swift-patterns": {
        "command": "npx",
        "args": ["-y", "swift-patterns-mcp@latest"]
      }
    }
  }
}

Abra .vscode/mcp.json e clique em Iniciar ao lado do servidor swift-patterns. Consulte a documentação MCP do VS Code para detalhes.

Teste

Experimente estas consultas:

"Show me SwiftUI animation patterns"
"What does Sundell say about testing?"
"Explain navigation patterns in SwiftUI"

🔧 Configuração

A configuração é criada automaticamente em ~/.swift-patterns-mcp/config.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"
  }
}

Nota: configured se aplica apenas a fontes premium. Fontes gratuitas são tratadas como configuradas por padrão.

Memória Persistente com Memvid

O Memvid fornece memória semântica persistente que melhora o recall entre sessões. Diferente do cache em memória, o Memvid armazena padrões em um banco de dados de arquivo único que persiste entre reinicializações do servidor.

Recursos:

💾 Armazenamento Persistente: Padrões armazenados em ~/.swift-patterns-mcp/swift-patterns-memory.mv2
🔁 Recall Entre Sessões: Encontre padrões de buscas anteriores após reiniciar o servidor
🧠 Busca Semântica: Busca opcional por similaridade baseada em embeddings
🚀 Armazenamento Automático: Padrões armazenados durante buscas
⚡ Recuperação Rápida: BM25 integrado + busca vetorial opcional

Configuração:

{
  "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"
  }
}

Quando ativar:

Você deseja que os padrões persistam entre reinicializações do servidor
Você busca frequentemente tópicos semelhantes
Você precisa de memória semântica entre sessões

Nota: O Memvid complementa o MiniSearch (busca rápida na sessão) e o recall semântico (fallback na sessão). Os três funcionam juntos:

MiniSearch: Busca lexical rápida na sessão atual
Recall semântico: Ativa para resultados lexicais ruins (na sessão)
Memvid: Memória persistente e recall entre sessões

Recall Semântico (Aprimoramento Opcional de IA)

O recall semântico fornece busca semântica com IA como fallback quando a busca por palavras-chave retorna resultados ruins. Ele usa embeddings de transformers para entender a intenção da consulta e encontrar padrões conceitualmente semelhantes.

Recursos:

🧠 Ativa automaticamente quando as pontuações da busca por palavras-chave são baixas
🎯 Usa sentence transformers para entender o significado além das palavras-chave
📊 Filtragem de qualidade para indexar apenas padrões de alta relevância
⚡ Cache eficiente de embeddings

Configuração:

{
  "semanticRecall": {
    "enabled": false,              // Enable semantic recall
    "minLexicalScore": 0.35,       // Activate when keyword search < 0.35
    "minRelevanceScore": 70        // Only index patterns with score >= 70
  }
}

Quando ativar:

Suas consultas usam termos conceituais que não correspondem a palavras-chave exatas
Você deseja resultados de busca mais inteligentes e sensíveis ao contexto
Você aceita buscas iniciais um pouco mais lentas (os embeddings precisam ser calculados)

Nota: Requer o download de um modelo transformer de ~50MB no primeiro uso. Os embeddings são armazenados em cache para desempenho.

Variáveis de Ambiente (Opcional)

Patreon

Todas as três variáveis são necessárias para a busca de conteúdo do Patreon:

Variável	Descrição
`PATREON_CLIENT_ID`	ID do cliente OAuth do seu aplicativo Patreon
`PATREON_CLIENT_SECRET`	Segredo do cliente OAuth do seu aplicativo Patreon
`YOUTUBE_API_KEY`	Habilita a busca de vídeos do YouTube de criadores do Patreon. Obtenha a chave da API

Adicione à configuração do seu cliente MCP:

{
  "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"
      }
    }
  }
}

💡 Exemplos de Uso

Consultas Básicas

"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"

Consultas Avançadas

"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"

Com Integração Patreon

"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"

🔐 Integração Premium (Opcional)

Configuração do Patreon

Acesse conteúdo premium de criadores iOS que você apoia:

swift-patterns-mcp patreon setup

Siga o assistente interativo para:

Verificar se as variáveis de ambiente estão configuradas
Concluir a autenticação OAuth
Buscar e verificar o conteúdo das suas assinaturas

📖 Guia Detalhado: Documentação de Configuração do Patreon

Requisitos

Conta Patreon ativa com pelo menos uma assinatura de criador iOS
Conta de Criador no Patreon (gratuita - não é necessário lançar uma página de criador)
10 minutos para a configuração única do OAuth

Por que uma Conta de Criador?

O Patreon exige que aplicativos OAuth sejam registrados por criadores. Você não precisa lançar uma página de criador nem se tornar um criador ativo - basta se registrar como um para criar um aplicativo OAuth para uso pessoal.

O que Você Obtém

✅ Acesso a tutoriais e padrões premium dos criadores que você apoia
✅ Extração automática de código de conteúdo para download
✅ Filtragem de qualidade e busca avançada
✅ Suporte a múltiplos criadores
✅ Autenticação privada e segura

⚙️ Comandos

# 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

🗃️ Como Funciona

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]

Consulta: Recebe uma consulta através do protocolo MCP
Processamento: Busca em fontes habilitadas com base na consulta
Recuperação de Conteúdo: Busca e analisa conteúdo de feeds RSS, APIs e dados em cache
Filtragem de Qualidade: Aplica limites de qualidade configuráveis
Resposta: Retorna padrões e exemplos formatados e relevantes

🔧 Solução de Problemas

Problemas Comuns

Versão do Node incompatível

node --version  # Should be >= 18.0.0

Fontes não retornando resultados

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

Problemas de Integração com Patreon

Redirecionamento OAuth não funcionando

Certifique-se de que o URI de redirecionamento seja exatamente: http://localhost:3000/patreon/callback
Verifique se nenhum outro processo está usando a porta 3000
Verifique se as credenciais OAuth estão configuradas corretamente

Nenhum conteúdo premium aparecendo

Confirme que você tem assinaturas ativas do Patreon para criadores iOS
Verifique o status: swift-patterns-mcp patreon status
Reautentique: swift-patterns-mcp patreon setup

🗺️ Roteiro

Atual (v1.x)

Futuro (v2.x)

Fontes premium adicionais
Mais fontes gratuitas
Validação de código

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas diretrizes de contribuição.

📄 Licença

🙏 Créditos

Criado por Lasha Efremidze

Fontes de Conteúdo

John Sundell - Swift by Sundell
Antoine van der Lee - SwiftLee
Nil Coalescing - Padrões SwiftUI e dicas de Swift
Point-Free - Educação avançada em Swift

Construído com Model Context Protocol

Feito com ❤️ para a comunidade Swift

⭐ Dê uma estrela neste repositório • 🐛 Reportar Bug • ✨ Solicitar Recurso