seo-api Checked

1. **Preflight.**

• Confirm the SE Ranking MCP is reachable. If not, emit:

     claude mcp add --transport http se-ranking https://api.seranking.com/mcp

and stop. See references/auth-and-keys.md for OAuth vs. X-Api-Key header tradeoffs and headless / CI patterns.

• Call DATA_getSubscription (0 credits). Record units_left, plan status, expiration — units_left is the figure to forecast against, and it gets printed in the cost forecast in step 5. Optionally also call DATA_getCreditBalance for its { limit, used } view — but the two are **not** aliases: they report different remaining-credit numbers that do not reconcile (an ~8.6M gap is normal), so treat getSubscription.units_left as the source of truth.

2. **Clarify the goal.** Ask 1–3 questions only if the goal is ambiguous. Skip when the user already spelled it out. Useful follow-ups:

• "Is this a one-off run, a recurring job (daily/weekly), or a long-lived integration in your product?"
• "Target country / language / device — or worldwide?"
• "Are we operating on a project you already own in SE Ranking, or just researching domains?"

3. **Identify the API surface(s).** Map the goal to one or both of:

• **Data API** — research-shaped data on any domain, no prior account setup. Credit-billed. See references/api-surface-map.md § "Data API surfaces".
• **Project API** — operations on the user's own SE Ranking projects (rank tracking, audits, AIRT, backlink groups, marketing plan, sub-accounts). Subscription-limit-billed, not credit-billed. Requires Business or Enterprise plan. See references/api-surface-map.md § "Project API surfaces".
• Many real integrations span both — e.g., a rank-tracker setup uses PROJECT_createProject + PROJECT_addKeywords + PROJECT_runPositionCheck, then reports use DATA_getDomainKeywords for the same domain.

4. **Map to tools / endpoints.** For every step in the integration, name:

• The MCP tool: ` DATA_getDomainKeywords or PROJECT_addKeywords `.
• The underlying REST endpoint + HTTP verb (e.g., GET /v1/domain/keywords).
• The credit cost (Data API) or limit consumed (Project API). Source costs from references/rate-limits-and-credits.md and the per-endpoint pages at seranking.com/api/data/* — MCP tool description fields carry input schemas and usage notes but **not** credit costs.
• If a tool needs an ID the user didn't supply (project ID, search engine ID, geo region name, language code), insert the prerequisite *list* or *available* call before it. See references/api-surface-map.md § "ID resolution".

5. **Forecast cost.** Sum credit cost across all Data API calls. For Project API calls, surface plan-limit impact (e.g., "this consumes 1 Site + 50 Keywords + ~500 Audit Pages from your plan"). Compare against:

• units_left from step 1 — if insufficient, surface and stop with the upgrade link.
• Plan limits if Project API tools are involved — PROJECT_getUserProfile returns current usage; flag if the integration would push a limit over.

6. **Pick execution mode.** Confirm with the user explicitly:

• **Code mode** — emit ready-to-paste cURL, Python (requests), TypeScript (fetch), and MCP-tool-call variants. The developer runs them. Default for read-only research, recurring jobs the user wants to own, and anything they want to deploy outside their Claude session.
• **Live mode** — execute the integration step by step via MCP. Confirm every mutating call. Default for one-off Project API setup (new project, add keywords, configure audit, set up AIRT prompt group, etc.) where the user wants the state to exist by the end of this conversation.
• **Hybrid** — wire up the one-time setup live, emit code for the recurring workload (e.g., "I created the project and added the 50 keywords for you; here's the daily-run Python script to pull positions and write them to BigQuery").

7. **Execute or emit.**

• **Code mode** — write code/curl.sh, code/python.py, code/typescript.ts, code/mcp-calls.md. Each file is a complete runnable example, not a fragment. Include error handling for 429 (rate limit) and 403 (insufficient credits). See references/integration-patterns.md for canonical pattern snippets.
• **Live mode** — for each *mutating* call (PROJECT_create*, PROJECT_add*, PROJECT_delete*, PROJECT_update*, DATA_createStandardAudit, DATA_createAdvancedAudit, etc.), print a single-line confirmation:

     About to call PROJECT_createProject(domain="acme.com", name="ACME Inc — Rank Tracker", country="us").
     Consumes: 1 "Site" from your subscription. Proceed? [y/N]

Wait for explicit y / yes. On anything else, fall back to code mode and emit the equivalent code instead of executing. Read-only calls (DATA_get*, DATA_list*, PROJECT_get*, PROJECT_list*) run without confirmation. Log every call to evidence/03-execution-log.md with timestamp, args, response status.

8. **Synthesise RECIPE.md.** Always written, regardless of mode. The deliverable a developer reads to understand what was built or how to build it. See output format below.

Output format

Folder seo-api-{slug}-{YYYYMMDD}/ where {slug} is a kebab-case summary of the goal (e.g., acme-rank-tracker, bulk-backlinks-bigquery).

seo-api-{slug}-{YYYYMMDD}/
├── RECIPE.md                       (primary deliverable — what was built or how to build it)
├── code/
│   ├── curl.sh                     (cURL one-liners + multi-step bash)
│   ├── python.py                   (idiomatic requests-based script)
│   ├── typescript.ts               (fetch + zod-validated responses)
│   └── mcp-calls.md                (MCP-tool-call sequence — same workflow, agent-native)
└── evidence/
    ├── 01-preflight.md             (credit balance, subscription status, MCP connectivity check)
    ├── 02-cost-forecast.md         (per-call cost breakdown, plan-limit deltas, total)
    ├── 03-ids-resolved.md          (Project API / search-engine IDs, geo codes resolved upfront — omit if none needed)
    └── 04-execution-log.md         (every MCP call executed, with args + status — omit in pure code mode where nothing ran)

Top-level: RECIPE.md + code/. The evidence/ folder preserves the reasoning trail; auditors lean on 02-cost-forecast.md and the execution log. 03 and 04 are conditional — a run with no ID lookups and no executed calls (pure code-mode advice) ships just 01 + 02.

RECIPE.md follows this shape:

# {