Periphery Code Audit

Periphery MCP 服务

一个封装 Periphery 工具的 Model Context Protocol (MCP) 服务，可让 AI 助手对 iOS/macOS 项目执行 Swift 代码审计并检测未使用的代码。

功能

• 7 个 MCP 工具，提供全面的代码分析
• CLI 集成——使用 Periphery CLI，稳定可靠且支持灵活选择版本
• JSON 输出——结构化、可解析的结果，非常适合 AI 解读
• 灵活扫描——支持 Xcode 项目和 Swift Packages
• 高级选项——全面控制 Periphery 扫描配置

快速开始

使用 Homebrew（推荐）：

# 1. Install Periphery
brew install peripheryapp/periphery/periphery

# 2. Install Periphery MCP Server
brew tap zyntx-lab/tap
brew install periphery-mcp-server

# 3. Configure Claude Desktop
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
# Add:
#   "periphery": {
#     "command": "/opt/homebrew/bin/periphery-mcp-server"
#   }

# 4. Restart Claude Desktop (Cmd+Q then reopen)

# 5. Test it
# In Claude Desktop: "Check if Periphery is installed"

从源代码构建：

# 1. Install Periphery
brew install peripheryapp/periphery/periphery

# 2. Clone and build this server
git clone https://github.com/zyntx-lab/periphery-mcp-server.git
cd periphery-mcp-server
swift build -c release

# 3. Install to system path
sudo cp .build/release/periphery-mcp-server /usr/local/bin/
sudo chmod +x /usr/local/bin/periphery-mcp-server

# 4. Configure Claude Desktop
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json
# Add:
#   "periphery": {
#     "command": "/usr/local/bin/periphery-mcp-server"
#   }

# 5. Restart Claude Desktop (Cmd+Q then reopen)

# 6. Test it
# In Claude Desktop: "Check if Periphery is installed"

前提条件

• macOS 13.0 或更高版本
• Swift 6.0 或更高版本
• 已安装 Periphery

安装 Periphery

brew install peripheryapp/periphery/periphery

也可以从 Periphery releases 下载。

安装

选项 1：Homebrew（推荐）

# Add the tap
brew tap zyntx-lab/tap

# Install the server
brew install periphery-mcp-server

# Verify installation
which periphery-mcp-server
# Should output: /opt/homebrew/bin/periphery-mcp-server

选项 2：从 GitHub Releases 下载

从 Releases 下载最新的二进制文件：

# Download and install
curl -L https://github.com/zyntx-lab/periphery-mcp-server/releases/download/v1.0.0/periphery-mcp-server \
  -o /usr/local/bin/periphery-mcp-server
chmod +x /usr/local/bin/periphery-mcp-server

# Verify installation
which periphery-mcp-server
# Should output: /usr/local/bin/periphery-mcp-server

选项 3：从源代码构建

# Clone the repository
git clone https://github.com/zyntx-lab/periphery-mcp-server.git
cd periphery-mcp-server

# Build release version
swift build -c release

# Install to system path (requires password)
sudo cp .build/release/periphery-mcp-server /usr/local/bin/
sudo chmod +x /usr/local/bin/periphery-mcp-server

# Verify installation
which periphery-mcp-server
# Should output: /usr/local/bin/periphery-mcp-server

选项 4：从 MCP Registry 安装

此服务也可通过 MCP Registry 获取。使用兼容 MCP 的客户端直接安装。

配置

Claude Desktop

步骤 1：找到配置文件

配置文件位于：~/Library/Application Support/Claude/claude_desktop_config.json

步骤 2：编辑配置

如果通过 Homebrew 安装：

{
  "mcpServers": {
    "periphery": {
      "command": "/opt/homebrew/bin/periphery-mcp-server"
    }
  }
}

如果安装到 /usr/local/bin：

{
  "mcpServers": {
    "periphery": {
      "command": "/usr/local/bin/periphery-mcp-server"
    }
  }
}

如果直接使用构建目录：

{
  "mcpServers": {
    "periphery": {
      "command": "/FULL/PATH/TO/periphery-mcp-server/.build/release/periphery-mcp-server"
    }
  }
}

如果已配置其他 MCP 服务：

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/path/to/xcode-mcp-server/dist/index.js"]
    },
    "periphery": {
      "command": "/usr/local/bin/periphery-mcp-server"
    }
  }
}

步骤 3：重启 Claude Desktop

重要提示： 必须完全退出并重启 Claude Desktop，修改才会生效。

1. 退出 Claude Desktop：按 Cmd+Q 或选择 Claude Desktop → Quit
2. 等待几秒钟
3. 重新打开 Claude Desktop

步骤 4：验证是否正常运行

在 Claude Desktop 中开启新对话并尝试：

"Check if Periphery is installed"

如果配置正确，Claude 将使用 check_periphery_installed 工具并返回安装状态。

使用 MCP Inspector 测试

配置 Claude Desktop 之前，可以使用 MCP Inspector 测试此服务：

# Install MCP Inspector (if not already installed)
npm install -g @modelcontextprotocol/inspector

# Test your server
npx @modelcontextprotocol/inspector /usr/local/bin/periphery-mcp-server

# Or if using build directory
npx @modelcontextprotocol/inspector /path/to/periphery-mcp-server/.build/release/periphery-mcp-server

Inspector 会在浏览器中打开，你可以在那里交互式测试所有工具。

其他编辑器

VS Code

添加到 .vscode/mcp.json：

{
  "mcpServers": {
    "periphery": {
      "type": "stdio",
      "command": "/usr/local/bin/periphery-mcp-server"
    }
  }
}

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "periphery": {
      "type": "stdio",
      "command": "/usr/local/bin/periphery-mcp-server"
    }
  }
}

可用工具

1. check_periphery_installed

验证 Periphery CLI 是否已安装且可访问。

参数： 无

响应示例：

{
  "installed": true,
  "path": "/usr/local/bin/periphery",
  "message": "Periphery is installed and ready"
}

2. get_periphery_version

获取已安装的 Periphery 版本。

参数： 无

响应示例：

{
  "version": "2.18.0",
  "raw_output": "2.18.0"
}

3. scan_project

对项目运行基本的 Periphery 扫描。

参数：

• project_path（必需）：.xcodeproj 或 Package.swift 的路径
• schemes（可选）：要扫描的构建 scheme（仅适用于 Xcode）
• targets（可选）：要分析的特定 target
• format（可选）：输出格式：json、xcode、csv、checkstyle（默认值：json）

响应示例：

{
  "success": true,
  "results": [
    {
      "kind": "class",
      "name": "UnusedClass",
      "modifiers": ["public"],
      "location": "Sources/MyApp/UnusedClass.swift:10:7"
    }
  ],
  "summary": {
    "total_unused": 5,
    "by_kind": {"class": 2, "function": 3}
  }
}

4. scan_with_config

使用 YAML 配置文件运行 Periphery 扫描。

参数：

• config_path（必需）：.periphery.yml 配置文件的路径

5. analyze_unused_imports

专门检测未使用的导入。

参数：

• project_path（必需）：.xcodeproj 或 Package.swift 的路径
• schemes（可选）：要扫描的构建 scheme
• targets（可选）：要分析的特定 target

6. find_redundant_public

识别可设为内部的公开声明。

参数：

• project_path（必需）：.xcodeproj 或 Package.swift 的路径
• schemes（可选）：要扫描的构建方案
• targets（可选）：要分析的特定目标

7. scan_with_options

使用自定义 Periphery 标志进行高级扫描。

参数：

• project_path（必需）：.xcodeproj 或 Package.swift 的路径
• schemes（可选）：要扫描的构建方案
• targets（可选）：要分析的特定目标
• format（可选）：输出格式
• retain_public（可选）：保留所有公开声明
• retain_objc_accessible（可选）：保留 @objc 声明
• disable_unused_import_analysis（可选）：禁用未使用导入分析
• index_store_path（可选）：自定义索引存储位置
• verbose（可选）：启用详细输出

使用示例

使用 Claude Desktop

配置完成后，你可以与 Claude 自然地讨论你的代码：

检查安装：

You: "Check if Periphery is installed"

Claude: [Uses check_periphery_installed]
"Yes, Periphery is installed at /usr/local/bin/periphery
Version: 2.18.0"

扫描项目：

You: "Scan my iOS project at ~/Projects/MyApp/MyApp.xcodeproj for unused code"

Claude: [Uses scan_project]
"I found 15 unused declarations in your project:

Classes (5):
- UnusedViewController at MyApp/UnusedViewController.swift:10
- OldDataManager at MyApp/Models/OldDataManager.swift:25
...

Functions (8):
- helperFunction at Utils/Helpers.swift:42
...

Imports (2):
- UIKit in DataModel.swift:1
..."

查找冗余公开声明：

You: "Check which public declarations could be made internal in ~/Projects/MyFramework"

Claude: [Uses find_redundant_public]
"Found 12 public declarations that are only used internally and could be made internal:
- public class InternalHelper (only used within the framework)
- public func formatDate() (only called from within the module)
..."

分析未使用的导入：

You: "Find unused imports in my Swift package"

Claude: [Uses analyze_unused_imports]
"Found 8 unused imports that can be safely removed:
- Foundation in Models/User.swift (not using any Foundation APIs)
- Combine in ViewModels/ProfileViewModel.swift (Combine is imported but not used)
..."

使用自定义配置

在项目中创建 .periphery.yml：

project: MyApp.xcodeproj
schemes:
  - MyApp
targets:
  - MyApp
  - MyAppKit
format: json
retain_public: false
retain_objc_accessible: true
verbose: false

然后使用 scan_with_config：

You: "Scan my project using the custom config"

故障排除

Claude Desktop 中未显示服务

**症状：**配置后，Claude 无法识别 Periphery 工具

解决方案：

1. 验证配置文件语法：

   # Check for JSON syntax errors
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
   

2. 检查二进制文件路径是否正确：

   # Test that the binary exists and runs
   /usr/local/bin/periphery-mcp-server
   # Or your custom path
   /path/to/.build/release/periphery-mcp-server
   

3. 完全重启 Claude Desktop：

   • 按 Cmd+Q 退出（不要只关闭窗口）
   • 等待 5 秒
   • 重新打开 Claude Desktop
   • 开始新对话（旧对话无法看到新服务）

4. 检查 Claude Desktop 日志：

   # View logs for errors
   tail -f ~/Library/Logs/Claude/mcp*.log
   

未找到 Periphery

如果看到“未安装 Periphery”的提示：

1. 安装 Periphery：brew install peripheryapp/periphery/periphery
2. 验证安装：which periphery
3. 重启 Claude Desktop/VS Code/Cursor
4. 再次尝试 check_periphery_installed 工具

MCP Inspector 连接错误

如果 Inspector 无法连接到服务：

1. 验证服务是否正在运行：

   # Server should wait for input, not exit immediately
   /usr/local/bin/periphery-mcp-server
   # Press Ctrl+C to exit
   

2. 检查是否有错误：

   # Run with verbose output
   /usr/local/bin/periphery-mcp-server 2>&1 | tee server.log
   

3. 使用绝对路径：

   npx @modelcontextprotocol/inspector $(which periphery-mcp-server)
   

扫描超时

默认超时时间为 5 分钟。对于大型项目：

1. 使用 scan_with_config 和精简配置
2. 扫描特定目标，而不是整个项目
3. 使用 --index-store-path 复用构建产物
4. 先在 Xcode 中构建项目以生成索引

无结果或扫描结果为空

Periphery 需要已编译且带有索引存储的项目：

1. 先在 Xcode 中构建项目（Cmd+B）
2. 确保方案已共享：
   • Xcode → Product → Scheme → Manage Schemes
   • 勾选方案对应的“Shared”复选框
3. 验证项目路径：

   # For Xcode projects
   ls /path/to/YourProject.xcodeproj
   
   # For Swift Packages
   ls /path/to/Package.swift
   

4. 检查 Periphery 是否可以访问项目：

   # Test Periphery directly
   periphery scan --project /path/to/YourProject.xcodeproj --schemes YourScheme
   

权限被拒绝

如果运行服务时看到“权限被拒绝”的提示：

# Make the binary executable
chmod +x /usr/local/bin/periphery-mcp-server

# Or for build directory
chmod +x .build/release/periphery-mcp-server

架构

为确保最大稳定性，此服务采用 CLI 方式，而不是将 Periphery 作为库导入：

• ✅ CLI 接口是 Periphery 的公开 API 契约
• ✅ 能够经受 Periphery 内部重构
• ✅ 用户可以独立更新 Periphery
• ✅ 依赖管理更简单

贡献

欢迎贡献！请：

1. Fork 此代码库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

相关项目

• Periphery - 底层代码分析工具
• Model Context Protocol - 协议规范
• MCP Swift SDK - MCP 官方 Swift SDK
• MCP Registry - 官方 MCP 服务注册表
• MCP Community Servers - 社区 MCP 服务集合

分发渠道

此服务可通过多个渠道获取：

• MCP Registry：registry.modelcontextprotocol.io
• Homebrew Tap：github.com/zyntx-lab/homebrew-tap
• GitHub Releases：github.com/zyntx-lab/periphery-mcp-server/releases
• 社区服务：列于 modelcontextprotocol/servers

支持

• 问题反馈：GitHub Issues
• Periphery 文档：Periphery 指南
• MCP 文档：MCP 规范