swiftlens

SwiftLens is an MCP server that provides semantic-level analysis of Swift code by leveraging SourceKit-LSP. It exposes a suite of tools that let you analyze single files, bulk analyze multiple files, inspect symbol declarations and definitions, and perform code modifications with safe, atomic operations. The server is designed to work with AI agents, enabling them to request code understanding, symbol lookups, refactoring suggestions, and cross-file navigation, all optimized to minimize token usage while preserving semantic accuracy. Use it to build project-wide insights, navigate complex Swift codebases, and perform targeted analyses that drive AI-driven development workflows.

To use SwiftLens, run the MCP server through the configured runtime (uvx in this setup) and invoke its available tools via your AI agent or via the provided tool invocations. Tools include single-file analysis (swift_analyze_file, swift_summarize_file, swift_get_symbols_overview), cross-file analysis (swift_find_symbol_references, swift_get_symbol_definition, swift_get_hover_info), and code modification (swift_replace_symbol_body). If you need to build a project index for cross-file analysis, use swift_build_index, which creates the SourceKit-LSP index store needed for deeper analysis. The real-time dashboard, when enabled, will show tool execution logs and analytics locally at http://localhost:53729.

In an AI-driven workflow, your agent can, for example, request a full symbol overview of a Swift file, then drill down to see where a particular type or function is defined, or ask to replace a function body and return a patch. Use the provided examples as templates to structure prompts for your agent, such as asking to analyze a file for references to a method, or to build a project-wide index before performing cross-file queries.

Prerequisites:

• macOS (required for SourceKit-LSP)
• Python 3.10+
• Xcode installed from the App Store (not just Command Line Tools)

Installation steps:

1. Ensure your environment meets the prerequisites:

   • macOS with Xcode
   • Python 3.10 or newer

2. Install the MCP runtime wrapper (uvx) and the SwiftLens server binary interface:

# Optional: upgrade pip and install uvx (Python-based MCP runtime)
pip install --upgrade pip
pip install uvx

3. Install the SwiftLens MCP server entry point (via uvx or your preferred installer):

# Install the SwiftLens package/entry point (adjust as needed for your setup)
uvx install swiftlens

4. Verify installation and start the MCP server:

uvx swiftlens

5. Connect your MCP client or AI agent to the server using the mcp_config below (server name: swiftlens).

Notes:

• If you need to build a SourceKit-LSP index, run the index-building commands described in the README (swift build with index-store-path).
• The SwiftLens server relies on macOS tooling (SourceKit-LSP) and Xcode; ensure these are properly installed and configured before running.

Troubleshooting:

• If you encounter symbol-not-found or missing index issues, rebuild the index using:

swift build -Xswiftc -index-store-path -Xswiftc .build/index/store

• Confirm Xcode path and that sourcekit-lsp is accessible:

xcode-select -p
xcrun sourcekit-lsp --help

Environment and configuration tips:

• The mcp_config uses uvx as the runtime, with the server name swiftlens. You can adjust the command or arguments if you deploy in a different environment.
• If you plan to run multiple Swift projects, consider setting up dedicated index stores per project to avoid cross-project index contamination.
• The real-time dashboard is labeled as CURRENT NOT WORKING in the README; expectations for deployment dashboards should be managed accordingly.
• Ensure your Swift toolchain and SourceKit-LSP are kept in sync with the Swift version used in your project to minimize symbol resolution issues.
• For production usage, monitor memory usage of the index store and prune or rebuild indices as needed after significant project changes.