pencil-setup

Pencil Setup

Auto-detect, install, and register the Pencil MCP server with Claude Code CLI.

Prerequisite: One of: (1) the headless CLI (no GUI required, recommended for agents), (2) Pencil Desktop, or (3) an IDE (Cursor/VS Code) with the Pencil extension.

Known limitation: macOS detection uses unverified bundle ID dev.pencil.desktop -- falls back to PATH-based detection if incorrect.

Phase 0: Dependency Check

Run [check_deps.sh](./scripts/check_deps.sh) before proceeding. When invoked from a pipeline (e.g., one-shot), pass --auto to skip interactive prompts, auto-install the IDE extension, and auto-launch Pencil Desktop.

For interactive use:

bash ${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}/skills/pencil-setup/scripts/check_deps.sh

For pipeline/automated use:

bash ${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}/skills/pencil-setup/scripts/check_deps.sh --auto

If the script exits non-zero, no Pencil MCP source is available. Stop and inform the user with the printed instructions (both Desktop and IDE options).

If all checks pass, capture these values from the script output:

• PREFERRED_MODE -- headless_cli, cli, desktop_binary, or ide
• PREFERRED_BINARY -- path to binary (adapter for headless, pencil for CLI mode)
• PREFERRED_APP -- --app flag value (empty for CLI and headless modes)
• PREFERRED_NODE -- (headless_cli only) path to Node >= 22.9.0 binary

Proceed to Step 1.

Step 1: Check if Already Registered

<!-- verified: 2026-04-19 source: claude mcp list --help (the -s flag was dropped from list; plain claude mcp list now includes user-scoped entries) -->

claude mcp list 2>&1 | grep -q "pencil" && echo "REGISTERED" || echo "NOT_REGISTERED"

If REGISTERED, classify the existing registration mode by inspecting the binary path printed by claude mcp list:

existing=$(claude mcp list 2>&1 | grep pencil)
case "$existing" in
  *pencil-mcp-adapter*|*@pencil.dev/cli*|*pencil-cli*) existing_mode=headless_cli ;;
  *visual_studio_code*|*cursor*)                       existing_mode=ide ;;
  *--app\ pencil*|*mcp-server-*-x64*)                   existing_mode=desktop ;;
  *)                                                   existing_mode=unknown ;;
esac

Auto-upgrade rule (when --auto is set): if existing_mode is ide or desktop AND Phase 0 set PREFERRED_MODE=headless_cli, the existing registration is unsuitable for agent-driven flows (no programmatic save — see Sharp Edges §"No programmatic save"). Remove and re-register as headless instead of stopping:

if [[ "$AUTO_INSTALL" == "true" && "$existing_mode" != "headless_cli" && "$PREFERRED_MODE" == "headless_cli" ]]; then
  echo "Upgrading Pencil MCP from $existing_mode → headless_cli (agent-driven flows require programmatic save)"
  claude mcp remove pencil -s user 2>/dev/null || true
  # Fall through to Step 2 to register fresh
else
  # Verify the registered binary path still exists on disk before declaring "ready".
  # Extract the path from `claude mcp list` output, then `test -f <path>`.
  case "$existing_mode" in
    headless_cli) echo "Pencil MCP is already configured via headless CLI adapter. Restart Claude Code for tools to become available." ;;
    desktop)      echo "Pencil MCP is already configured. Make sure Pencil Desktop is running, then restart Claude Code." ;;
    ide)          echo "Pencil MCP is already configured. Make sure your IDE is running with Pencil active, then restart Claude Code. NOTE: IDE mode does not auto-save .pen edits — use --auto to upgrade to headless if running agent-driven flows." ;;
    *)            echo "Pencil MCP is registered but mode could not be classified. Re-run with --auto to refresh registration." ;;
  esac
  # Stop here unless --auto-upgrading.
fi

If the path does not exist, NOT_REGISTERED, or the auto-upgrade path was taken, continue to Step 2.

Step 2: Register MCP Server

Registration varies by PREFERRED_MODE from Phase 0:

Remove any existing registration first:

claude mcp remove pencil -s user 2>/dev/null

Headless CLI mode (PREFERRED_MODE=headless_cli)

First, sync the repo adapter into the user's install location so stale installed copies don't mask repo-level fixes (see #2630):

bash ${CLAUDE_PLUGIN_ROOT:-plugins/soleur}/skills/pencil-setup/scripts/copy_adapter.sh

The adapter requires PENCIL_CLI_KEY in the MCP environment. Retrieve the key, then register with -e before the -- separator:

# Retrieve the key (Doppler, or use pencil login token)
PENCIL_KEY=$(doppler secrets get PENCIL_CLI_KEY -p soleur -c dev --plain 2>/dev/null)
# If Doppler is not available, check for a stored login token:
# PENCIL_KEY=$(cat ~/.config/pencil/auth.json 2>/dev/null | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

claude mcp add pencil -s user -e PENCIL_CLI_KEY="$PENCIL_KEY" -- <PREFERRED_NODE> <PREFERRED_BINARY>

Replace <PREFERRED_NODE> with the Node 22+ binary path and <PREFERRED_BINARY> with the adapter path from Phase 0.

Critical: The -e flag must appear before --. Placing it after -- passes it as a CLI arg to the adapter instead of setting an environment variable, causing silent auth failures.

Drift check. If the adapter ever appears to "silently drop" operations, verify the installed copy is in sync with the repo:

bash ${CLAUDE_PLUGIN_ROOT:-plugins/soleur}/skills/pencil-setup/scripts/check_deps.sh --check-adapter-drift
# On DRIFT, re-sync: add --auto, or re-run copy_adapter.sh

CLI mode (PREFERRED_MODE=cli)

claude mcp add -s user pencil -- pencil mcp-server

No --app flag needed -- the CLI handles connection internally.

Desktop binary mode (PREFERRED_MODE=desktop_binary)

claude mcp add -s user pencil -- <PREFERRED_BINARY> --app <PREFERRED_APP>

Replace <PREFERRED_BINARY> and <PREFERRED_APP> with values from Phase 0.

IDE mode (PREFERRED_MODE=ide)

claude mcp add -s user pencil -- <PREFERRED_BINARY> --app <PREFERRED_APP>

Replace <PREFERRED_BINARY> with the extension binary path and <PREFERRED_APP> with cursor or visual_studio_code.

Step 3: Verify

claude mcp list 2>&1 | grep pencil

If the pencil entry appears, tell the user:

• Headless CLI mode: "Pencil MCP registered via headless adapter. Restart Claude Code for tools to become available. No GUI required."
• CLI/Desktop mode: "Pencil MCP registered. Restart Claude Code for tools to become available. Make sure Pencil Desktop is running."
• IDE mode: "Pencil MCP registered. Restart Claude Code for tools to become available. Make sure your IDE is open with Pencil active."

If it does not appear, tell the user the registration failed and suggest running the commands manually.

Untracked .pen safety

Rule cq-before-calling-mcp-pencil-open-document is canonical in .claude/hooks/pencil-open-guard.sh header (see that file for the full body and rationale). The hook is a PreToolUse deny on untracked .pen files; pre-flight to avoid the deny:

git -C <repo> ls-files --error-unmatch <path>   # exit 0 = tracked, exit 1 = untracked

For freshly-created .pen files, commit an empty or scaffold placeholder before the first open_document call.

Tracked .pen collapse recovery

Rule cq-pencil-collapse-auto-recover is canonical in the .claude/hooks/pencil-collapse-guard.sh header [hook-enforced: pencil-collapse-guard.sh]. It is the deterministic backstop for the open_document truncation bug (#3274 / upstream #4859): the PreToolUse pencil-open-guard.sh only denies untracked .pen, and the ux-design-lead / brand-workshop prose HARD-GATEs (PR #4855) rely on agent discipline.

The hook fires PostToolUse on mcp__pencil__open_document. When the on-disk .pen has collapsed to the unambiguous empty-document shape ({"version":"...","children":[]} or a 0-byte/whitespace truncation) while