putior MCPサーバーの設定

AIアシスタント（Claude Code、Claude Desktop）がワークフローのアノテーションとダイアグラム生成ツールを直接呼び出せるように、putior MCPサーバーをセットアップする。

使用タイミング

• AIアシスタントがワークフローをインタラクティブにアノテーション・可視化できるようにする時
• putior MCP統合で新しい開発環境をセットアップする時
• putiorをインストールした後にAI支援のワークフロードキュメンテーションが必要な時
• 自動化パイプライン用のACP経由のエージェント間通信を設定する時

入力

• 必須: putiorがインストール済み（install-putiorを参照）
• 必須: ターゲットクライアント: Claude Code、Claude Desktop、または両方
• 任意: ACPサーバーも設定するかどうか（デフォルト: いいえ）
• 任意: ACPサーバーのカスタムホスト/ポート（デフォルト: localhost:8080）

手順

ステップ1: MCP依存関係のインストール

MCPサーバー機能に必要なパッケージをインストールする。

# Required: MCP framework
remotes::install_github("posit-dev/mcptools")

# Required: Tool definition framework
install.packages("ellmer")

# Verify both load
library(mcptools)
library(ellmer)

期待結果: 両方のパッケージがエラーなくインストール・ロードされる。

失敗時: mcptoolsにはremotesパッケージが必要。まずインストールする：install.packages("remotes")。GitHubがレート制限する場合、~/.RenvironにGITHUB_PATを設定する（GITHUB_PAT=your_token_hereの行を追加してRを再起動）。トークンをシェルコマンドに貼り付けたりバージョン管理にコミットしたりしない。

ステップ2: Claude Code（WSL/Linux/macOS）の設定

Claude Codeの設定にputior MCPサーバーを追加する。

# One-line setup
claude mcp add putior -- Rscript -e "putior::putior_mcp_server()"

WSLでWindows Rを使用する場合:

claude mcp add putior -- "/mnt/c/Program Files/R/R-4.5.2/bin/Rscript.exe" -e "putior::putior_mcp_server()"

設定の確認:

claude mcp list
claude mcp get putior

期待結果: MCPサーバーリストにputiorがステータス「configured」で表示される。

失敗時: Claude CodeがPATHにない場合、追加する：export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"。Rscriptのパスが間違っている場合、which Rscriptまたはls "/mnt/c/Program Files/R/"でRの場所を確認する。

ステップ3: Claude Desktop（Windows）の設定

Claude DesktopのMCP設定ファイルにputiorを追加する。

%APPDATA%\Claude\claude_desktop_config.jsonを編集する:

{
  "mcpServers": {
    "putior": {
      "command": "C:\\PROGRA~1\\R\\R-45~1.0\\bin\\x64\\Rscript.exe",
      "args": ["-e", "putior::putior_mcp_server()"]
    }
  }
}

またはフルパスで:

{
  "mcpServers": {
    "putior": {
      "command": "C:\\Program Files\\R\\R-4.5.2\\bin\\x64\\Rscript.exe",
      "args": ["-e", "putior::putior_mcp_server()"]
    }
  }
}

設定ファイル編集後にClaude Desktopを再起動する。

期待結果: Claude DesktopのMCPサーバーリストにputiorが表示される。会話中にツールが利用可能になる。

失敗時: JSONリンターで構文を検証する。Rパスが存在することを確認する。パスのスペースが問題を引き起こす場合は8.3短縮名（PROGRA~1、R-45~1.0）を使用する。

ステップ4: 全16ツールの検証

すべてのMCPツールがアクセス可能で機能することをテストする。

# Get tool definitions
tools <- putior::putior_mcp_tools()
cat(sprintf("Total tools: %d\n", length(tools)))

# List tool names
vapply(tools, function(t) t$name, character(1))

カテゴリ別の16ツール:

コアワークフロー（5）:

• put -- ファイルからPUTアノテーションをスキャン（正規表現ベースのファイルフィルタリング用のexcludeパラメータをサポート）
• put_diagram -- Mermaidダイアグラムを生成
• put_auto -- コードからワークフローを自動検出（excludeパラメータをサポート）
• put_generate -- アノテーション提案を生成（excludeパラメータをサポート）
• put_merge -- 手動と自動のアノテーションをマージ（excludeパラメータをサポート）

リファレンス/ディスカバリ（7）:

• get_comment_prefix -- 拡張子のコメントプレフィックスを取得
• get_supported_extensions -- サポートされる拡張子を一覧表示
• list_supported_languages -- サポートされる言語を一覧表示
• get_detection_patterns -- 自動検出パターンを取得
• get_diagram_themes -- 利用可能なテーマを一覧表示
• putior_guide -- AIアシスタントドキュメンテーション
• putior_help -- クイックリファレンスヘルプ

ユーティリティ（3）:

• is_valid_put_annotation -- アノテーション構文を検証
• split_file_list -- ファイルリストをパース
• ext_to_language -- 拡張子を言語名に変換

設定（1）:

• set_putior_log_level -- ログ詳細度を設定

Claude Codeからコアツールをテスト:

Use the putior_help tool to see available commands
Use the put tool to scan ./R/ for annotations
Use the put_diagram tool to generate a diagram

期待結果: 全16ツールがリストされる。有効な入力でコアツールが期待通りの結果を返す。

失敗時: ツールが欠けている場合、putiorのバージョンが最新か確認する：packageVersion("putior")。古いバージョンではツールが少ない場合がある。remotes::install_github("pjt222/putior")で更新する。

ステップ5: ACPサーバーの設定（任意）

エージェント間通信用のACP（Agent Communication Protocol）サーバーをセットアップする。

# Install ACP dependency
install.packages("plumber2")

# Start ACP server (blocks — run in a separate R session or background)
putior::putior_acp_server()

# Custom host/port
putior::putior_acp_server(host = "0.0.0.0", port = 9000)

ACPエンドポイントのテスト:

# Discover agent
curl http://localhost:8080/agents

# Execute a scan
curl -X POST http://localhost:8080/runs \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "parts": [{"content": "scan ./R/"}]}]}'

# Generate diagram
curl -X POST http://localhost:8080/runs \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "parts": [{"content": "generate diagram for ./R/"}]}]}'

期待結果: ACPサーバーが設定されたポートで起動する。/agentsがputiorエージェントマニフェストを返す。/runsが自然言語リクエストを受け付けワークフロー結果を返す。

失敗時: ポート8080が使用中の場合、別のポートを指定する。plumber2がインストールされていない場合、サーバー関数がインストールを提案する有用なエラーメッセージを表示する。

バリデーション

• putior::putior_mcp_tools()がコアツール（put、put_diagram、put_auto、put_generate、put_merge）を公開し、現在のバージョンで約16ツールを返す
• Claude Code: claude mcp listでputiorが設定済みと表示される
• Claude Code: 呼び出し時にputior_helpツールがヘルプテキストを返す
• Claude Desktop: 再起動後にMCPサーバーリストにputiorが表示される
• コアツール（put、put_diagram、put_auto）がエラーなく実行される
• （任意）ACPサーバーがcurl http://localhost:8080/agentsに応答する

よくある落とし穴

• mcptoolsがインストールされていない: MCPサーバーにはmcptools（GitHubから）とellmer（CRANから）が必要。両方がインストールされている必要がある。putiorは不足している場合に有用なメッセージを表示する
• Claude DesktopのRパスが間違っている: WindowsパスはJSON内でエスケープが必要（\\）。スペースを避けるために8.3短縮名を使用する：C:\\PROGRA~1\\R\\R-45~1.0\\bin\\x64\\Rscript.exe
• 再起動の忘れ: Claude Desktopは設定ファイル編集後に再起動が必要。Claude Codeは次のセッション開始時に変更を反映する
• renvの分離: putiorがrenvライブラリにインストールされているがClaude Code/DesktopがRをrenvなしで起動する場合、パッケージが見つからない。mcptoolsとellmerがグローバルライブラリにインストールされているか、MCPサーバーコマンドでrenvアクティベーションが設定されていることを確認する
• ACPのポート競合: デフォルトACPポート（8080）はよく使用される。起動前にlsof -i :8080またはnetstat -tlnp | grep 8080で確認する
• 特定のツールのみを含める: ツールのサブセットを公開するには、カスタムMCPサーバーラッパーを構築する際にputior_mcp_tools(include = c("put", "put_diagram"))を使用する
• MCP経由のカスタムパレット: put_diagramのpaletteパラメータにはputior_theme Rオブジェクト（put_theme()で作成）が必要で、MCPのJSONインターフェース経由ではシリアライズできない。MCP呼び出しには組み込みのthemeパラメータ文字列を使用する。カスタムパレットにはRを直接使用する

関連スキル

• install-putior -- 前提条件: putiorとオプションの依存関係がインストールされている必要がある
• configure-mcp-server -- Claude Code/Desktop用の一般的なMCPサーバー設定
• troubleshoot-mcp-connection -- ツールが表示されない場合の接続問題の診断
• build-custom-mcp-server -- putiorツールをラップするカスタムMCPサーバーの構築
• analyze-codebase-workflow -- コードベース分析にMCPツールをインタラクティブに使用