open-seo: Skill for Claude Code

Verify local MCP

Two layers, in order. The protocol layer proves the server and provider behave; the consumer layer proves an agent that has never seen the code can use the tools well. They catch different bugs — protocol testing found DataForSEO quirks (zoom-dependent empty SERPs), the consumer probe found ergonomics failures (9KB provider rows overflowing client token budgets, fractional inputs rejected upstream with raw provider errors). Do both.

1. Boot

• .env.local needs AUTH_MODE=local_noauth and DATAFORSEO_API_KEY (base64 of login:password). Never print the key.
• Start pnpm dev:agents in the background. The server URL is branch-prefixed: http://<branch-suffix>.open-seo.localhost:1355 (the exact URL is printed on boot; logs tee to .logs/dev-server.log).
• With local_noauth, /mcp needs no token. Vite hot-reloads server code, so fix → re-call without restarting.
• After changing a tool's input or output schema, refresh the client's tool discovery (tools/list) or reconnect the MCP client before calling it again. Clients can cache validators from the previous tool list and reject valid results after the provider call has already incurred a charge.

2. Protocol smoke (cheap, deterministic)

Raw JSON-RPC against /mcp — the layer for asserting exact shapes and driving edge cases (resume taskIds, empty results, invalid inputs):

curl -sS http://<url>/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# tools/call: {"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}

• Bootstrap: list_projects, then create_project if empty — most tools need a projectId.
• Test the happy path AND at least one edge per changed tool: an empty result (obscure query), an invalid identifier, and for queued tools the full lifecycle including resuming with the returned taskId.
• These are real, billed DataForSEO calls (metering itself short-circuits in local_noauth — billing needs unit tests, not this). Keep depths 10–20.