Content
# Geo-Perception
> Three-layer geospatial cognition system: Perception (L1) → Comprehension (L2) → Reasoning (L3)
> Provides spatial perception, pattern recognition, and causal reasoning capabilities for LLM Agents
## Architecture
```
┌─────────────────────────────────────────────┐
│ L3 Spatial Reasoning │
│ Cluster detection · OD flow · Causal premise check · Spatial narrative │
├─────────────────────────────────────────────┤
│ L2 Spatial Comprehension │
│ Spatial weights · Moran/LISA/Gi* · Semantic labeling │
├─────────────────────────────────────────────┤
│ L1 Spatial Perception │
│ Coordinate transformation · Distance · Buffer · Topology · Geocoding │
└─────────────────────────────────────────────┘
```
**Dual-path design**: Skills define cognitive processes (knowledge injection), MCP Server provides computational capabilities (tool invocation).
## MCP Tools (18)
| Layer | Tool | Function |
|------|------|------|
| **L1 Perception** | `geo_transform_crs` | Coordinate system transformation |
| | `geo_calculate_distance` | Distance and azimuth |
| | `geo_buffer` | Buffer generation |
| | `geo_bbox` | Bounding box calculation |
| | `geo_spatial_relation` | Single topology relation judgment |
| | `geo_all_relations` | Full topology relation (DE-9IM) |
| | `geo_scale_analysis` | Scale inference and MAUP risk assessment |
| | `geo_geocode` | Address → coordinates (Amap API) |
| | `geo_reverse_geocode` | Coordinates → address (Amap API) |
| | `geo_bbox_from_places` | Multi-place joint bounding box |
| **L2 Comprehension** | `geo_spatial_weights` | Spatial weights matrix (Queen/Rook/KNN) |
| | `geo_moran_global` | Global Moran's I |
| | `geo_moran_local` | Local LISA (HH/LL/HL/LH) |
| | `geo_getis_ord` | Getis-Ord Gi* hotspot analysis |
| | `geo_semantic_label` | Topology → semantic labeling mapping |
| **L3 Reasoning** | `geo_cluster_detect` | Dual-mode clustering (point DBSCAN/face spatial constraint) |
| | `geo_od_flow` | OD flow aggregation and dominant flow direction |
| | `geo_causal_check` | Causal premise check (spatial autocorrelation + sample size + common support) |
## Skills (Cognitive Processes)
| Skill | Decision Chain | Content |
|-------|--------|------|
| `geo-perception` | 5 steps | Coordinates → distance → geometry → topology → scale |
| `geo-comprehension` | 6 steps | Weights → global pattern → local pattern → heterogeneity → semantics |
| `geo-reasoning` | 6 steps | Clustering → flow → causal check → causal analysis → narrative |
| `air-pollution` (plugin) | — | AQI indicators/monitoring network/exposure/pattern |
### Offline Code Templates
Slow computations (>2s) are not included in MCP; offline guides are provided:
| Template | Location |
|------|------|
| GWR Geographic Weighted Regression | `skills/geo-comprehension/references/gwr-offline-guide.md` |
| Spatial DID | `skills/geo-reasoning/references/spatial-did-guide.md` |
| Spatial Regression Discontinuity Design (RDD) | `skills/geo-reasoning/references/spatial-rdd-guide.md` |
| Spatial Instrumental Variables (IV) | `skills/geo-reasoning/references/spatial-iv-guide.md` |
## Quick Start
### Installation
```bash
# Clone
git clone https://github.com/kevics1/geo-perception.git
cd geo-perception
# Install dependencies (recommended uv)
uv pip install -e .
# or pip
pip install -e .
```
### Start MCP Server
```bash
# Direct start
python run.py
# or via MCP CLI
mcp run src.server:mcp
```
### Configure in Hermes / Claude Code / Other Agents
```json
{
"geo-perception": {
"command": "python",
"args": ["path/to/geo-perception/run.py"],
"env": {
"PROJ_LIB": "path/to/proj/data",
"AMAP_API_KEY": "your-amap-key"
}
}
}
```
### Load Skills
Copy the three Skills from the `skills/` directory to your Agent's skills directory:
```bash
cp -r skills/geo-perception ~/.hermes/skills/geoai/
cp -r skills/geo-comprehension ~/.hermes/skills/geoai/
cp -r skills/geo-reasoning ~/.hermes/skills/geoai/
```
## Design Principles
| Principle | Description |
|------|------|
| MCP Response <2s | Slow computations use offline templates; MCP only provides fast responses |
| Dual-path knowledge + tools | Skills inject cognitive processes; MCP provides computational capabilities |
| Geometry-first | L2/L3 tools transmit geometries rather than serialized weight JSON |
| Degradation-friendly | Tools return fallback + explanation when unavailable |
| Point-face dual-mode | Clustering tools automatically select algorithms based on geometric type |
## Tech Stack
- **MCP Server**: [FastMCP](https://github.com/modelcontextprotocol/python-sdk)
- **Spatial Computation**: Shapely, pyproj, GeoPandas, PySAL (libpysal + esda)
- **Clustering**: scikit-learn (DBSCAN, AgglomerativeClustering)
- **Geocoding**: Amap API
- **Python**: 3.10+
## Project Structure
```
geo-perception/
├── src/ # MCP Server code
│ ├── server.py # 18 MCP tool definitions
│ └── core/
│ └── spatial_engine.py # Computation engine
├── skills/ # Cognitive processes (knowledge layer)
│ ├── geo-perception/ # L1: 5-step perception chain + 6 refs + 1 template + air-pollution plugin
│ ├── geo-comprehension/ # L2: 6-step comprehension chain + 8 refs
│ └── geo-reasoning/ # L3: 6-step reasoning chain + 5 refs + 1 template
├── tests/ # Tests
├── pyproject.toml
├── run.py # Start script
└── README.md
```
## Tests
```bash
python -m pytest tests/ -v
```
## License
MIT
## Acknowledgements
- [PySAL](https://pysal.org/) — Spatial statistics ecosystem
- [Shapely](https://shapely.readthedocs.io/) — Geometric computation
- [FastMCP](https://github.com/modelcontextprotocol/python-sdk) — MCP protocol implementation
