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. 提交拉取請求。