Periphery Code Audit

Periphery MCP サーバー

Periphery ツールをラップし、AI アシスタントが iOS／macOS プロジェクトの Swift コード監査を実施し、未使用コードを検出できるようにする Model Context Protocol (MCP) サーバーです。

機能

• 包括的なコード分析を行う 7 つの MCP ツール
• CLI との統合 - 安定性とバージョンの柔軟性のため、Periphery CLI を使用します
• JSON 出力 - AI による解釈に最適な、構造化された解析可能な結果を出力します
• 柔軟なスキャン - Xcode プロジェクトと Swift パッケージに対応しています
• 高度なオプション - 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 のリリースからダウンロードしてください。

インストール

オプション 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 → 終了を選択します
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（任意）：スキャンするビルドスキーム（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 と自然な会話ができます。

インストールを確認する：

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 is not installed」と表示される場合：

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
   

アクセスが拒否された

サーバーの実行時に「Permission denied」と表示される場合：

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

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

アーキテクチャ

このサーバーでは、安定性を最大限に高めるため、Periphery をライブラリとしてインポートするのではなく、CLI 方式を採用しています。

• ✅ CLI インターフェースは Periphery の公開 API 契約です
• ✅ Periphery の内部リファクタリングの影響を受けません
• ✅ ユーザーは Periphery を個別に更新できます
• ✅ 依存関係の管理がよりシンプルです

コントリビューション

コントリビューションを歓迎します。以下の手順でお願いします。

1. リポジトリをフォークします
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 Guide
• MCP のドキュメント：MCP Specification