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（推奨）

# タップを追加
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 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でサーバーをテストできます。

# 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"
    }
  }
}

💻 使用例

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"

🛠 トラブルシューティング

Claude Desktopにサーバーが表示されない場合

症状: 設定後、ClaudeがPeripheryツールを認識しない

解決策:

1. 設定ファイルの構文を確認する

   # JSON構文エラーをチェック
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
   

2. バイナリパスが正しいことを確認する

   # バイナリが存在し、実行できることをテスト
   /usr/local/bin/periphery-mcp-server
   # またはカスタムパス
   /path/to/.build/release/periphery-mcp-server
   

3. Claude Desktopを完全に再起動する
   • Cmd+Q を押して終了する (ウィンドウを閉じるだけではなく)
   • 5秒待つ
   • Claude Desktopを再度開く
   • 新しい会話を開始する (古い会話では新しいサーバーが表示されない)
4. Claude Desktopのログを確認する

   # エラーを表示するためのログを表示
   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. サーバーが実行されていることを確認する

   # サーバーは入力を待機する必要があり、すぐに終了しないでください
   /usr/local/bin/periphery-mcp-server
   # Ctrl+Cで終了
   

2. エラーを確認する

   # 詳細な出力で実行
   /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. プロジェクトパスを確認する

   # Xcodeプロジェクトの場合
   ls /path/to/YourProject.xcodeproj
   
   # Swiftパッケージの場合
   ls /path/to/Package.swift
   

4. Peripheryがプロジェクトにアクセスできることを確認する

   # 直接Peripheryをテストする
   periphery scan --project /path/to/YourProject.xcodeproj --schemes YourScheme
   

権限が拒否される場合

サーバーを実行するときに "Permission denied" と表示された場合は、以下のコマンドを実行してください。

# バイナリを実行可能にする
chmod +x /usr/local/bin/periphery-mcp-server

# またはビルドディレクトリの場合
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
• Community Servers: modelcontextprotocol/servers に掲載

サポート

• 問題報告: GitHub Issues
• Peripheryドキュメント: Periphery Guide
• MCPドキュメント: MCP Specification