Periphery MCP Server

外围MCP服务器

特性

• 7 MCP工具 用于全面的代码分析
• CLI集成 -使用Periphery CLI实现稳定性和版本灵活性
• JSON输出 -结构化、可解析的结果非常适合人工智能解释
• 灵活扫描 -支持Xcode项目和Swift包
• 高级选项 -完全控制外围设备扫描配置

快速开始

使用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或更高版本
• 外围 安装

安装外围设备

brew install peripheryapp/periphery/periphery

或从以下网址下载 外围设备释放.

安装

选项1：自制（推荐）

# 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版本下载

从下载最新二进制文件 发布:

# 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注册表安装

服务器也可在 MCP注册表。使用兼容MCP的客户端直接安装。

配置

克劳德桌面

步骤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，更改才能生效。

1. 退出Claude桌面：按 Cmd+Q 或使用克劳德桌面→ Quit
2. 等几秒钟
3. 重新打开克劳德桌面

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

在Claude Desktop中打开一个新对话，然后尝试：

"Check if Periphery is installed"

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

MCP检验员测试

在配置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

检查器将在您的浏览器中打开，您可以在其中交互式地测试所有工具。

其他编辑

VS Code

增添 .vscode/mcp.json:

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

光标

增添 .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

在项目上运行基本的外围设备扫描。

参数：

• 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配置文件运行外围设备扫描。

参数：

• 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

使用自定义外围设备标志进行高级扫描。

参数：

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

用法示例

使用克劳德桌面

配置后，您可以与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桌面中

症状： 配置后Claude无法识别外围工具

解决：

1. 验证配置文件语法：

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

1. 检查二进制路径是否正确：

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

1. 完全重新启动克劳德桌面：

- 按 Cmd+Q 退出（不仅仅是关闭窗口） - 等待5秒 - 重新打开克劳德桌面 - 开始新对话（旧对话看不到新服务器）

1. 检查克劳德桌面日志：

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

未找到外围设备

如果您收到“未安装外围设备”：

1. 安装外围设备： brew install peripheryapp/periphery/periphery
2. 验证安装： which periphery
3. 重新启动克劳德桌面/VS代码/光标
4. 试试 check_periphery_installed 工具再次

MCP检查器连接错误

如果检查器无法连接到服务器：

1. 验证服务器是否运行：

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

1. 检查错误：

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

1. 使用绝对路径：

   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. 确保方案共享：

- 项目→ 产品→ 方案→ 管理方案 - 选中方案的“共享”复选框

1. 验证项目路径：

   # For Xcode projects
   ls /path/to/YourProject.xcodeproj

   # For Swift Packages
   ls /path/to/Package.swift

1. 检查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
• ✅ 更简单的依赖关系管理

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

相关项目

• 外围 -底层代码分析工具
• 模型上下文协议 -协议规范
• MCP Swift SDK -MCP官方Swift SDK
• MCP注册表 -MCP服务器官方注册表
• MCP社区服务器 -社区MCP服务器集合

分销渠道

此服务器可通过多种渠道使用：

• MCP注册表: register.modelcontextprotocol.io
• 自制水龙头:
• GitHub发布:
• 社区服务器：列在 模型上下文协议/服务器

支持

• 问题:
• 外围文件: 外围设备指南
• MCP文件: MCP规范