---
name: shapefile
displayName: Shapefile & GeoPackage Reader / Converter
description: Read, inspect, and convert .shp/.dbf/.shx Shapefiles and .gpkg
  GeoPackage files to GeoJSON, CSV, or JSON. Use when opening vector GIS data in
  these formats.
tags:
  - geospatial
  - shapefile
  - geopackage
  - gis
  - converter
  - reader
capabilities:
  - ReadShapefile
  - ReadGeopackage
  - ConvertToGeojson
  - ConvertToCsv
  - ExtractAttributes
  - SummarizeGeometry
representativeQueries:
  - Read a .shp file and show me its contents
  - Convert a shapefile to GeoJSON
  - Extract the attribute table from a shapefile to CSV
  - Open a GeoPackage .gpkg file and list its layers
  - What features and fields are in this shapefile?
version: 0.1.0
tier: curated
---

# Shapefile & GeoPackage Reader / Converter

Read and convert vector GIS data stored as ESRI Shapefiles (`.shp` + `.dbf` + `.shx`) or OGC GeoPackage (`.gpkg`) files. Uses the `fiona` library (backed by GDAL) to handle geometry and attributes, with an optional `geopandas` path for DataFrame-style output.

## When to use

- You have a `.shp` file (with its sibling `.dbf` / `.shx`) and need to inspect features or export them.
- You have a `.gpkg` GeoPackage and want to list layers, read one layer, or convert it.
- You need to convert either format to GeoJSON, CSV (attribute table only), or newline-delimited JSON.

## Steps

1. **Detect format.** Check file extension: `.shp` for Shapefile bundle, `.gpkg` for GeoPackage.
2. **Check for the library.** The script imports `fiona`; if absent it prints a one-line `pip install` hint and exits non-zero.
3. **Route by task.**
   - To read/inspect: open the file with `fiona.open`, print CRS, schema, feature count, and the first N features as formatted JSON.
   - To convert to GeoJSON: write a valid FeatureCollection to stdout.
   - To convert to CSV: flatten properties to rows; serialize geometry as a WKT or JSON string in a `geometry` column.
4. **For GeoPackage multi-layer files:** list available layers (`fiona.listlayers`); use `--layer` to select one (defaults to layer 0).

## Operations

| Capability | CRUD | Resource | Tool |
|---|---|---|---|
| ReadShapefile | READ | .shp + .dbf + .shx bundle | scripts/shapefile_convert.py |
| ReadGeopackage | READ | .gpkg file (single or multi-layer) | scripts/shapefile_convert.py |
| ExtractAttributes | READ | .dbf attribute table | scripts/shapefile_convert.py |
| SummarizeGeometry | READ | geometry schema + CRS | scripts/shapefile_convert.py |
| ConvertToGeojson | READ + local CREATE | GeoJSON FeatureCollection | scripts/shapefile_convert.py |
| ConvertToCsv | READ + local CREATE | CSV (attribute table + geometry column) | scripts/shapefile_convert.py |

## Output

- **Summary mode (default):** driver, CRS, geometry type, field schema, feature count, and the first 5 features as formatted JSON.
- **GeoJSON mode (`--format geojson`):** a complete GeoJSON FeatureCollection printed to stdout.
- **CSV mode (`--format csv`):** one row per feature; columns are all attribute fields plus a `geometry` column (WKT string). Printed to stdout.
- **JSON mode (`--format json`):** newline-delimited JSON (one object per feature) printed to stdout.

## Notes

- Always keep `.shp`, `.dbf`, and `.shx` together in the same directory. Passing `.shp`, `.dbf`, or `.shx` to the script is sufficient — the script locates the companion `.shp` automatically. Other sidecar files (`.prj`, `.cpg`, `.sbn`, `.sbx`) must be in the same directory but cannot be passed as the primary path.
- If no `.prj` file is present, the CRS is reported as `None`; the script does not assume WGS 84.
- `.dbf` field names are truncated to 10 characters by the Shapefile spec; this may cause collisions when converting from other formats.
- For GeoPackage files, use `--layer <name|index>` to select a specific layer (default: layer 0).
- Character encoding: fiona/GDAL reads the `.cpg` hint when present and falls back to `latin-1` for legacy `.dbf` files without one. No explicit encoding logic is needed in the script.
- The script requires `fiona` (and transitively GDAL). If `geopandas` is also available it is not required but mentioned in the install hint for users who want DataFrame output.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `shapefile_summary`, `shapefile_to_geojson`, `shapefile_to_csv`, `shapefile_to_ndjson`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).