minimal working customizable stdio version

Author: cboettig

.bumpver.toml

@@ -0,0 +1,17 @@
+{
+	"servers": {
+		"duckdb-geo": {
+			"command": "uv",
+			"args": [
+				"run",
+				"--with",
+				"mcp",
+				"--with",
+				"duckdb",
+				"--with",
+				"pandas",
+				"server.py"
+			]
+		}
+	}
+}

.vscode/mcp.json

@@ -1,213 +1 @@
-# Wetlands MCP Server
-
-An MCP server specialized for analyzing wetlands datasets using DuckDB. This server provides AI assistants and IDEs with the ability to query and analyze comprehensive wetlands data, including spatial information, temporal trends, and ecological metrics.
-
-This server is based on [MotherDuck's DuckDB MCP Server](https://github.com/motherduckdb/mcp-server-motherduck) and extends it with wetlands-specific prompts and context.
-
-## Features
-
-- **Wetlands-specific**: Pre-configured prompts and context for wetlands data analysis
-- **Hybrid execution**: Query data from local DuckDB or cloud-based MotherDuck databases
-- **Cloud storage integration**: Access wetlands data stored in Amazon S3 or other cloud storage
-- **Spatial analytics**: Leverage DuckDB's spatial extensions for geospatial wetlands analysis
-- **SQL analytics**: Use DuckDB's SQL dialect to query wetlands datasets directly from your AI Assistant or IDE
-- **Serverless architecture**: Run analytics without needing to configure instances or clusters
-
-## Components
-
-### Prompts
-
-The server accepts custom prompts with --custom-prompt argument.  
-
-### Tools
-
-The server offers one tool:
-
-- `query`: Execute a SQL query on the DuckDB or MotherDuck database
-  - **Inputs**:
-    - `query` (string, required): The SQL query to execute
-
-All interactions with both DuckDB and MotherDuck are done through writing SQL queries.
-
-**Result Limiting**: Query results are automatically limited to prevent using up too much context:
-- Maximum 1024 rows by default (configurable with `--max-rows`)
-- Maximum 50,000 characters by default (configurable with `--max-chars`)
-- Truncated responses include a note about truncation
-
-## Command Line Parameters
-
-The MCP server supports the following parameters:
-
-| Parameter | Type | Default | Description                                                                                                                                                                                                                                                    |
-|-----------|------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--transport` | Choice | `stdio` | Transport type. Options: `stdio`, `sse`, `stream`                                                                                                                                                                                                              |
-| `--port` | Integer | `8000` | Port to listen on for sse and stream transport mode                                                                                                                                                                                                            |
-| `--host` | String | `127.0.0.1` | Host to bind the MCP server for sse and stream transport mode                                                                                                                                                                                                  |
-| `--db-path` | String | `md:` | Path to local DuckDB database file, MotherDuck database, or S3 URL (e.g., `s3://bucket/path/to/db.duckdb`)                                                                                                                                                     |
-| `--read-only` | Flag | `False` | Flag for connecting to DuckDB or MotherDuck in read-only mode. For DuckDB it uses short-lived connections to enable concurrent access                                                                                                                          |
-| `--home-dir` | String | `None` | Home directory for DuckDB (uses `HOME` env var by default)                                                                                                                                                
-| `--json-response` | Flag | `False` | Enable JSON responses for HTTP stream. Only supported for `stream` transport                                                                                                                                                                                   |
-| `--max-rows` | Integer | `1024` | Maximum number of rows to return from queries.                                                                                                                                                                    |
-| `--max-chars` | Integer | `50000` | Maximum number of characters in query results.                                                                                                                                                          |
-| `--query-timeout` | Integer | `-1` | Query execution timeout in seconds. Set to -1 to disable timeout (default).                                                                                                                                                          |
-| `--custom-prompt` | String | `None` | Path to a custom prompt markdown file. Use this to provide domain-specific context instead of the built-in wetlands data prompt. The custom prompt will be combined with the DuckDB prompt.                                           |
-
-### Quick Usage Examples
-
-```bash
-# Connect to local DuckDB file in read-only mode
-uvx mcp-data-server --db-path /path/to/local.db --read-only
-
-# Connect to local DuckDB file in read-only mode
-uvx mcp-data-server --db-path /path/to/local.db --read-only
-
-# Customize result truncation limits for large wetlands queries
-uvx mcp-data-server --max-rows 2048 --max-chars 100000
-
-# Enable query timeout (5 minutes) for complex spatial queries
-uvx mcp-data-server --query-timeout 300
-
-# Use a custom prompt file for different datasets
-uvx mcp-data-server --custom-prompt /path/to/custom-prompt.md
-```
-
-## Getting Started
-
-### General Prerequisites
-
-- `uv` installed, you can install it using `pip install uv` or `brew install uv`
-
-If you plan to use the MCP with Claude Desktop or any other MCP compatible client, the client needs to be installed.
-
-### Development Setup
-
-1. Clone the repository
-2. Create and activate a virtual environment:
-```bash
-uv venv
-source .venv/bin/activate  # On Linux/Mac
-```
-
-3. Install the package in development mode:
-```bash
-uv pip install -e .
-```
-
-4. Install the MCP Python SDK for testing:
-```bash
-uv pip install mcp
-```
-
-5. Run the test suite:
-```bash
-python3 test_server.py
-```
-
-### Prerequisites for DuckDB
-
-- No prerequisites. The MCP server can create an in-memory database on-the-fly
-- Or connect to an existing local DuckDB database file, or one stored on remote object storage (e.g., AWS S3)
-- Wetlands datasets can be loaded from S3 or other sources as needed
-
-
-#### Manual Installation
-
-
-Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
-
-```json
-{
-  "servers": {
-    "wetlands": {
-      "command": "uvx",
-      "args": [
-        "mcp-data-server"
-      ]
-    }
-  }
-}
-```
-
-### Usage with Claude Code
-
-Claude Code supports MCP servers through CLI commands or JSON configuration. Add the server using a JSON configuration:
-
-```bash
-claude mcp add-json mcp-data-server '{
-  "command": "uvx",
-  "args": [
-    "mcp-data-server",
-    "--db-path"
-  ]
-}'
-```
-
-**Scoping Options**:
-- Use `--local` (default) for project-specific configuration
-- Use `--project` to share the configuration with your team via `.mcp.json`
-- Use `--user` to make the server available across all your projects
-
-
-
-## Running in SSE mode
-
-The server can run in SSE mode in two ways:
-
-### Direct SSE mode
-
-Run the server directly in SSE mode using the `--transport sse` flag:
-
-```bash
-uvx mcp-data-server --transport sse --port 8000 --db-path md: --motherduck-token <your_motherduck_token>
-```
-
-This will start the server listening on the specified port (default 8000) and you can point your clients directly to this endpoint.
-
-### Using supergateway
-
-Alternatively, you can run SSE mode using `supergateway`:
-
-```bash
-npx -y supergateway --stdio "uvx mcp-data-server --db-path md: --motherduck-token <your_motherduck_token>"
-```
-
-Both methods allow you to point your clients such as Claude Desktop, Cursor to the SSE endpoint.
-
-## Development configuration
-
-To run the server from a local development environment, use the following configuration:
-
-```json
- {
-  "mcpServers": {
-    "mcp-data-server": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "/path/to/your/local/mcp-data-server",
-        "run",
-        "mcp-data-server",
-        "--db-path",
-        "md:",
-        "--motherduck-token",
-        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
-      ]
-    }
-  }
-}
-```
-
-## Troubleshooting
-
-- If you encounter connection issues, verify your MotherDuck token is correct
-- For local file access problems, ensure the `--home-dir` parameter is set correctly
-- Check that the `uvx` command is available in your PATH
-- If you encounter `spawn uvx ENOENT` errors, try specifying the full path to `uvx` (output of `which uvx`)
-- In version previous for v0.4.0 we used environment variables, now we use parameters
-
-## License
-
-This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
-
-##
-mcp-name: io.github.boettiger-lab/mcp-data-server
+Minimal stdio-based server

LICENSE

@@ -1,14 +1,8 @@
-# Wetlands Data Context
-
-You are a helpful wetlands data analyst assistant with access to global wetlands data through a DuckDB database. 
-
-Maintain a conversational, helpful tone while providing expert analysis of wetlands datasets. Focus on answering users' analytical questions clearly and concisely.
-
-## Available Datasets
+# Available Datasets
 
 All datasets are H3-indexed for efficient spatial joins. Always use h8 and h0 columns for joining.
 
-### Core Wetlands
+## Core Wetlands
 
 **1. Global Lakes & Wetlands (GLWD)** - `s3://public-wetlands/glwd/hex/**`
 - Columns: `Z` (type 0-33), `h8`, `h0`
@@ -17,7 +11,7 @@ All datasets are H3-indexed for efficient spatial joins. Always use h8 and h0 co
   - Open Water (1-7), Lacustrine (8-9), Riverine (10-15), Palustrine (16-19)
   - Ephemeral (20-21), Peatlands (22-27), Coastal (28-33)
 
-### Environmental Data
+## Environmental Data
 
 **2. Vulnerable Carbon** - `s3://public-carbon/hex/vulnerable-carbon/**`
 - Columns: `carbon`, `h8`, `h0`
@@ -26,7 +20,7 @@ All datasets are H3-indexed for efficient spatial joins. Always use h8 and h0 co
 **3. Nature's Contributions (NCP)** - `s3://public-ncp/hex/ncp_biod_nathab/**`
 - Columns: `ncp` (0-1 score), `h8`, `h0`
 
-### Geographic Boundaries
+## Geographic Boundaries
 
 **4. Countries** - `s3://public-overturemaps/hex/countries.parquet`
 - Columns: `id`, `country` (ISO alpha-2: 'US', 'CA'), `name`, `h8`, `h0`
@@ -35,7 +29,7 @@ All datasets are H3-indexed for efficient spatial joins. Always use h8 and h0 co
 - Columns: `id`, `country`, `region` (ISO: 'US-CA'), `name`, `h8`, `h0`
 - Use only when user explicitly requests regional breakdown
 
-### Protected Areas
+## Protected Areas
 
 **6. Protected Areas (WDPA)** - `s3://public-wdpa/hex/**`
 - Columns: `NAME_ENG`, `DESIG_ENG`, `IUCN_CAT`, `STATUS`, `GIS_AREA` (km²), `ISO3`, `h8`, `h0`
@@ -45,12 +39,12 @@ All datasets are H3-indexed for efficient spatial joins. Always use h8 and h0 co
 **7. Ramsar Sites** - `s3://public-wetlands/ramsar/hex/**`
 - Columns: `Site name`, `Country`, `Area (ha)`, `ramsarid`, `Criterion1-9`, `h8`, `h0`
 
-### Watersheds
+## Watersheds
 
 **8. HydroBASINS** - Level 3: `s3://public-hydrobasins/level_03/hexes/**` / Level 6: `level_06`
 - Columns: `id`, `PFAF_ID`, `UP_AREA` (upstream km²), `SUB_AREA`, `h8`, `h0`
 
-### Biodiversity
+## Biodiversity
 
 **9. iNaturalist Species** - `s3://public-inat/range-maps/hex/**`
 - Columns: `taxon_id`, `name`, `rank`, `h0-h4` (NO h8 - use h3_cell_to_parent!)
@@ -59,41 +53,8 @@ All datasets are H3-indexed for efficient spatial joins. Always use h8 and h0 co
   - Columns: `class`, `order`, `family`, `scientificName`, `vernacularName`
   - Filter by class: 'Aves' (birds), 'Mammalia' (mammals), etc.
 
-### Socioeconomic
+## Socioeconomic
 
 **10. Corruption Index 2024** - `s3://public-wetlands/other/cpi_2024_data.csv`
 - Columns: `Country`, `ISO2`, `Score` (0-100), `Rank`
 - Join to countries using ISO2 for spatial analysis
-
-## Your Role & Responsibilities
-
-You are a specialist in:
-- Interpreting natural language questions about wetlands ecology and geography
-- Writing optimized DuckDB SQL queries for large-scale geospatial datasets
-- Explaining results in clear, non-technical language with ecological context
-- Suggesting relevant follow-up analyses when appropriate
-
-### Best Practices:
-
-1. **Translate codes to names** - Always show wetland type names, not just numeric codes
-2. **Report areas, not counts** - Convert hexagon counts to hectares or km² using H3 constants
-3. **Optimize joins** - Always include `AND t1.h0 = t2.h0` for partition pruning when both tables have h0
-4. **Filter early** - Use CTEs to filter small datasets (countries, taxonomy) before joining large global datasets  
-5. **Format numbers** - Round to appropriate precision (e.g., 2 decimals for areas)
-6. **Use country-level aggregation** - Don't group by region unless explicitly requested
-7. **Handle errors gracefully** - If a query fails, explain the issue clearly and suggest corrections
-8. **Be efficient but not rigid** - Try to answer questions thoroughly, making additional queries if truly needed
-
-### Context Awareness:
-
-- Maintain awareness of the conversation history
-- Remember data the user has already asked about
-- Build on previous queries when relevant
-- Suggest related analyses based on what's been explored
-
-### Error Handling:
-
-- **Query errors**: Explain what went wrong and suggest fixes
-- **Missing data**: Clearly indicate if requested data isn't available in the datasets
-- **Ambiguous requests**: Ask clarifying questions rather than making assumptions
-- **Large results**: Mention when results are truncated and suggest using LIMIT or more specific filters