audubon-iba-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Audubon IBA fork. This is a National Audubon Society Important Bird Areas fork of the OpenContext MCP server framework (forked from the San Diego City GIS fork). It serves Audubon's public IBA feature service via the audubon_iba plugin (see config.yaml).

Unlike the sibling GIS forks, this one fronts a single fixed ArcGIS FeatureServer with a known schema — not a portal or services directory. There is nothing to crawl, so all the catalog-discovery machinery is gone: no search_datasets, no get_aggregations, no catalog manifest, no dataset-id resolution. Every tool addresses layer 0 (or one of its related tables) directly.

https://services1.arcgis.com/lDFzr3JyGEn5Eymu/arcgis/rest/services/iba_polygons_public/FeatureServer
  layer 0   iba_polygons_public  -- the main IBA polygon record
  tables    3 criteria_site   4 criteria_species   5 habitat    6 landuse
            7 observation     8 ownership          9 site_description
           10 species        11 threat

Key invariants of the audubon_iba plugin:

• Six tools, no discovery — find_ibas_near_point, search_ibas, get_iba_details, get_iba_related_records, get_iba_boundary, list_distinct_values, under the audubon_iba__ prefix.
• Geometry is opt-in — every tool but get_iba_boundary sends returnGeometry=false, so the shared pager (_query_layer_paged) hardcodes it. get_iba_boundary has its own request path and simplifies server-side with maxAllowableOffset (in degrees, since outSR=4326).
• WGS84 hard contract — the polygons are authored in EPSG:3857 (Web Mercator); every query sets inSR=4326/outSR=4326 and lets the service reproject. Without inSR, WGS84 coords are read as Web Mercator metres and silently match nothing. find_ibas_near_point adds a server-side buffer (distance + units=esriSRUnit_Kilometer).
• Runtime schema introspection — layer 0's fields, coded-value domains, record cap, and relationship ids are read from the service at runtime (?f=json) and cached per instance. Nothing is hardcoded beyond the fields the tools name. Related tables are introspected separately, so their dates/domains decode against their own schema.
• relationshipId != relatedTableId — queryRelatedRecords takes the relationship's id (0–8), not the related table's id (3–11). The plugin resolves the id from live metadata by relationship name; hardcoding the number would silently query the wrong table.
• site_id is not objectid — queryRelatedRecords keys on the origin layer's objectid, so get_iba_related_records resolves site_id -> objectid first (which doubles as the existence check).
• Pagination — maxRecordCount is 2000; both /query and /queryRelatedRecords page with resultOffset/resultRecordCount.
• No free-form SQL surface — callers pass values (state, priority, flyway, name), never a WHERE clause. Values are quote- and LIKE-wildcard-escaped into fixed predicates, and the composed clause still goes through WhereValidator (shared from plugins/arcgis/where_validator.py). Field names in list_distinct_values are validated against the live schema before interpolation.
• Auth-free — the public service is anonymous. The token config key exists only so the same plugin could front a secured mirror.