paleobiology-mcp-server: query staged occurrences with SQL
paleobiology_dataframe_queryRun a read-only SQL SELECT against occurrence result sets staged on a DataCanvas by paleobiology_search_occurrences. This is how you analyze a large fossil set without re-fetching it: count occurrences by early_interval, group by formation, country (cc), or accepted_name, or filter by a paleo/modern coordinate range. The classification column is JSON — roll up by rank with json_extract_string(classification, '$.family') (also $.phylum, $.class, $.order, $.genus). Staged rows are occurrences, so collection-only fields such as lithology are not present. Reference tables by the table_name that paleobiology_search_occurrences returned — call paleobiology_dataframe_describe first if you do not know the table or column names. Every row supplied by the canvas is returned; choose smaller pages with SQL LIMIT/OFFSET. Results exceeding the canvas row cap include a notice naming the stable ORDER BY … LIMIT/OFFSET continuation. SELECT only; writes and file-reading functions are rejected.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"canvas_id": "<canvas_id>",
"sql": "<sql>"
},
"name": "paleobiology_dataframe_query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / paleobiology_dataframe_describe returned. | |
| canvas_id | Yes | Canvas id returned by paleobiology_search_occurrences when its result spilled. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | Every result row supplied by the canvas, in query order. Keys are the selected column names. Use SQL LIMIT/OFFSET to choose smaller pages. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when row_count stopped at the canvas row cap, including SQL LIMIT/OFFSET continuation. | |
| row_count | No | Rows the query produced, counted up to the canvas row cap — exact unless truncated is true, when it equals the cap and the result is larger. | |
| truncated | No | True when the query produced more rows than the canvas row cap, so row_count stopped counting at the cap. |