sdks LIVE

the agent client: MCP LIVE

The closest thing to an SDK in the shinnslist codebase: seven task tools over JSON-RPC 2.0 at POST /api/mcp (find_parcels, town_stats, check_parcel, list_coverage, list_signals, explain_grading, run_signal). Protocol revision 2026-07-28 (MCP_PROTOCOL_VERSION in functions/lib/mcp.js) and, since 2026-10-17, the legacy initialize handshake too, so today's clients connect; no session ids. Server identity: MCP_SERVER_NAME = 'shinnslist', MCP_SERVER_VERSION = '0.2.0'. Three methods, all re-derived from the handler: server/discover, tools/list, tools/call. Tool names are the kebab-case of the signal id (toolName() in scripts/gen-docs.mjs — e.g. well-depth-drill-cost).

Auth: the shared resolver in functions/lib/api-keys.js reads the x-api-key header (line 80) or ?key= (line 82) — same key as the REST api. Quota: run_signal (and the old per-signal names) counts as one intel call against the same daily quota; the six aggregate tools, server/discover and tools/list are free (functions/api/mcp.js header comment). Error codes, verbatim from functions/lib/mcp.js: -32700 parse error · -32600 invalid request · -32601 unknown method/tool · -32001 invalid api key · -32002 rate limited · -32003 daily quota exceeded · -32004 signal not entitled · -32005 outside Virginia.

Full method-by-method reference: mcp for agent builders.

copy-paste code that works today LIVE

The chat page ships real snippet generators (chat.html: apiSnippetLangsV1(), apiSnippetForCallV1(origin, call, lang)). Three languages — curl, python, javascript — a language picker renders the exact request each disclosed call made. The URL contract is byte-identical to slice 1's apiCallPathV1(signal, zip): /api/engine/<signal>?zip=<encodeURIComponent(zip)>. Every snippet is a plain GET — no headers, no api key, no body. Unknown language ids fall back to curl (apiSnippetLangV1); a tampered call renders the honest could not verify this call — snippet withheld note instead of a fabricated snippet.

Verbatim output of the generators for assumable / 22902 (base URL https://shinnslist.com from scripts/gen-docs.mjs):

# GET assumable · 22902
curl "https://shinnslist.com/api/engine/assumable?zip=22902"

# GET assumable · 22902
# shinnslist engine api — plain GET, no api key
import requests  # pip install requests

url = "https://shinnslist.com/api/engine/assumable?zip=22902"
response = requests.get(url)
print(response.status_code)
print(response.json())

// GET assumable · 22902
// shinnslist engine api — plain GET, no api key
const url = "https://shinnslist.com/api/engine/assumable?zip=22902";
const res = await fetch(url);
console.log(res.status, await res.json());

The comment headers (# GET <signal> · <zip> / // GET <signal> · <zip>) are added by apiSnippetHeadV1(call, lang), one block per call. Generate your own live in chat: run an engine query, open "take this api call into your code", pick a language.

typed javascript + python clients DRAFT

Planned: two typed clients — javascript and python — thin wrappers over the REST api and MCP tools, covering every live signal. Package names, repository names, and versioning are not final, so we do not print install commands here: anything you see elsewhere claiming an install command is guessing. The real install commands ship on this page, the day the packages publish.

Planned guarantees, all draft: every function maps 1:1 to a documented REST endpoint or MCP tool; typed inputs and outputs (no raw dicts/untyped json); built-in retry with backoff, auth from one api key, and quota headers surfaced. Function and method names are not final, so no client calls are shown here.

llms.txt / agent-readable docs

/llms.txt (since 2026-10-16) is the plain summary for AI agents: what shinnslist is, what is real today, its beta status and how to use it, rewritten from the site's own records at every deploy (site/scripts/gen-agent-pages.mjs). It describes the site, not this api: the signal catalog, method names and example calls are still not in one fetchable file, so the mcp reference stays the agent integration surface.

what works today: call the api directly

Until the typed SDKs ship, plain http does everything. The getting started guide walks through your first parcel query; the api reference lists every live signal; the mcp reference is the agent path. A raw query looks like this:

curl -s "https://shinnslist.com/api/intel?q=37.5407,-77.4360" \
  -H "x-api-key: YOUR_KEY" | jq '.signals | keys'

Free tier gets 25 calls a day per key — enough to build on while the clients are on the roadmap.