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

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

source content

Configure putior MCP Server

Configurar el servidor MCP de putior para que los asistentes de IA (Claude Code, Claude Desktop) puedan llamar directamente a las herramientas de anotación de flujo de trabajo y generación de diagramas.

Cuándo Usar

Habilitar asistentes de IA para anotar y visualizar flujos de trabajo interactivamente
Configurar un nuevo entorno de desarrollo con integración MCP de putior
Después de instalar putior y querer documentación de flujo de trabajo asistida por IA
Configurar comunicación agente-a-agente vía ACP para pipelines automatizados

Entradas

Requerido: putior instalado (ver
```
install-putior
```
)
Requerido: Cliente objetivo: Claude Code, Claude Desktop, o ambos
Opcional: Si también configurar el servidor ACP (por defecto: no)
Opcional: Host/puerto personalizado para el servidor ACP (por defecto: localhost:8080)

Procedimiento

Paso 1: Instalar Dependencias MCP

Instalar los paquetes requeridos para la funcionalidad del servidor MCP.

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

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

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

Esperado: Ambos paquetes se instalan y cargan sin errores.

En caso de fallo:

mcptools

requiere el paquete

remotes

. Instalarlo primero:

install.packages("remotes")

. Si GitHub limita la tasa, configurar un

GITHUB_PAT

~/.Renviron

(agregar la línea

GITHUB_PAT=your_token_here

y reiniciar R). No pegar tokens en comandos de shell ni incluirlos en control de versiones.

Paso 2: Configurar Claude Code (WSL/Linux/macOS)

Agregar el servidor MCP de putior a la configuración de Claude Code.

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

Para WSL con R de Windows:

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

Verificar la configuración:

claude mcp list
claude mcp get putior

Esperado:

putior

aparece en la lista de servidores MCP con estado "configured".

En caso de fallo: Si Claude Code no está en PATH, agregarlo:

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

. Si la ruta de Rscript es incorrecta, localizar R con

which Rscript

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

Paso 3: Configurar Claude Desktop (Windows)

Agregar putior al archivo de configuración MCP de Claude Desktop.

Editar

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

O con la ruta completa:

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

Reiniciar Claude Desktop después de editar la configuración.

Esperado: Claude Desktop muestra putior en su lista de servidores MCP. Las herramientas se vuelven disponibles en la conversación.

En caso de fallo: Validar la sintaxis JSON con un linter JSON. Verificar que la ruta de R exista. Usar nombres cortos 8.3 (

PROGRA~1

R-45~1.0

) si los espacios en las rutas causan problemas.

Paso 4: Verificar las 16 Herramientas

Probar que todas las herramientas MCP sean accesibles y funcionales.

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

Las 16 herramientas organizadas por categoría:

Flujo de Trabajo Principal (5):

```
put
```
-- Escanear archivos para anotaciones PUT (soporta parámetro
```
exclude
```
para filtrado de archivos basado en regex)
```
put_diagram
```
-- Generar diagramas Mermaid
```
put_auto
```
-- Auto-detectar flujo de trabajo desde código (soporta parámetro
```
exclude
```
)
```
put_generate
```
-- Generar sugerencias de anotación (soporta parámetro
```
exclude
```
)
```
put_merge
```
-- Fusionar anotaciones manuales + automáticas (soporta parámetro
```
exclude
```
)

Referencia/Descubrimiento (7):

```
get_comment_prefix
```
-- Obtener prefijo de comentario para extensión
```
get_supported_extensions
```
-- Listar extensiones soportadas
```
list_supported_languages
```
-- Listar lenguajes soportados
```
get_detection_patterns
```
-- Obtener patrones de auto-detección
```
get_diagram_themes
```
-- Listar temas disponibles
```
putior_guide
```
-- Documentación del asistente de IA
```
putior_help
```
-- Ayuda de referencia rápida

Utilidades (3):

```
is_valid_put_annotation
```
-- Validar sintaxis de anotación
```
split_file_list
```
-- Analizar listas de archivos
```
ext_to_language
```
-- Extensión a nombre de lenguaje

Configuración (1):

```
set_putior_log_level
```
-- Configurar verbosidad de registro

Probar herramientas principales desde 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

Esperado: Las 16 herramientas listadas. Las herramientas principales retornan resultados esperados cuando se llaman con entradas válidas.

En caso de fallo: Si faltan herramientas, verificar que la versión de putior sea actual:

packageVersion("putior")

. Las versiones anteriores pueden tener menos herramientas. Actualizar con

remotes::install_github("pjt222/putior")

Paso 5: Configurar Servidor ACP (Opcional)

Configurar el servidor ACP (Agent Communication Protocol) para comunicación agente-a-agente.

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

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

Esperado: El servidor ACP inicia en el puerto configurado.

/agents

retorna el manifiesto del agente putior.

/runs

acepta solicitudes en lenguaje natural y retorna resultados de flujo de trabajo.

En caso de fallo: Si el puerto 8080 está en uso, especificar un puerto diferente. Si

plumber2

no está instalado, la función del servidor imprimirá un mensaje de error útil sugiriendo la instalación.

Validación

```
putior::putior_mcp_tools()
```
expone las herramientas principales (
```
put
```
,
```
put_diagram
```
,
```
put_auto
```
,
```
put_generate
```
,
```
put_merge
```
) y retorna ~16 herramientas para la versión actual
Claude Code:
```
claude mcp list
```
muestra
```
putior
```
configurado
Claude Code: la herramienta
```
putior_help
```
retorna texto de ayuda cuando se invoca
Claude Desktop: putior aparece en la lista de servidores MCP después de reiniciar
Las herramientas principales (
```
put
```
,
```
put_diagram
```
,
```
put_auto
```
) se ejecutan sin errores
(Opcional) El servidor ACP responde a
```
curl http://localhost:8080/agents
```

Errores Comunes

mcptools no instalado: El servidor MCP requiere
```
mcptools
```
(de GitHub) y
```
ellmer
```
(de CRAN). Ambos deben estar instalados. putior verifica y proporciona mensajes útiles si faltan.
Ruta de R incorrecta en Claude Desktop: Las rutas de Windows necesitan escape en JSON (
```
\\
```
). Usar nombres cortos 8.3 para evitar espacios:
```
C:\\PROGRA~1\\R\\R-45~1.0\\bin\\x64\\Rscript.exe
```
.
Olvidar reiniciar: Claude Desktop debe reiniciarse después de editar el archivo de configuración. Claude Code recoge los cambios al iniciar la siguiente sesión.
Aislamiento de renv: Si putior está instalado en una biblioteca renv pero Claude Code/Desktop lanza R sin renv, los paquetes no se encontrarán. Asegurar que
```
mcptools
```
y
```
ellmer
```
estén instalados en la biblioteca global o configurar la activación de renv en el comando del servidor MCP.
Conflictos de puerto para ACP: El puerto ACP por defecto (8080) se usa comúnmente. Verificar con
```
lsof -i :8080
```
o
```
netstat -tlnp | grep 8080
```
antes de iniciar.
Incluir solo herramientas específicas: Para exponer un subconjunto de herramientas, usar
```
putior_mcp_tools(include = c("put", "put_diagram"))
```
al construir wrappers de servidor MCP personalizados.
Paletas personalizadas vía MCP: El parámetro
```
palette
```
en
```
put_diagram
```
requiere un objeto R
```
putior_theme
```
(creado por
```
put_theme()
```
), que no puede serializarse a través de la interfaz JSON de MCP. Usar el parámetro de cadena
```
theme
```
incorporado para llamadas MCP. Para paletas personalizadas, usar R directamente.

Habilidades Relacionadas

```
install-putior
```
-- prerrequisito: putior y dependencias opcionales deben estar instalados
```
configure-mcp-server
```
-- configuración general de servidor MCP para Claude Code/Desktop
```
troubleshoot-mcp-connection
```
-- diagnosticar problemas de conexión si las herramientas no aparecen
```
build-custom-mcp-server
```
-- construir servidores MCP personalizados que envuelvan herramientas de putior
```
analyze-codebase-workflow
```
-- usar herramientas MCP interactivamente para análisis de base de código