minimax-cli-web-search

Original source / Raw SKILL.md

---
name: minimax-cli-web-search
description: Web search via MiniMax MCP using a local CLI wrapper (mcporter), with environment preflight, API-key/config checks, and normalized result formatting. Use when tasks require real-time web lookup, source links, quick research, or time-sensitive facts. Prefer this skill over built-in web search tools when MiniMax MCP is available.
---

# MiniMax CLI Web Search

Use this skill to run web search through MiniMax MCP from CLI, then return clean, source-first results.

## Phase 1: Environment Preparation (must run first)

### 1) Preflight checks
Run:

```bash
scripts/minimax_web_search.sh --preflight
```

This verifies:
- `mcporter` exists
- MiniMax MCP server is discoverable (`mcporter list --json`)
- Server status is healthy (`name=minimax`, `status=ok`)

### 2) If preflight fails, repair by failure type
- `mcporter not found`
  - Install/setup mcporter in PATH.
- `minimax MCP server not ready`
  - Check `config/mcporter.json` includes minimax server.
  - Verify command/transport is valid.
- Auth/API-key related errors
  - Ensure MiniMax API key is configured for the minimax MCP server.
  - Re-run preflight.

### 3) Initiate / smoke test
Run one query after preflight passes:

```bash
scripts/minimax_web_search.sh --query "latest OpenClaw release" --count 3
```

If this returns results, environment is ready.

---

## Phase 2: Search Usage (runtime)

### Quick usage

```bash
scripts/minimax_web_search.sh --query "your query" --count 5
```

### Supported options
- `--query <text>`: required search query
- `--count <n>`: max printed results (default `5`)
- `--freshness <value>`: freshness hint appended to query (optional)
- `--json`: normalized JSON output
- `--raw`: raw tool JSON output
- `--timeout <sec>`: command timeout (default `35`)

### Output contract (default text)
- Show top-N results in order
- For each item: title, URL, snippet, date (when available)
- Keep output concise and directly actionable

### Agent behavior guideline
1. Start with a focused query (3–7 keywords).
2. If low quality, rephrase once with narrower terms.
3. Return key findings + links (no table required).
4. For time-sensitive asks, include time words in query (e.g., `today`, `latest`, date).

---

## Error model (for reliable automation)

Script exit codes:
- `0`: success
- `2`: argument error
- `3`: dependency missing (`mcporter`/`python3`)
- `4`: config/auth issue (MCP server unavailable, API key/auth problems)
- `5`: upstream/runtime/network failure
- `6`: no results (non-fatal)

Treat code `6` as a normal “no match” outcome, not a crash.

---

## Risks and handling

1. **CLI/config drift across machines**
   - Use `--preflight` before first use in a new environment.
2. **API key exposure risk**
   - Never print key values; report only missing/invalid status.
3. **Temporary file safety**
   - Wrapper uses `mktemp` for stderr/output temp files and cleans them with `trap`.
3. **Upstream response variance**
   - Use `--json` normalized output for downstream automation.
4. **Timeout/network instability**
   - Increase `--timeout` and retry with narrower query/count.
5. **Weak relevance**
   - Rephrase query, add concrete entities/time ranges.

---

## Additional reference

- For setup/verification commands and publish readiness checks, read:
  - `references/environment-checklist.md`

## Reference style

When presenting findings, include direct links for verification. Prefer 3–5 high-signal sources over large dumps.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/minimax_web_search.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

# minimax_web_search.sh
# Wrapper for: mcporter call minimax.web_search query="..."

print_help() {
  cat <<'EOF'
Usage:
  minimax_web_search.sh --query "your query" [options]

Options:
  --query <text>          Search query (required)
  --count <n>             Max items to print (default: 5)
  --freshness <value>     Optional freshness hint (e.g. pd/pw/pm/py or date phrase)
  --json                  Print normalized JSON instead of plain text
  --raw                   Print raw mcporter JSON result
  --preflight             Run environment checks only
  --timeout <seconds>     Max runtime seconds for mcporter call (default: 35)
  --help                  Show this help

Exit codes:
  0 success
  2 invalid arguments
  3 dependency missing (mcporter/python3)
  4 configuration/auth issue
  5 upstream/network/runtime error
  6 no results (non-fatal)
EOF
}

QUERY=""
COUNT=5
FRESHNESS=""
OUT_MODE="text"   # text | json | raw
PREFLIGHT_ONLY=0
TIMEOUT_SECONDS=35

while [[ $# -gt 0 ]]; do
  case "$1" in
    --query)
      QUERY="${2:-}"
      shift 2
      ;;
    --count)
      COUNT="${2:-}"
      shift 2
      ;;
    --freshness)
      FRESHNESS="${2:-}"
      shift 2
      ;;
    --json)
      OUT_MODE="json"
      shift
      ;;
    --raw)
      OUT_MODE="raw"
      shift
      ;;
    --preflight)
      PREFLIGHT_ONLY=1
      shift
      ;;
    --timeout)
      TIMEOUT_SECONDS="${2:-}"
      shift 2
      ;;
    --help|-h)
      print_help
      exit 0
      ;;
    *)
      echo "[ERR] Unknown argument: $1" >&2
      print_help >&2
      exit 2
      ;;
  esac
done

if ! command -v python3 >/dev/null 2>&1; then
  echo "[ERR] python3 is required" >&2
  exit 3
fi

if ! command -v mcporter >/dev/null 2>&1; then
  echo "[ERR] mcporter not found. Install/configure mcporter first." >&2
  exit 3
fi

if ! [[ "$COUNT" =~ ^[0-9]+$ ]] || [[ "$COUNT" -lt 1 ]]; then
  echo "[ERR] --count must be a positive integer" >&2
  exit 2
fi

if ! [[ "$TIMEOUT_SECONDS" =~ ^[0-9]+$ ]] || [[ "$TIMEOUT_SECONDS" -lt 1 ]]; then
  echo "[ERR] --timeout must be a positive integer" >&2
  exit 2
fi

LIST_ERR=$(mktemp)
TMP_OUT=$(mktemp)
TMP_ERR=$(mktemp)
trap 'rm -f "$LIST_ERR" "$TMP_OUT" "$TMP_ERR"' EXIT

# Preflight: verify minimax server is visible in mcporter list
if ! LIST_JSON=$(mcporter list --json 2>"$LIST_ERR"); then
  echo "[ERR] Failed to run 'mcporter list --json'" >&2
  sed -n '1,80p' "$LIST_ERR" >&2 || true
  exit 4
fi

if ! python3 - "$LIST_JSON" <<'PY'
import json, sys
raw = sys.argv[1]
obj = json.loads(raw)
servers = obj.get("servers", [])
ok = any(s.get("name") == "minimax" and s.get("status") == "ok" for s in servers)
if not ok:
    print("[ERR] minimax MCP server not ready. Check config/mcporter.json and API key.", file=sys.stderr)
    sys.exit(1)
PY
then
  exit 4
fi

if [[ "$PREFLIGHT_ONLY" -eq 1 ]]; then
  echo "[OK] Preflight passed: mcporter + minimax MCP are available."
  exit 0
fi

if [[ -z "$QUERY" ]]; then
  echo "[ERR] --query is required (unless using --preflight)" >&2
  exit 2
fi

# minimax.web_search currently requires only query; freshness is appended into query hint.
QUERY_EFF="$QUERY"
if [[ -n "$FRESHNESS" ]]; then
  QUERY_EFF="$QUERY (freshness: $FRESHNESS)"
fi

if ! timeout "$TIMEOUT_SECONDS" mcporter call minimax.web_search query="$QUERY_EFF" >"$TMP_OUT" 2>"$TMP_ERR"; then
  echo "[ERR] web_search call failed" >&2
  sed -n '1,80p' "$TMP_ERR" >&2 || true
  if grep -Eiq 'auth|apikey|api key|unauthorized|forbidden|401|403' "$TMP_ERR"; then
    exit 4
  fi
  exit 5
fi

if [[ "$OUT_MODE" == "raw" ]]; then
  cat "$TMP_OUT"
  exit 0
fi

if [[ "$OUT_MODE" == "json" ]]; then
  python3 - "$TMP_OUT" "$COUNT" <<'PY'
import json, sys
path, count = sys.argv[1], int(sys.argv[2])
raw = open(path, 'r', encoding='utf-8').read()
obj = json.loads(raw)
organic = obj.get('organic') or []
out = {
  'query': obj.get('query'),
  'count': min(count, len(organic)),
  'results': [
    {
      'title': r.get('title', '').strip(),
      'url': r.get('link', '').strip(),
      'snippet': (r.get('snippet', '') or '').strip(),
      'date': (r.get('date', '') or '').strip(),
    }
    for r in organic[:count]
  ],
  'related_searches': [x.get('query') for x in (obj.get('related_searches') or []) if x.get('query')],
}
print(json.dumps(out, ensure_ascii=False, indent=2))
PY
  if [[ $(python3 - "$TMP_OUT" <<'PY'
import json,sys
o=json.loads(open(sys.argv[1],encoding='utf-8').read())
print(len(o.get('organic') or []))
PY
) -eq 0 ]]; then
    exit 6
  fi
  exit 0
fi

# text mode
python3 - "$TMP_OUT" "$COUNT" <<'PY'
import json, sys
path, count = sys.argv[1], int(sys.argv[2])
obj = json.loads(open(path, 'r', encoding='utf-8').read())
organic = obj.get('organic') or []
if not organic:
    print("No results.")
    sys.exit(6)
print("Top results:")
for i, r in enumerate(organic[:count], 1):
    t = (r.get('title') or '').strip() or '(no title)'
    u = (r.get('link') or '').strip()
    s = (r.get('snippet') or '').strip()
    d = (r.get('date') or '').strip()
    print(f"{i}. {t}")
    if d:
      print(f"   Date: {d}")
    if u:
      print(f"   URL: {u}")
    if s:
      print(f"   Snippet: {s}")
PY
rc=$?
if [[ $rc -eq 6 ]]; then
  exit 6
fi
exit 0

```

### references/environment-checklist.md

```markdown
# Environment Checklist

## 1) Verify CLI

```bash
command -v mcporter
mcporter --help
```

## 2) Verify minimax MCP registration

```bash
mcporter list --json
```

Expected:
- server named `minimax`
- `status: ok`
- tool includes `web_search`

## 3) Verify search call

```bash
mcporter call minimax.web_search query="latest AI news"
```

If auth/config error appears:
- verify API key placement in MCP server config
- verify the server command/transport
- retry after fixing config

## 4) Wrapper smoke test

```bash
scripts/minimax_web_search.sh --preflight
scripts/minimax_web_search.sh --query "OpenClaw GitHub" --count 3
scripts/minimax_web_search.sh --query "nonexistent-query-zzz" --count 3
```

## 5) Publish readiness

- SKILL frontmatter name/description complete
- script executable (`chmod +x`)
- package command succeeds

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "biggersun",
  "slug": "minimax-cli-web-search",
  "displayName": "MiniMax CLI Web Search",
  "latest": {
    "version": "0.1.1",
    "publishedAt": 1771849618786,
    "commit": "https://github.com/openclaw/skills/commit/40ec9f1f0d56196d35aa81e3703f4af2b20f68d5"
  },
  "history": [
    {
      "version": "0.1.0",
      "publishedAt": 1771848625695,
      "commit": "https://github.com/openclaw/skills/commit/e316e30c0f1b594b9b37df2f5f5d9de444a92de0"
    }
  ]
}

```