Agent-almanac configure-putior-mcp

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/configure-putior-mcp" ~/.claude/skills/pjt222-agent-almanac-configure-putior-mcp-934627 && rm -rf "$T"

manifest: i18n/zh-CN/skills/configure-putior-mcp/SKILL.md

source content

配置 putior MCP 服务器

设置 putior MCP 服务器，使 AI 助手（Claude Code、Claude Desktop）可以直接调用工作流注释和图表生成工具。

适用场景

使 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）。不要将令牌粘贴到 shell 命令中或提交到版本控制。

第 2 步：配置 Claude Code（WSL/Linux/macOS）

将 putior MCP 服务器添加到 Claude Code 的配置中。

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

对于使用 Windows R 的 WSL：

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

预期结果：

putior

出现在 MCP 服务器列表中，状态为"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）

将 putior 添加到 Claude Desktop 的 MCP 配置文件中。

编辑

%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 检查器验证 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（代理通信协议）服务器用于代理间通信。

# 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：重启后 putior 出现在 MCP 服务器列表中
核心工具（
```
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 在没有 renv 的情况下启动 R，则找不到包。确保
```
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