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/caveman/skills/configure-putior-mcp" ~/.claude/skills/pjt222-agent-almanac-configure-putior-mcp-346bd2 && rm -rf "$T"

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

source content

Configure putior MCP Server

Set up putior MCP server so AI assistants (Claude Code, Claude Desktop) can directly call workflow annotation, diagram generation tools.

When Use

Enable AI assistants to interactively annotate, visualize workflows
Set up new dev environment with putior MCP integration
After install putior and want AI-assisted workflow documentation
Configure agent-to-agent communication via ACP for automated pipelines

Inputs

Required: putior installed (see
```
install-putior
```
)
Required: Target client: Claude Code, Claude Desktop, or both
Optional: Whether to also configure ACP server (default: no)
Optional: Custom host/port for ACP server (default: localhost:8080)

Steps

Step 1: Install MCP Dependencies

Install required packages for MCP server functionality.

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

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

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

Got: Both packages install, load without errors.

If fail:

mcptools

requires

remotes

package. Install first:

install.packages("remotes")

. GitHub rate-limits? Configure

GITHUB_PAT

~/.Renviron

(add line

GITHUB_PAT=your_token_here

, restart R). Do not paste tokens into shell commands or commit them to version control.

Step 2: Configure Claude Code (WSL/Linux/macOS)

Add putior MCP server to Claude Code configuration.

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

For WSL with Windows R:

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

Verify configuration:

claude mcp list
claude mcp get putior

Got:

putior

appears in MCP server list with status "configured".

If fail: Claude Code not in PATH? Add:

export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"

. Rscript path wrong? Locate R with

which Rscript

ls "/mnt/c/Program Files/R/"

Step 3: Configure Claude Desktop (Windows)

Add putior to Claude Desktop MCP configuration file.

Edit

%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()"]
    }
  }
}

Or with full path:

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

Restart Claude Desktop after editing configuration.

Got: Claude Desktop shows putior in its MCP server list. Tools become available in conversation.

If fail: Validate JSON syntax with JSON linter. Check R path exists. Use 8.3 short names (

PROGRA~1

R-45~1.0

) if spaces in paths cause issues.

Step 4: Verify All 16 Tools

Test all MCP tools accessible, functional.

# 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 tools organized by category:

Core Workflow (5):

```
put
```
— Scan files for PUT annotations (supports
```
exclude
```
parameter for regex-based file filtering)
```
put_diagram
```
— Generate Mermaid diagrams
```
put_auto
```
— Auto-detect workflow from code (supports
```
exclude
```
parameter)
```
put_generate
```
— Generate annotation suggestions (supports
```
exclude
```
parameter)
```
put_merge
```
— Merge manual + auto annotations (supports
```
exclude
```
parameter)

Reference/Discovery (7):

```
get_comment_prefix
```
— Get comment prefix for extension
```
get_supported_extensions
```
— List supported extensions
```
list_supported_languages
```
— List supported languages
```
get_detection_patterns
```
— Get auto-detection patterns
```
get_diagram_themes
```
— List available themes
```
putior_guide
```
— AI assistant documentation
```
putior_help
```
— Quick reference help

Utilities (3):

```
is_valid_put_annotation
```
— Validate annotation syntax
```
split_file_list
```
— Parse file lists
```
ext_to_language
```
— Extension to language name

Configuration (1):

```
set_putior_log_level
```
— Configure logging verbosity

Important: Custom palettes cannot be used through MCP. The
palette
parameter on
put_diagram
accepts a
putior_theme
R object created by
put_theme()
. Because MCP communicates via JSON, R objects like
putior_theme
cannot be serialized across MCP boundary. When calling
put_diagram
through MCP, use string-based
theme
parameter (e.g.,
theme = "viridis"
) instead. For custom palettes, call
put_theme()
and
put_diagram(palette = ...)
directly in R session.

Test core tools from 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

Got: All 16 tools listed. Core tools return expected results when called with valid inputs.

If fail: Tools missing? Check putior version current:

packageVersion("putior")

. Older versions may have fewer tools. Update with

remotes::install_github("pjt222/putior")

Step 5: Configure ACP Server (Optional)

Set up ACP (Agent Communication Protocol) server for agent-to-agent communication.

# 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)

Test ACP endpoints:

# 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/"}]}]}'

Got: ACP server starts on configured port.

/agents

returns putior agent manifest.

/runs

accepts natural language requests, returns workflow results.

If fail: Port 8080 in use? Specify different port.

plumber2

not installed? Server function prints helpful error message suggesting installation.

Checks

putior::putior_mcp_tools()

exposes core tools (

put

put_diagram

put_auto

put_generate

put_merge

), returns ~16 tools for current version

Claude Code:
```
claude mcp list
```
shows
```
putior
```
configured
Claude Code:
```
putior_help
```
tool returns help text when invoked
Claude Desktop: putior appears in MCP server list after restart
Core tools (
```
put
```
,
```
put_diagram
```
,
```
put_auto
```
) execute without errors
(Optional) ACP server responds to
```
curl http://localhost:8080/agents
```

Pitfalls

mcptools not installed: MCP server requires
```
mcptools
```
(from GitHub) and
```
ellmer
```
(from CRAN). Both must be installed. putior checks, provides helpful messages if missing.
Wrong R path in Claude Desktop: Windows paths need escaping in JSON (
```
\\
```
). Use 8.3 short names to avoid spaces:
```
C:\\PROGRA~1\\R\\R-45~1.0\\bin\\x64\\Rscript.exe
```
.
Forgetting to restart: Claude Desktop must be restarted after editing config file. Claude Code picks up changes on next session start.
renv isolation: putior installed in renv library but Claude Code/Desktop launches R without renv? Packages won't be found. Ensure
```
mcptools
```
and
```
ellmer
```
installed in global library or configure renv activation in MCP server command.
Port conflicts for ACP: Default ACP port (8080) commonly used. Check with
```
lsof -i :8080
```
or
```
netstat -tlnp | grep 8080
```
before starting.
Including only specific tools: To expose subset of tools, use
```
putior_mcp_tools(include = c("put", "put_diagram"))
```
when building custom MCP server wrappers.
Custom palettes via MCP:
```
palette
```
parameter on
```
put_diagram
```
requires
```
putior_theme
```
R object (created by
```
put_theme()
```
), which cannot be serialized through MCP JSON interface. Use built-in
```
theme
```
parameter string for MCP calls. For custom palettes, use R directly.