Periphery MCP Server

🚀 Periphery MCP Server

Periphery MCP Server 是一个 模型上下文协议（Model Context Protocol，MCP） 服务器，它封装了 Periphery 工具，使 AI 助手能够对 Swift 代码进行审核，并检测 iOS/macOS 项目中的未使用代码。

✨ 主要特性

• 7 种 MCP 工具：用于全面的代码分析。
• CLI 集成：使用 Periphery CLI 以确保稳定性和版本灵活性。
• JSON 输出：结构化、可解析的结果，非常适合 AI 解读。
• 灵活扫描：支持 Xcode 项目和 Swift 包。
• 高级选项：可完全控制 Periphery 扫描配置。

🚀 快速开始

使用 Homebrew（推荐）

# 1. 安装 Periphery
brew install peripheryapp/periphery/periphery

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

# 3. 配置 Claude Desktop
# 编辑：~/Library/Application Support/Claude/claude_desktop_config.json
# 添加：
#   "periphery": {
#     "command": "/opt/homebrew/bin/periphery-mcp-server"
#   }

# 4. 重启 Claude Desktop（Cmd+Q 然后重新打开）

# 5. 测试
# 在 Claude Desktop 中输入："Check if Periphery is installed"

从源码安装

# 1. 安装 Periphery
brew install peripheryapp/periphery/periphery

# 2. 克隆并构建此服务器
git clone https://github.com/zyntx-lab/periphery-mcp-server.git
cd periphery-mcp-server
swift build -c release

# 3. 安装到系统路径
sudo cp .build/release/periphery-mcp-server /usr/local/bin/
sudo chmod +x /usr/local/bin/periphery-mcp-server

# 4. 配置 Claude Desktop
# 编辑：~/Library/Application Support/Claude/claude_desktop_config.json
# 添加：
#   "periphery": {
#     "command": "/usr/local/bin/periphery-mcp-server"
#   }

# 5. 重启 Claude Desktop（Cmd+Q 然后重新打开）

# 6. 测试
# 在 Claude Desktop 中输入："Check if Periphery is installed"

📦 安装指南

选项 1：使用 Homebrew（推荐）

# 添加 tap
brew tap zyntx-lab/tap

# 安装服务器
brew install periphery-mcp-server

# 验证安装
which periphery-mcp-server
# 应输出：/opt/homebrew/bin/periphery-mcp-server

选项 2：从 GitHub Releases 下载

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

# 下载并安装
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

# 验证安装
which periphery-mcp-server
# 应输出：/usr/local/bin/periphery-mcp-server

选项 3：从源码构建

# 克隆仓库
git clone https://github.com/zyntx-lab/periphery-mcp-server.git
cd periphery-mcp-server

# 构建发布版本
swift build -c release

# 安装到系统路径（需要输入密码）
sudo cp .build/release/periphery-mcp-server /usr/local/bin/
sudo chmod +x /usr/local/bin/periphery-mcp-server

# 验证安装
which periphery-mcp-server
# 应输出：/usr/local/bin/periphery-mcp-server

选项 4：从 MCP 注册表安装

该服务器也可在 MCP 注册表 上获取。使用与 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” → “退出”。
2. 等待几秒钟。
3. 重新打开 Claude Desktop。

步骤 4：验证是否正常工作

在 Claude Desktop 中打开一个新对话并尝试输入：

"Check if Periphery is installed"

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

使用 MCP Inspector 进行测试

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

# 安装 MCP Inspector（如果尚未安装）
npm install -g @modelcontextprotocol/inspector

# 测试服务器
npx @modelcontextprotocol/inspector /usr/local/bin/periphery-mcp-server

# 或者如果使用构建目录
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（可选）：要扫描的构建方案（仅适用于 Xcode 项目）
  • targets（可选）：要分析的特定目标
  • 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（可选）：要扫描的构建方案
  • targets（可选）：要分析的特定目标

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 就代码进行自然对话：

检查安装情况

你："Check if Periphery is installed"

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

扫描项目

你："Scan my iOS project at ~/Projects/MyApp/MyApp.xcodeproj for unused code"

Claude：[使用 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
..."

查找冗余公共声明

你："Check which public declarations could be made internal in ~/Projects/MyFramework"

Claude：[使用 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)
..."

分析未使用的导入

你："Find unused imports in my Swift package"

Claude：[使用 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：

你："Scan my project using the custom config"

🔧 技术细节

本服务器采用 CLI 方式，而非将 Periphery 作为库导入，以实现最大稳定性：

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

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

相关项目

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

分发渠道

本服务器可通过以下多种渠道获取：

• MCP 注册表：registry.modelcontextprotocol.io
• Homebrew Tap：github.com/zyntx-lab/homebrew-tap
• GitHub 发布版：github.com/zyntx-lab/periphery-mcp-server/releases
• 社区服务器：列于 modelcontextprotocol/servers

支持

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

贡献

欢迎贡献代码！请按照以下步骤操作：

1. 分叉仓库。
2. 创建功能分支。
3. 为新功能添加测试。
4. 提交拉取请求。