Swift Semantic Summary

An MCP (Model Context Protocol) server that provides semantic summaries of Swift source files using SwiftSyntax.

Given a Swift file, it parses the AST and returns a structured JSON summary of all declarations: imports, classes, structs, enums, protocols, functions, extensions, and their members.

Architecture

┌─────────────┐     stdio      ┌──────────────────┐     exec      ┌────────────────────┐
│  MCP Client  │ ◄───────────► │  TypeScript Server │ ───────────► │  Swift CLI (binary) │
│ (e.g. Claude)│               │  (server/)         │              │  (swift/)            │
└─────────────┘               └──────────────────┘              └────────────────────┘
                                                                         │
                                                                    SwiftSyntax
                                                                    AST Parser

1. Swift CLI (swift/): A SwiftPM package that uses SwiftSyntax to parse .swift files and output structured JSON summaries.
2. TypeScript MCP Server (server/): An MCP server that wraps the Swift CLI, exposing swift_semantic_summary(path) as an MCP tool over stdio.

Prerequisites

• Swift 5.9+ (tested with Swift 6.3)
• Node.js 18+
• macOS or Linux

Installation

1. Build the Swift binary

cd swift
swift build -c release

2. Install and build the server

cd server
npm install
npm run build

3. Configure Claude Code

Ask Claude to create a .mcp.json at your project root pointing to the built server:

"Add swift-semantic-summary to .mcp.json using the server at /absolute/path/to/server/dist/index.js"

Restart your Claude Code session. You'll be prompted to approve the new MCP server on first load.

4. (Optional) Add a slash command

Ask Claude to create a slash command for you:

"Create a /summarize-swift slash command that calls swift_semantic_summary on the given file and explains the results"

Claude will create .claude/commands/summarize-swift.md. Then you can run:

/summarize-swift path/to/File.swift

Usage

MCP Tool

The server exposes a single tool:

swift_semantic_summary

Parameter	Type	Required	Description
path	string	Yes	Absolute path to a Swift source file

Slash Command

/summarize-swift examples/SimpleClass.swift

Claude will call the MCP tool and explain the semantic structure of the file.

CLI (Direct)

./swift/.build/release/semantic-summary path/to/file.swift

Example

For a file containing:

import Foundation

public class UserManager {
    private var users: [String] = []

    public func addUser(_ name: String) -> Bool {
        users.append(name)
        return true
    }
}

The tool returns:

{
  "declarations" : [
    {
      "accessLevel" : "public",
      "kind" : "class",
      "members" : [
        {
          "accessLevel" : "private",
          "isStatic" : false,
          "kind" : "property",
          "name" : "users",
          "type" : "[String]"
        },
        {
          "accessLevel" : "public",
          "isStatic" : false,
          "kind" : "method",
          "name" : "addUser",
          "parameters" : [
            {
              "name" : "name",
              "type" : "String"
            }
          ],
          "returnType" : "Bool"
        }
      ],
      "name" : "UserManager"
    }
  ],
  "file" : "path/to/file.swift",
  "imports" : [
    "Foundation"
  ]
}

Project Structure

.
├── .mcp.json                       # MCP server config for Claude Code
├── .claude/commands/
│   └── summarize-swift.md          # /summarize-swift slash command
├── swift/                          # SwiftPM package
│   ├── Package.swift
│   ├── Sources/
│   │   ├── SemanticSummaryLib/     # Core library
│   │   │   ├── Models.swift        # Data models (Codable)
│   │   │   └── SemanticAnalyzer.swift
│   │   └── SemanticSummaryCLI/     # CLI entry point
│   │       └── main.swift
│   └── Tests/
│       └── SemanticSummaryTests/
│           └── AnalyzerTests.swift
├── server/                         # TypeScript MCP server
│   ├── package.json
│   ├── tsconfig.json
│   └── src/
│       └── index.ts
├── tests/                          # Integration tests
│   ├── manifest.test.ts
│   └── integration.test.ts
├── examples/                       # Sample Swift files
│   ├── SimpleClass.swift
│   └── ProtocolExample.swift
├── .github/workflows/ci.yml       # CI pipeline
├── manifest.json                   # MCP manifest
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md

Supported Declarations

Declaration Type	Extracted Info
import	Module path
class	Name, access level, inheritance, generics, members
struct	Name, access level, inheritance, generics, members
enum	Name, access level, inheritance, generics, cases, members
protocol	Name, access level, inheritance, associated types, members
extension	Extended type, conformances, members
func	Name, access level, generics, parameters, return type
typealias	Name, access level, aliased type

Member Types

Member Type	Extracted Info
property	Name, type, access level, static
method	Name, parameters, return type, access level, static
initializer	Parameters, access level
case	Name, associated value types
associatedtype	Name, constraint

Development

Running tests

# Swift unit tests
cd swift && swift test

# TypeScript / integration tests
cd tests && npm install && npm test

License

MIT — see LICENSE.