swift-skeleton

swift-skeleton provides an MCP server that exposes a skeleton of your Swift (and other language) codebases to large language models. It focuses on declarations and structure rather than full implementations, allowing agents to reason about types, methods, inheritance, and file locations before delving into source files. The MCP server exposes two primary tools: get_skeleton and query_symbols. Use get_skeleton to fetch a project-wide or file-scoped skeleton that includes type declarations, properties, method signatures, and line-numbered file paths. Use query_symbols to search for symbols by name across the project, returning hits with context to help the agent locate relevant definitions quickly. The server is designed to work with Claude Code, Codex, or other agents that can leverage the skeleton to guide exploration and coding tasks.

Prerequisites:

• A Swift toolchain (Swift 6.2+ is required by swift-skeleton).
• Xcode or macOS environment with the Swift toolchain installed.
• Mint (optional but recommended for installation).
• Access to the MCP server runtime (the skltn CLI) installed or available in PATH.

Installation steps:

1. Install Mint (if not already installed):

brew install mint

2. Install swift-skeleton via Mint (recommended):

mint install 1amageek/swift-skeleton

3. Build from source (alternative):

git clone https://github.com/1amageek/swift-skeleton.git
cd swift-skeleton
swift build -c release

4. Verify the CLI is available and supports MCP service:

skltn mcp

5. Create an MCP config in your project root at .mcp.json

{
  "mcpServers": {
    "skltn": {
      "command": "skltn",
      "args": ["mcp"]
    }
  }
}

6. Run the MCP server (if needed, in daemon mode or as a one-off per invocation as your environment requires).

Notes and tips:

• The server focuses on skeletons (types, methods, and file locations) rather than full file contents, enabling faster reasoning for LLMs.
• Ensure the targeted project is Swift-enabled and that dependencies (Tree-sitter parsers) are accessible to the claws of the agent; the skeletons are language-agnostic to some extent but the Swift parser is central.
• If using Sidecar or Embedded modes, you may choose either in-process usage or an out-of-process service depending on your workflow.
• The MCP endpoints exposed by skltn include index.open, index.get_skeleton, and index.query, accessed via standard JSON-RPC over stdin/stdout when using the daemon or MCP server mode.
• For multi-language projects, you can inject additional SkeletonParser implementations to cover Kotlin, TypeScript, Go, Zig, Rust, C++, Python, and Java as supported by swift-skeleton.
• If you encounter path or permission issues on macOS, ensure CLI tools have appropriate execute permissions and that your terminal session has sufficient rights to read project files.