Setup

scout:setup — Guided Configuration

Purpose

Walk the user through configuring scout's optional search and fetching tools via interactive dialogue. Each step explains what the tool adds and lets the user decide.

Core Principle

"scout already works. These options make it stronger. The user chooses."

Transparency Protocol

Every configuration change must be visible before it happens. This builds trust and lets the user understand what scout is doing to their environment.

1. Show the diff before writing — Before editing .mcp.json or any config file, display the exact JSON block that will be added. Format: "Adding this to [file path]:" → fenced JSON block → then write. No extra confirmation needed — the step-level consent ("Install") already covers it.

2. Echo commands before running — Before executing shell commands (e.g., npx playwright install chromium, claude mcp add ..., pip install ...), display the command first. Format: "Running:" → fenced command block → then execute. Do NOT ask for separate confirmation here — the step-level consent already covers it.

3. State the footprint — For installs that add significant disk usage (e.g., Playwright ~200MB), state the approximate size before the user consents.

These rules apply to every step below. They do not add extra confirmation prompts — they make the existing prompts more informative.

Interaction Rules

• Respond in the user's language with dynamic equivalence — check the locale: line from the pre-check output (e.g. ja_JP → Japanese, es_ES → Spanish, en_US → English). ALL dialogue, explanations, step titles, and option descriptions MUST be in that language. Translate with dynamic equivalence (functional equivalence), not word-for-word. Prioritize natural, idiomatic phrasing that a native speaker would use — avoid translationese. Technical terms (API, MCP, Playwright, Context7, Jina Reader, Exa) stay in English. The English templates below are for content guidance only — NEVER output them as-is.
• Frame each tool as an upgrade, not a missing piece
• Every step is skippable — do not ask why if the user declines
• State facts about what each tool adds, not what's lost without it
• No excessive celebration on completion. A simple confirmation is enough
• Never install or configure anything without explicit consent

Pre-check

Before starting, diagnose the current state:

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
MCP_JSON="$PLUGIN_ROOT/.mcp.json"
VENV_DIR="$PLUGIN_ROOT/tools/.venv"

echo "=== scout setup status ==="

# jq check (required for configuration)
if ! command -v jq >/dev/null 2>&1; then
  echo "jq: NOT FOUND"
else
  echo "jq: ok"
fi

# System locale for language detection
echo "locale: $(defaults read -g AppleLocale 2>/dev/null || echo "${LANG:-en_US}")"

# Context7 (user-scoped MCP — check via claude CLI or config file)
if command -v claude >/dev/null 2>&1 && claude mcp list 2>/dev/null | grep -q context7; then
  echo "context7: configured"
elif [ -f "$HOME/.claude.json" ] && jq -e '.mcpServers.context7' "$HOME/.claude.json" > /dev/null 2>&1; then
  echo "context7: configured"
else
  echo "context7: not configured"
fi

# Jina Reader (configured = entry exists, with or without key)
if [ -f "$MCP_JSON" ] && jq -e '.mcpServers["jina-reader"]' "$MCP_JSON" > /dev/null 2>&1; then
  echo "jina: configured"
else
  echo "jina: not configured"
fi

# Exa (paid)
if [ -f "$MCP_JSON" ] && jq -e '.mcpServers.exa' "$MCP_JSON" > /dev/null 2>&1; then
  echo "exa: configured"
else
  echo "exa: not configured"
fi

# Playwright
if [ -f "$VENV_DIR/bin/python" ] && "$VENV_DIR/bin/python" -c "import playwright" 2>/dev/null; then
  echo "playwright: installed"
else
  echo "playwright: not installed"
fi

Run this check first. If jq: NOT FOUND, stop immediately and tell the user to install jq (brew install jq on macOS, apt install jq on Linux) before continuing — without jq, key configuration will fail silently. Present ALL four steps in order. For already-configured items, show them as a one-line confirmation (e.g. "Step 1/4 — Library & framework docs ✓ configured") and immediately move to the next step. Do not ask the user to act on configured items. If everything is already configured, tell the user and end setup.

Interaction Flow

CRITICAL: This is a multi-turn dialogue. You MUST present only ONE step per response, then STOP and wait for the user's reply. Do NOT mention, preview, or summarize upcoming steps.

The flow is:

1. Run pre-check
2. Present Step 1 (Context7). If already configured, show "Step 1/4 — ... ✓ configured" as a one-liner, then immediately present Step 2 in the SAME response. If unconfigured, present the full step and STOP.
3. User responds (provides key, says "skip", "private", asks a question, etc.)
4. Handle the response (configure, skip, or show manual instructions). Then present the NEXT step — again, if configured show one-liner and continue to the next unconfigured step. Then STOP.
5. Repeat until all items are addressed.
6. Run "After Setup" once.

"private" response handling

If the user says "private" for any API key step (Jina or Exa), show them the file path and the JSON to add, so they can edit it themselves without the key passing through the conversation.

If .mcp.json does not exist yet, tell the user to create it first:

cp ${CLAUDE_PLUGIN_ROOT}/.mcp.json.dist ${CLAUDE_PLUGIN_ROOT}/.mcp.json

Then show what to add:

File: ${CLAUDE_PLUGIN_ROOT}/.mcp.json

# For Jina Reader, add this to mcpServers:
"jina-reader": {
  "type": "http",
  "url": "https://mcp.jina.ai/v1",
  "headers": { "Authorization": "Bearer YOUR_KEY_HERE" }
}

# For Exa, add this to mcpServers:
"exa": {
  "type": "http",
  "url": "https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY_HERE&tools=web_search_advanced_exa,crawling_exa,company_research_exa,people_search_exa,deep_researcher_start,deep_researcher_check"
}

Tell the user to edit the file, then say "done" when finished. Confirm by re-running the pre-check for that item.

Tone guidance

Write as if you're a colleague helping someone set up their tools — casual, brief, no marketing speak. Do NOT translate English templates literally. Adapt naturally to the user's language and culture. Always output the numbered options as a numbered list — do NOT merge them into a paragraph.

Framing rules

• Always use gain framing — state what the user GETS, not what they AVOID. "key stays in your environment" is correct; "key won't appear in the conversation" is loss-avoidance framing and MUST NOT be used.
• No unverifiable claims — "more accurate" or "better results" without a concrete mechanism is overclaiming. Instead, describe what changes observably: "returns just the content as clean text, so the model often has fewer tokens to process."
• "Already works" must come first — every step must open by stating what scout already does. The tool strengthens this.
• Honest delta — describe mechanism, not outcome — state what the tool concretely adds ("searches by meaning, not just keywords") instead of evaluating the result ("better search"). Additive language ("adds", "extends") is fine. Banned: "unlocks", "lets you...", "〜できるようになります", "〜に対応しています" — these imply current capabilities are locked.
• Skip option must be procedural, not evaluative — state what happens ("scout uses its built-in search"), not how good it is ("works fine without it"). The latter triggers the "protesting too much" effect. Add reversibility: "you can add this later."

Japanese translation pitfalls (check your output against these)

Product name introduction rule

When mentioning a product/service name for the FIRST time, anchor the name to a known category. The order differs by language:

• Japanese/Korean/Chinese: category BEFORE the name — e.g. "ページ読み取りサービスの Jina Reader", "セマンティック検索サービスの Exa"
• English/European: name first, then context — e.g. "Jina Reader, a page-reading service", "Exa, a semantic search service"

On subsequent mentions, use the name alone.

What to say for each item

Step 1 — Context7 (present first if unconfigured):

Convey this (adapt to user's language, do NOT copy verbatim):

Step 1/4 — Library & framework docs scout searches the web for technical questions. Context7, a documentation index, adds a direct path to official library and framework docs (React, Prisma, Next.js, etc.) — less time digging through SEO pages, more time on the actual API docs. The indexed content matches the latest published version. No API key needed.

1. Install — one command, done in seconds
2. Skip — scout uses web search for docs. You can add this later

If user consents, run:

claude mcp add --transport http -s user context7 https://mcp.context7.com/mcp

If the command fails (e.g. claude not in PATH), show the manual alternative:

Run this in your terminal:
claude mcp add --transport http -s user context7 https://mcp.context7.com/mcp

Confirm briefly, then move to next item.

Step 2 — Jina Reader (present if unconfigured):

Convey this (adapt to user's language, do NOT copy verbatim):

Step 2/4 — Cleaner web page reading scout fetches web pages as-is, including ads and navigation. Jina Reader, a page-reading service, strips those out and returns just the content as clean text, which often means less text reaches the model and fewer tokens are used. It works without a key for lighter usage. Add a key if you want higher rate limits: https://jina.ai/?newKey

1. Paste a key — I'll handle the rest
2. Set it up myself — I'll show you the file to edit (key stays in your environment only)
3. Skip — scout fetches pages as raw HTML. You can add this later

If user provides a key, configure it:

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
MCP_JSON="$PLUGIN_ROOT/.mcp.json"
MCP_DIST="$PLUGIN_ROOT/.mcp.json.dist"

if [ ! -f "$MCP_JSON" ]; then
  cp "$MCP_DIST" "$MCP_JSON"
fi

jq --arg key "JINA_KEY" \
  '.mcpServers["jina-reader"] = {
    "type": "http",
    "url": "https://mcp.jina.ai/v1",
    "headers": { "Authorization": ("Bearer " + $key) }
  }' "$MCP_JSON" > "$MCP_JSON.tmp" && mv "$MCP_JSON.tmp" "$MCP_JSON"
chmod 600 "$MCP_JSON"

Confirm briefly, then move to next item.

Step 3 — Exa (present if unconfigured):

Convey this (adapt to user's language, do NOT copy verbatim):

Step 3/4 — Meaning-based web search scout searches the web without any extra keys. Exa, a semantic search service, searches by meaning, not just keywords — useful when you're not sure of the exact terms and want relevant niche sources sooner. Key here: https://exa.ai

1. Paste a key — I'll handle the rest
2. Set it up myself — I'll show you the file to edit (key stays in your environment only)
3. Skip — scout uses keyword search. You can add this later

Japanese example (use as reference, adapt naturally):

ステップ 3/4 — 意味ベースのウェブ検索 scout はキーなしでもウェブ検索できます。セマンティック検索サービスの Exa は、キーワードではなく意味で検索します。正確な言葉が分からないときに有効です。キーはこちら: https://exa.ai

1. キーを貼り付ける — あとはこちらで設定します
2. 自分で設定する — 編集先のファイルを案内します（キーは手元の環境にのみ保存されます）
3. スキップ — scout はキーワード検索を使います。あとで追加できます

If user provides a key, configure it:

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
MCP_JSON="$PLUGIN_ROOT/.mcp.json"
MCP_DIST="$PLUGIN_ROOT/.mcp.json.dist"

if [ ! -f "$MCP_JSON" ]; then
  cp "$MCP_DIST" "$MCP_JSON"
fi

jq --arg key "EXA_KEY" \
  '.mcpServers.exa = {
    "type": "http",
    "url": ("https://mcp.exa.ai/mcp?exaApiKey=" + $key + "&tools=web_search_advanced_exa,crawling_exa,company_research_exa,people_search_exa,deep_researcher_start,deep_researcher_check")
  }' "$MCP_JSON" > "$MCP_JSON.tmp" && mv "$MCP_JSON.tmp" "$MCP_JSON"
chmod 600 "$MCP_JSON"

Confirm briefly, then move to next item.

Step 4 — Playwright (present last if not installed):

Convey this (adapt to user's language, do NOT copy verbatim):

Step 4/4 — Handling interactive pages scout fetches pages via API. Playwright runs a real browser locally — it handles JavaScript-rendered content (SPAs, dashboards) and keeps confidential URLs on your machine, so private pages stay local. Needs ~200MB for Chromium.

1. Install
2. Skip — scout fetches via API (no JS rendering). You can add this later

If user consents:

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}"
VENV_DIR="$PLUGIN_ROOT/tools/.venv"
python3 -m venv "$VENV_DIR" && \
  "$VENV_DIR/bin/pip" install --quiet playwright && \
  "$VENV_DIR/bin/playwright" install chromium

If the install fails, show the manual commands and move on. Do not retry.

After Setup

1. Run /mcp to reload MCP servers so the new configurations take effect. Do this yourself — do not ask the user to do it. If /mcp cannot be executed programmatically, tell the user to type /mcp to complete the setup.

2. Write the setup status flag:

STATE_DIR="${CLAUDE_PLUGIN_DATA:-${XDG_STATE_HOME:-$HOME/.local/state}/scout}"
mkdir -p "$STATE_DIR"
cat > "$STATE_DIR/setup-status.json" << 'STATUSEOF'
{"complete": true}
STATUSEOF

3. Show a brief summary of what was configured.

4. Propose a demo search to try out the configured tools. Suggest one of these queries that showcase scout's strength — where query redesign makes a clear difference:

   • "I want something like Git blame but for design decisions" — scout translates this concept into the right term (ADR) and reaches primary sources, while a plain keyword search returns git blame tutorials
   • "What should I actually migrate to from Terraform — not the sponsored lists, real migration stories" — scout filters past SEO noise to find real experience reports

   Let the user pick one, or suggest their own topic. If they decline, move on.