Xcode Janitor MCP

🧹 Xcode资产管理器MCP

MCP（模型上下文协议）服务器，用于清理Xcode项目中未使用的资产。使用交互式HTML报告查找和删除未使用的图像、颜色和数据资产。

✨ 特性

• 🔍 快速资产索引 -扫描全部 .xcassets 在Xcode项目中
• 🚀 平行分析 -在10-15秒内处理10000多个Swift文件
• 📊 交互式HTML报告 -可排序和可过滤的报告
• 💾 代币高效 -将结果保存到文件中，而不是使用令牌（对于一个有10k个swift文件的项目，使用看门人的令牌约为50个，而使用标准claude代码/副本的令牌为25000个以上）
• 🔧 SwiftGen支持 -自动检测SwiftGen管理的资产
• ⚡ 智能过滤 -自动跳过Pod、.build、DeriveData

📋 需求

• macOS 13.0+
• Swift 6.0+
• Claude Code（或Claude CLI）、VS Code扩展或其他MCP兼容IDE。

🚀 安装

自制（推荐）

brew install thepearl/tap/xcode-janitor-mcp

就是这样！这 xcode-janitor-mcp 二进制文件将在您的PATH中可用。 你现在要做的就是 配置MCP客户端

从源代码构建

如果您更喜欢从源代码构建：

git clone https://github.com/thepearl/xcode-janitor-mcp.git
cd xcode-janitor-mcp
swift build -c release

二进制文件将位于 .build/release/XcodeJanitorMCP

配置MCP客户端

安装后，将MCP客户端配置为使用Xcode Janitor。

一般配置

大多数MCP客户端（Cursor、VS Code、Windsurf、Claude Desktop等）都使用这种JSON格式。添加到您的客户 mcpServers 配置：

如果通过Homebrew安装：

{
  "xcode-janitor": {
    "command": "xcode-janitor-mcp"
  }
}

如果从源代码构建：

{
  "xcode-janitor": {
    "command": "/absolute/path/to/xcode-janitor-mcp/.build/release/XcodeJanitorMCP"
  }
}

💡 How to get absolute path for source build

cd xcode-janitor-mcp && pwd
# Example output: /Users/you/projects/xcode-janitor-mcp
# Use: /Users/you/projects/xcode-janitor-mcp/.build/release/XcodeJanitorMCP

特定客户端安装说明

克劳德代码CLI

如果通过Homebrew安装：

claude mcp add xcode-janitor xcode-janitor-mcp

或者使用Homebrew的完整路径：

claude mcp add xcode-janitor "$(brew --prefix)/bin/xcode-janitor-mcp"

如果从源代码构建：

claude mcp add xcode-janitor /absolute/path/to/xcode-janitor-mcp/.build/release/XcodeJanitorMCP

验证它是否已连接：

claude mcp list

您应该看到：

xcode-janitor: xcode-janitor-mcp - ✓ Connected

克劳德桌面（MacOS）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

如果通过Homebrew安装：

{
  "mcpServers": {
    "xcode-janitor": {
      "command": "xcode-janitor-mcp"
    }
  }
}

如果从源代码构建：

{
  "mcpServers": {
    "xcode-janitor": {
      "command": "/absolute/path/to/xcode-janitor-mcp/.build/release/XcodeJanitorMCP"
    }
  }
}

更改后重新启动Claude Desktop。

VS代码/光标/风帆

1. 打开设置（Cmd+，）
2. 搜索“MCP”或“Claude:MCP”
3. 添加服务器配置：

如果通过Homebrew安装：

{
  "xcode-janitor": {
    "command": "xcode-janitor-mcp"
  }
}

如果从源代码构建：

{
  "xcode-janitor": {
    "command": "/absolute/path/to/xcode-janitor-mcp/.build/release/XcodeJanitorMCP"
  }
}

1. 重新启动扩展程序或重新加载窗口

🎯 用法

🎯 何时使用Xcode Janitor

使用Xcode Janitor：

• ✅ 在iOS/macOS Xcode项目中查找未使用的资产
• ✅ 分析 .xcassets 资产目录（图像集、颜色集、数据集）
• ✅ 扫描Swift代码以查找资产引用（UIImage、NSImage、Color）
• ✅ 检测SwiftGen枚举使用情况并管理生成的资产
• ✅ 清理遗留资产以减小应用程序大小
• ✅ 质量控制：检查是否缺少@1x/@2x/@3x变体

为什么Xcode Janitor是正确的工具：

• ⚡ 更快 比一般代码搜索（5-20秒vs 3-10分钟）
• 🎯 专门建造的 用于Xcode资产目录和Swift代码模式
• 💾 代币高效 （约500个令牌，而通用搜索工具为2.5k+）
• 📊 交互式HTML报告 具有排序、过滤和搜索功能
• 🔍 了解SwiftGen -检测生成的枚举使用情况，而不仅仅是字符串
• 🛡️ 安全删除 具有自动备份和模拟运行模式

基本工作流程

1. 导航到您的Xcode项目：

cd ~/your-ios-project

1. 在聊天中提问：

Find unused assets and save to file

1. 打开HTML报告：

open unused_assets_report.html

🔍 常见查询

Xcode Janitor将在您询问时自动激活：

• “查找未使用的iOS图像” 或 “查找未使用的Xcode资源”
• “扫描我的iOS项目以查找未使用的资产”
• “检查资产目录中未使用的文件”
• “查找此项目中未使用的.xccassets”
• “清理未使用的应用程序图标” 或 “删除遗留资产”
• “我的iOS应用程序中没有使用哪些资产？”
• “显示项目中未使用的图像”

可用命令

自然地问：

• “此项目中的索引资产”

- 扫描全部 .xcassets 目录 - 显示总数和明细

• “查找未使用的资产并保存到文件”

- 分析所有Swift文件 - 检查资产使用情况 - 生成JSON+HTML报告 - 违约： unused_assets_report.{json,html}

• “检查SwiftGen状态”

- 检测SwiftGen配置 - 显示托管资产 - 报告SwiftGen的覆盖范围

• “查找使用‘assetName’的位置”

- 显示对特定资产的所有引用 - 列出文件、行号、上下文

• “从项目中删除资产'assetName'”

- 先创建备份 - 安全移除资产 - 报告大小已释放

📊 HTML报告功能

生成的HTML报告包括：

摘要仪表板

• 已扫描的总资产
• 未使用资产计数
• 总大小（MB）
• 节省空间%

交互式表格

• 可排序：单击资产名称或大小进行排序
• 搜索：按资产名称筛选（实时）
• 类型过滤器：图像、颜色、数据
• 目录筛选器：通过 .xcassets 文件

列

• 资产名称 -未使用资产的名称
• 类型 -徽章（图像/颜色/数据）
• 目录 -哪个 .xcassets 文件
• 尺寸 -文件大小（MB）
• 路径 -缩短文件路径

⚡ 演出

对于一个典型的iOS项目：

• 项目规模：在iOS项目上测试，包含8319个Swift文件和2498个资产
• 旧方法：使用标准试剂3-10分钟
• 优化：5-20秒，具体取决于项目的规模。

速度有多快

1. 单程扫描 -读取每个文件一次
2. 并行处理 -使用所有CPU内核
3. 预编译正则表达式 -模式编译一次
4. 智能过滤 -跳过Pod、.build、DerivedData

🔧 SwiftGen支持

如果您的项目使用 SwiftGen:

• 自动检测 swiftgen.yml 配置
• 了解SwiftGen管理的资产及其使用方式
• 防止未使用的报告中出现误报

支持的配置文件：

• swiftgen.yml
• swiftgen.yaml
• .swiftgen.yml

📁 输出文件

JSON报告(unused_assets_report.json)

脚本/自动化的机器可读格式：

{
  "generated_at": "2024-11-20T16:00:00Z",
  "project_path": "/Users/you/project",
  "summary": {
    "total_assets_scanned": 2498,
    "unused_count": 1528,
    "total_size_mb": "245.67"
  },
  "unused_assets": [...]
}

HTML报告(unused_assets_report.html)

交互式web界面：

• 自给自足（无外部依赖）
• 离线工作
• 可排序、可过滤、可搜索
• 移动响应

🛠️ 高级用法

自定义输出路径

Find unused assets and save to ~/Desktop/cleanup_report.json

按图案过滤

Find unused assets matching "Splash*"

获取详细信息

Get info about asset "AppIcon-Prod"

📝 示例会话

cd ~/dev/my-ios-app

# Ask Claude:
> Find unused assets and save to file

# Claude responds:
✓ Scanned 8,319 Swift files
✓ Found 1,528 unused assets
✓ Total size: 245.67 MB
✓ Reports saved to:
  - unused_assets_report.json
  - unused_assets_report.html

# Open report
open unused_assets_report.html

# Review in browser, then delete specific assets
> Delete asset "legacyHomeBg" from the project

# Verify
> Find unused assets again

🤝 发展

项目结构

xcode-janitor-mcp/
├── Package.swift
├── Sources/XcodeJanitorMCP/
│   ├── XcodeJanitorMCP.swift      # Main MCP server
│   ├── Models/
│   │   └── Asset.swift             # Data models
│   ├── Parsers/
│   │   ├── XCAssetsParser.swift   # Parse .xcassets
│   │   ├── SwiftCodeParser.swift  # Parse Swift files
│   │   └── SwiftGenParser.swift   # Parse swiftgen.yml
│   └── Tools/
│       ├── AssetIndexer.swift     # Index assets
│       ├── FastUsageAnalyzer.swift # Find usage (optimized)
│       ├── AssetManager.swift      # Delete assets
│       └── HTMLReportGenerator.swift # Generate HTML

建筑

# Debug build
swift build

# Release build (optimized)
swift build -c release

# Run tests
swift test

🐛 故障排除

MCP服务器无法连接

症状： Claude Code/CLI不显示xcode看门人服务器

解决：

1. 验证构建成功：

   ./verify-installation.sh

1. 检查二进制路径是否为绝对路径：

   realpath .build/release/XcodeJanitorMCP

必须是MCP配置中的绝对路径（不是相对路径 ~/ 路径）

1. 验证它是否可执行：

   chmod +x .build/release/XcodeJanitorMCP

1. 手动测试服务器：

   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | .build/release/XcodeJanitorMCP

应返回一个JSON响应 "result"

1. 重新启动MCP客户端：

- Claude Desktop：退出并重新打开应用程序 - VS代码/光标/风帆：重新加载窗口（Cmd+Shift+P→ “开发人员：重新加载窗口”） - Claude Code CLI：退出并启动新会话

构建错误

症状： swift build 失败

解决：

1. 检查Swift版本：

   swift --version

需要Swift 6.0+，macOS 13+

1. 清理构建工件：

   rm -rf .build
   swift build -c release

1. 更新依赖关系：

   swift package update

性能缓慢

症状： 分析所需的时间比预期的要长

解决：

• ✅ 使用发布版本： swift build -c release （比调试快10倍）
• ✅ 检查项目位置： 网络驱动器速度较慢；使用本地SSD
• ✅ 预计时间：

- 小项目（\<1k文件）：2-5秒 - 中等项目（1k-5k文件）：5-15秒 - 大型项目（5k-15k+文件）：15-60秒

假阳性（标记为未正确使用的资产）

症状： 资产被标记为未使用，但您知道它已被使用

常见原因：

1. 故事板/XIB（尚不支持）

- 未检测到XIB/故事板资产引用 - 解决方法：删除前手动验证

1. 动态加载（字符串插值）

   let name = "icon_\(type)"
   UIImage(named: name)  // Won't be detected

- 解决方法：使用 // janitor:keep icon_* 评论（功能待定）

1. Objective-C文件（尚不支持）

- 仅扫描Swift文件 - 解决方法：搜索 .m 手动文件

1. 外部参照

- 框架/包中使用的资产 - 解决方法：删除前检查

推荐工作流程：

1. 删除前查看HTML报告
2. 使用 dry_run: true 首先模拟删除
3. 提交前检查git diff
4. 创建备份（使用自动 create_backup: true)

假阴性（未检测到未使用的资产）

症状： 您知道某项资产未使用，但它不在报告中

常见原因：

1. SwiftGen管理的资产

- 目前，所有标记为“已使用”的SwiftGen资产 - 检查： Ask Claude to check SwiftGen status

1. 资产名称与代码字符串匹配

   let str = "MyImage"  // Asset "MyImage" marked as used

测试失败

症状： swift test 报告故障

解决：

1. 检查写入权限：

   ls -la /tmp

测试使用 /tmp 用于临时文件

1. 清理测试工件：

   rm -rf .build
   swift test

未生成报告

症状： 未创建HTML/JSON报告

解决：

1. 检查写入权限：

   ls -ld /path/to/your/project

1. 指定绝对路径：

   Ask Claude: Find unused assets and save to ~/Desktop/report.json

1. 检查磁盘空间：

   df -h .

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🙏 致谢

• 内置于 Swift MCP SDK
• 受到对更好的资产清理工具需求的启发
• 在拥有1000多个资产的真实iOS项目上进行了测试

🔗 链接

• 模型上下文协议
• 克劳德代码
• SwiftGen

______________________________________________________________________

由...制作❤️ 面向iOS开发者