外围MCP服务器
一个模型上下文协议（MCP）服务器，它公开 外围 通过iOS/macOS项目的静态分析功能 基于标准输入/输出（stdio）传输的模型上下文协议.
概述
此服务器封装了Periphery的死代码检测功能，使其可供Claude Desktop等MCP感知客户端访问。通信完全通过MCP的stdio传输进行--没有启动或暴露HTTP服务器该服务器为Swift/Objective-C项目提供自动设置、构建验证和全面的静态分析扫描。
特性
- 自动设置：具有合理默认值的交互式外围设备配置
- 构建验证：预扫描构建验证，以便及早发现问题
- 结构化分析：JSON格式的扫描结果，带有详细的问题报告
- 错误处理：全面的错误报告和可操作的反馈
- MCP集成：与Claude Desktop和其他MCP客户端无缝集成
先决条件
- macOS：Xcode和iOS/macOS开发所需
- 项目：用于构建iOS/macOS项目
- 外围：通过Homebrew安装：
brew install peripheryapp/periphery/periphery - Python 3.8+：用于运行MCP服务器
安装
- 克隆或下载 此存储库
- 创建conda环境:
conda create -n periphery-mcp python=3.12
conda activate periphery-mcp- 安装依赖项:
pip install "mcp[cli]==1.*" pexpect rich用法
启动服务器
服务器以MCP stdio传输方式运行（用于与Claude Desktop集成）：
cd /path/to/periphery-mcp
conda activate periphery-mcp
python periphery-mcp-server.py当与Claude Desktop集成时，服务器通过stdin/stdout进行通信。对于独立测试，您可以使用MCP CLI工具。
可用工具
1. periphery_setup
运行Periphery的交互式设置向导以创建 .periphery.yml 配置文件。
参数：
project_path（string）：Xcode项目目录的路径
退货：
success（boolean）：安装是否成功完成yml（string | null）：生成的YAML配置log_tail（数组）：设置进程日志输出
2. project_build
在运行静态分析之前，验证项目是否成功构建。
参数：
project_path（string）：Xcode项目目录的路径scheme（string，可选）：要构建的Xcode方案
退货：
build_ok（boolean）：构建是否成功log_tail（数组）：生成错误消息（如果有的话）
3. periphery_scan
执行全面的静态分析以检测未使用的代码。
参数：
project_path（string）：Xcode项目目录的路径extra_args（array，可选）：其他Periphery命令行参数
退货：
build_ok（boolean）：扫描是否成功完成issues（数组）：检测到位置信息问题raw_json（object|null）：JSON格式的完整外设输出build_error（对象|null）：扫描失败时的错误详细信息
问题格式示例
{
"kind": "unused_function",
"identifier": "MyClass.unusedMethod()",
"file": "/path/to/MyClass.swift",
"line": 42
}与Claude Desktop集成
要将此服务器与Claude Desktop一起使用，您需要将其添加到MCP配置中：
步骤1：添加到Claude桌面配置
编辑您的Claude Desktop配置文件（位于 ~/Library/Application Support/Claude/claude_desktop_config.json)并将以下条目添加到 mcpServers 章节：
{
"mcpServers": {
"periphery-mcp": {
"command": "/path/to/conda/envs/periphery-mcp/bin/python",
"args": [
"/path/to/periphery-mcp/periphery-mcp-server.py"
],
"env": {
"CONDA_DEFAULT_ENV": "periphery-mcp"
}
}
}
}替换路径 根据您的实际安装路径：
/path/to/conda/envs/periphery-mcp/bin/python→ 您的conda环境Python可执行文件/path/to/periphery-mcp/periphery-mcp-server.py→ 此服务器脚本的路径
第二步：找到你的Python路径
要查找您的conda环境Python路径：
conda activate periphery-mcp
which python步骤3：重新启动克劳德桌面
更新配置后，重新启动Claude Desktop以使更改生效。
步骤4：使用自然语言命令
配置后，您可以使用自然语言分析您的项目：
- “扫描我的iOS项目以查找死代码”
- “检查我的项目是否成功构建”
- “为我的新Swift项目设置外围设备”
替代方案：使用附带的启动脚本
为了更容易配置，您可以使用附带的启动脚本自动检测您的conda安装：
chmod +x start-server.sh
./start-server.sh启动脚本将：
- 自动检测常见的conda安装位置
- 更改到正确的目录
- 激活外围mcp环境
- 启动服务器
然后使用这个更简单的Claude Desktop配置：
{
"mcpServers": {
"periphery-mcp": {
"command": "/absolute/path/to/periphery-mcp/start-server.sh"
}
}
}替换 /absolute/path/to/periphery-mcp/ 带有项目目录的实际路径。
工作流示例
- 设置：首次运行创建
.periphery.yml具有项目特定配置 - 构建检查：验证项目是否成功编译
- 扫描：分析代码中未使用的声明、导入和协议
- 审查：检查结果并删除已识别的死代码
配置
服务器通过交互式设置自动处理外围设备配置。常见的配置选项包括：
- 构建目标：要分析哪些方案/目标
- 文件模式：包括/排除特定文件或目录
- 分析深度：静态分析应该有多彻底
故障排除
命令行测试
您可以在没有Claude Desktop的情况下直接从命令行测试工具：
# Test scanning a project
python cli_test.py scan /path/to/your/ios/project
# Test building a project (optionally specify scheme)
python cli_test.py build /path/to/your/ios/project [scheme]
# Test Periphery setup
python cli_test.py setup /path/to/your/ios/project
# Scan with extra Periphery arguments
python cli_test.py scan /path/to/your/ios/project --verbose这将向您准确显示每个工具返回的内容，并帮助您识别以下方面的任何问题：
- 路径分辨率
- 外围设备安装
- 项目构建问题
- 配置问题
工具超时和无反馈
如果您在使用Claude Desktop中的工具时遇到超时：
- 首先从命令行进行测试：使用
python cli_test.py scan /path/to/project验证该工具在Claude Desktop之外是否正常工作
- 检查克劳德桌面日志：在Claude Desktop的日志中查找调试输出
- 打开克劳德桌面 - 转到帮助→ 显示日志或检查控制台输出 - 寻找 [PERIPHERY-MCP DEBUG] 消息
- 测试服务器功能：使用附带的测试脚本：
python test_tools.py这可以直接测试工具的功能，而无需MCP协议开销。
- 调试步骤:
- 首先，使用CLI进行测试： python cli_test.py scan /your/project/path - 检查Claude Desktop日志中的MCP通信错误 - 验证您的项目路径是否正确且可访问 - 确保安装了所有必备组件
- 检查先决条件:
- 验证外围设备是否已安装： periphery version - 确保Xcode已安装并正常工作 - 首先测试你的项目是否在Xcode中构建 - 确保conda环境已正确激活
- 常见超时原因:
- 大型项目需要时间进行分析（对于非常大的代码库，最多需要30分钟） - Xcode依赖解析过程中的网络问题 - 缺少构建依赖项或证书 - Xcode项目文件损坏
调试输出
服务器将详细的调试信息记录到stderr，该信息显示在Claude Desktop日志中。每个工具执行显示：
- 输入参数和路径分辨率
- 命令执行细节和时间
- 带有完整堆栈跟踪的错误消息
- 外围设备设置和扫描进度
调试日志条目示例：
[PERIPHERY-MCP DEBUG] periphery_scan called with project_path: /path/to/project, extra_args: None
[PERIPHERY-MCP DEBUG] Resolved project path: /path/to/project
[PERIPHERY-MCP DEBUG] Checking for config file: /path/to/project/.periphery.yml
[PERIPHERY-MCP DEBUG] Running build check
[PERIPHERY-MCP DEBUG] Running periphery scan: periphery scan --format json
[PERIPHERY-MCP DEBUG] Found 42 issues使用您的项目进行测试
要使用真实的iOS/macOS项目进行测试，请修改测试脚本：
# Add this to test_tools.py
result = project_build("/path/to/your/ios/project")
print(f"Real project test: {result}")- 寻找
[PERIPHERY-MCP DEBUG]消息
- 手动测试服务器：使用附带的测试脚本：
python test_mcp_server.py这将测试基本服务器功能并显示调试输出。
- 检查先决条件:
- 验证外围设备是否已安装： periphery version - 确保Xcode已安装并正常工作 - 首先测试你的项目是否在Xcode中构建
- 常见超时原因:
- 大型项目需要时间进行分析（对于非常大的代码库，最多需要30分钟） - Xcode依赖解析过程中的网络问题 - 缺少构建依赖项或证书 - Xcode项目文件损坏
调试输出
服务器现在将详细的调试信息记录到stderr，该信息显示在Claude Desktop日志中。每次工具执行将显示：
- 输入参数
- 路径分辨率
- 命令执行详细信息
- 错误消息和堆栈跟踪
- 执行时间
常见问题
“项目路径不存在”
- 验证您提供的路径是否存在
- 尽可能使用绝对路径
- 检查您是否具有该目录的读取权限
“外围设备安装失败”
- 确保你的项目在Xcode中成功构建
- 检查是否正确配置了所有依赖项
- 验证外围设备是否已安装：
periphery version
“构建失败”
- 在Xcode中打开项目并解决任何编译错误
- 确保所有必需的证书和配置文件都可用
- 检查指定的方案是否存在
连接问题
- 验证Claude Desktop配置是否正确
- 检查服务器可执行文件路径是否正确
- 确保conda环境已激活
- 检查Claude Desktop日志以了解错误详细信息
性能提示
- 对于大型项目，从子集开始，使用
extra_args: ["--verbose"] - 使用排除测试目标的构建方案以加快分析速度
- 考虑排除供应商/第三方代码目录
- 首先在Xcode中运行构建，以确保所有依赖关系都已解决
局限性
- 平台：仅限macOS（由于依赖Xcode）
- 交互式设置：简化的提示处理（对复杂提示使用默认值）
- 构建要求：项目必须成功编译才能进行分析
贡献
欢迎投稿！需要改进的地方：
- 增强的交互式设置，提供完整的流媒体支持
- 支持其他静态分析工具
- 与CI/CD管道集成
- 更精细的过滤选项
许可证
本项目按原样提供，用于教育和发展目的。