TL;DR: I open‑sourced a small Model Context Protocol (MCP) server that plugs coding agents into authoritative Swift knowledge and best practices. It now includes TSPL & API Guidelines search, Apple DocC search, Swift Evolution lookup, SwiftLint, swift‑format / SwiftFormat, a heuristic API guideline checker, and a new hybrid search across Apple docs, HIG, and curated Cocoa patterns. Repo: https://github.com/gzaal/swift-mcp-server

Software agents are great at scaffolding code fast — but without the canonical Swift docs and style rules, answers drift. swift-mcp-server exposes those sources as callable tools so agents can cite accurately and ship code that passes lint and format checks.

What’s new (Sept 2025)

  • Apple DocC search (apple_docs_search) with filters for frameworks, kinds, topics.
  • Symbol resolver (swift_symbol_lookup) that understands selectors and aliases (e.g., performKeyEquivalent:).
  • Curated Cocoa patterns (cocoa_patterns_search) for keyboard, focus, windows/sheets, menu shortcuts.
  • HIG snapshots (hig_search) searchable offline.
  • Hybrid search (search_hybrid) that unifies Apple docs + HIG + patterns and returns facets to drill down.
  • Offline indexes and cache built by swift_update_sync (TSPL, Swift Evolution, HIG, Apple DocC sample).
  • Docker images: a lean base and a full image including swift‑format, SwiftFormat, and SwiftLint.

Why this exists

I wanted precise answers from TSPL and Swift API Design Guidelines, quick checks of Swift Evolution proposals, and one‑command access to SwiftLint and formatters during reviews — all exposed as MCP tools my agent can call with citations.

What it does

  • swift_docs_search — Searches TSPL and Swift API Design Guidelines; returns ranked links and snippets.
  • apple_docs_search — Searches local Apple DocC/docsets (AppKit, SwiftUI, Foundation, …) with filters.
  • swift_evolution_lookup — Finds proposals by SE-#### or keywords and surfaces status when available.
  • swift_symbol_lookup — Resolves a symbol or Obj‑C selector to likely Apple documentation hits.
  • cocoa_patterns_search — Queries a curated set of Cocoa patterns (keyboard, focus, windows/sheets, menus).
  • hig_search — Queries local HIG snapshots for platform guidance.
  • search_hybrid — Unified search across Apple docs + HIG + patterns with facets.
  • swift_lint_run — Runs SwiftLint and returns violations as JSON (great for PR annotations).
  • swift_format_apply — Formats with swift‑format (preferred) or SwiftFormat; supports check and write modes.
  • swift_guidelines_check — Heuristics to flag naming and polish issues.
  • swift_update_sync — Mirrors swift‑evolution and swift‑book; caches guidelines/HIG; seeds Apple DocC; builds indexes.

All tools are stdio‑based, return structured JSON, and use snake_case names to satisfy model tool‑name constraints. In practice, agents can plan, code, verify details, and clean up code before opening a PR.

Quick start (macOS)

Prereqs: Node 18+. Optional Swift tools via Homebrew:

brew install swift-format swiftformat swiftlint

Install & run:

git clone https://github.com/gzaal/swift-mcp-server
cd swift-mcp-server
npm install
npm run build
node dist/server.js

Seed caches and indexes (recommended):

node dist/tools/update.js

Try it with MCP Inspector:

npx @modelcontextprotocol/inspector node ./dist/server.js

Use with your agent

Codex (CLI) ~/.codex/config.toml:

[mcp_servers.swift]
command = "node"
args = ["/ABSOLUTE/PATH/swift-mcp-server/dist/server.js"]
env = { PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" }

Claude Desktop claude_desktop_config.json (optional):

{
  "mcpServers": {
    "swift": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/swift-mcp-server/dist/server.js"]
    }
  }
}

Examples

Apple DocC search:

// tool: apple_docs_search
{
  "query": "NSWindow",
  "frameworks": ["AppKit"],
  "limit": 5
}

Symbol lookup:

// tool: swift_symbol_lookup
{
  "symbolOrSelector": "performKeyEquivalent:"
}

Hybrid search with facets:

// tool: search_hybrid
{
  "query": "NSWindow",
  "sources": ["apple", "hig", "pattern"],
  "frameworks": ["AppKit"],
  "limit": 5
}

Lint and format:

// tool: swift_lint_run
{ "path": "Sources", "strict": true }

// tool: swift_format_apply
{
  "code": "struct A{}",
  "swiftVersion": "6.1",
  "assumeFilepath": "Sources/A.swift"
}

Architecture & Docker

  • TypeScript on Node using the official MCP SDK over stdio.
  • Offline‑friendly cache in .cache/ for mirrors and indexes (MiniSearch for Apple docs).
  • Curated content under content/ (patterns and symbol aliases).
  • Prefers swift-format; falls back to SwiftFormat where needed.
  • macOS CI smoke tests; weekly refresh keeps caches/indexes fresh.
  • Docker base and full images (full includes SwiftLint, swift‑format, SwiftFormat).

Roadmap

  • Expand offline Apple coverage by indexing full DocC bundles / Dash docsets.
  • Richer guideline rules (Bool-return naming, argument label clarity, acronym casing).
  • Symbol‑graph‑based API diffs for source‑break detection.
  • GitHub Action to annotate PRs with lint/format and guideline findings.

If you use Swift with agents, star the repo, file issues, or open a PR — especially with must‑have rules or evolution topics your team checks often.