使用说明

🧹 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代码/光标/风帆

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

如果通过Homebrew安装：

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

如果从源代码构建：

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

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

🎯 用法

🎯 何时使用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 -检测生成的枚举使用情况，而不仅仅是字符串
🛡️ 安全删除 具有自动备份和模拟运行模式

基本工作流程

导航到您的Xcode项目：

cd ~/your-ios-project

在聊天中提问：

Find unused assets and save to file

打开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秒，具体取决于项目的规模。

速度有多快

单程扫描 -读取每个文件一次
并行处理 -使用所有CPU内核
预编译正则表达式 -模式编译一次
智能过滤 -跳过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看门人服务器

解决：

验证构建成功：
```
./verify-installation.sh
```
检查二进制路径是否为绝对路径：
```
realpath .build/release/XcodeJanitorMCP
```
必须是MCP配置中的绝对路径（不是相对路径 ~/ 路径）

验证它是否可执行：

chmod +x .build/release/XcodeJanitorMCP

手动测试服务器：

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"

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

构建错误

症状： swift build 失败

解决：

检查Swift版本：
```
swift --version
```
需要Swift 6.0+，macOS 13+
清理构建工件：
```
rm -rf .build
swift build -c release
```
更新依赖关系：
```
swift package update
```

性能缓慢

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

解决：

✅ 使用发布版本： swift build -c release （比调试快10倍）
✅ 检查项目位置： 网络驱动器速度较慢；使用本地SSD
✅ 预计时间：
- 小项目（<1k文件）：2-5秒
- 中等项目（1k-5k文件）：5-15秒
- 大型项目（5k-15k+文件）：15-60秒

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

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

常见原因：

故事板/XIB（尚不支持）
- 未检测到XIB/故事板资产引用
- 解决方法：删除前手动验证
动态加载（字符串插值）
```
let name = "icon_\(type)"
UIImage(named: name)  // Won't be detected
```
- 解决方法：使用 // janitor:keep icon_* 评论（功能待定）
Objective-C文件（尚不支持）
- 仅扫描Swift文件
- 解决方法：搜索 .m 手动文件
外部参照
- 框架/包中使用的资产
- 解决方法：删除前检查

推荐工作流程：

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

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

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

常见原因：

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

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

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

测试失败

症状： swift test 报告故障

解决：

检查写入权限：
```
ls -la /tmp
```
测试使用 /tmp 用于临时文件
清理测试工件：
```
rm -rf .build
swift test
```

未生成报告

症状： 未创建HTML/JSON报告

解决：

检查写入权限：
```
ls -ld /path/to/your/project
```

指定绝对路径：

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

检查磁盘空间：
```
df -h .
```

📄 许可证

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

🙏 致谢

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

🔗 链接

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

使用说明

🧹 Xcode资产管理器MCP

✨ 特性

📋 需求

🚀 安装

自制（推荐）

从源代码构建

配置MCP客户端

一般配置

特定客户端安装说明

克劳德代码CLI

克劳德桌面（MacOS）

VS代码/光标/风帆

🎯 用法

🎯 何时使用Xcode Janitor

基本工作流程

🔍 常见查询

可用命令

📊 HTML报告功能

摘要仪表板

交互式表格

列

⚡ 演出

速度有多快

🔧 SwiftGen支持

📁 输出文件

JSON报告(unused_assets_report.json)

HTML报告(unused_assets_report.html)

🛠️ 高级用法

自定义输出路径

按图案过滤

获取详细信息

📝 示例会话

🤝 发展

项目结构

建筑

🐛 故障排除

MCP服务器无法连接

构建错误

性能缓慢

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

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

测试失败

未生成报告

📄 许可证

🙏 致谢

🔗 链接

相关 MCP

iOS模拟器交互服务器

Primavera P6 XER文件解析服务器

Kubernetes资源管理工具

iOS项目构建服务

Magic-API开发MCP服务

MCP服务器创建工具

JSON报告(`unused_assets_report.json`)

HTML报告(`unused_assets_report.html`)