R MCP Agent Guide — Development skill for Claude Code

用自然語言控制 R：MCP × R 統計環境安裝說明書

讓任何 AI Agent（Claude Code / ChatGPT Codex / Gemini CLI / OpenCode）透過 **MCP（Model Context Protocol）** 驅動本機的 **R** 統計引擎 —— 使用者只用自然語言下指令，Agent 就能跑迴歸、ANOVA、t 檢定、繪圖，全程不必碰 R 介面。

本說明書記錄了一套**已實際驗證可運作**的完整流程（驗證環境：Windows 11 + R 4.6.0 + Claude Code）。其他 Agent 讀到本文件時，可依此流程在自己的環境完成安裝並學會使用。

---

0. 這套方案在做什麼？（給 Agent 的心智模型）

使用者（自然語言）
      │  「幫我用 R 跑迴歸」
      ▼
   AI Agent ──呼叫 MCP 工具 btw_tool_run_r──►  R 引擎（mcptools server 程序）
      ▲                                              │
      └──────────  回傳統計結果 / 圖檔  ◄────────────┘

• MCP server = 一個常駐的 R 程序，由 mcptools::mcp_server() 啟動。
• 執行能力 = 由 btw 套件提供的 btw_tool_run_r 工具，能在該 R 程序裡執行任意 R 程式碼並回傳結果（含印出的值、文字、圖、警告、錯誤）。
• 關鍵：btw_tool_run_r 預設關閉（因為能執行任意程式碼），必須明確啟用。
• 程式碼在 server 程序內執行，狀態跨呼叫保留，不需要另外開 RStudio。RStudio 是給人看的選配工具。

一句話：裝好 R → 裝 `mcptools` + `btw` → 啟用 `run_r` → 把 server 註冊給你的 Agent → 重啟 Agent → 開始用自然語言下指令。

---

1. 安裝 R（必裝）與 RStudio（選配）

能不能用，取決於 **R 是否裝好**，不是 RStudio。RStudio 只是圖形介面，給人看圖、管理變數用。

Windows（已驗證）

# R 本體（必裝）
winget install --id RProject.R -e --accept-source-agreements --accept-package-agreements

# RStudio（選配，給人用的 IDE）
winget install --id Posit.RStudio -e --accept-source-agreements --accept-package-agreements

• 預設安裝路徑：C:\Program Files\R\R-<版本>\，執行檔在 ...\bin\Rscript.exe。
• ⚠️ winget 不會更新「目前終端機 session」的 PATH。裝完後新開的終端機才會有 Rscript；在同一個 session 內請用完整路徑呼叫。
• 把 R 加進使用者 PATH（之後任何終端機可直接用 Rscript）：

$rbin = "C:\Program Files\R\R-4.6.0\bin"   # 換成你的實際版本
$u = [Environment]::GetEnvironmentVariable("Path","User")
if ($u -notlike "*$rbin*") { [Environment]::SetEnvironmentVariable("Path", ($u.TrimEnd(';')+";"+$rbin), "User") }

macOS

brew install --cask r          # R 本體
brew install --cask rstudio    # RStudio（選配）
# Rscript 通常在 /usr/local/bin/Rscript 或 /Library/Frameworks/R.framework/Resources/bin/Rscript

Linux（Debian/Ubuntu）

sudo apt update && sudo apt insta