Metadata-Version: 2.4
Name: mcp-resilland
Version: 0.2.1
Summary: MCP server for RESILAND Intelligence — AI-powered spatial intelligence for Central Asia landscape restoration
Project-URL: Homepage, https://resilland.com
Project-URL: Repository, https://github.com/ilhankilic/mcp-resilland
Project-URL: Issues, https://github.com/ilhankilic/mcp-resilland/issues
Project-URL: Documentation, https://github.com/ilhankilic/mcp-resilland#readme
Project-URL: RESILAND Dashboard, https://resilland.com
Author: İlhan Kılıç
Maintainer: İlhan Kılıç
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: anthropic,central-asia,claude,fao,forestry,geospatial,gis,kazakhstan,landscape-restoration,mcp,model-context-protocol,postgis,resilland,restoration,uzbekistan,world-bank
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: fastmcp<4.0,>=3.0
Requires-Dist: httpx<1.0,>=0.28
Requires-Dist: pydantic<3.0,>=2.8
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# mcp-resilland

**AI-powered spatial intelligence for landscape restoration — now in any MCP client.**

*Built for the World Bank's $256M RESILAND CA+ program covering Uzbekistan,
Kazakhstan, Kyrgyzstan, Tajikistan, and Turkmenistan.*

[![PyPI version](https://img.shields.io/pypi/v/mcp-resilland.svg)](https://pypi.org/project/mcp-resilland/)
[![Python versions](https://img.shields.io/pypi/pyversions/mcp-resilland.svg)](https://pypi.org/project/mcp-resilland/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![MCP compatible](https://img.shields.io/badge/MCP-1.x-green)](https://modelcontextprotocol.io/)

</div>

---

`mcp-resilland` is a [Model Context Protocol](https://modelcontextprotocol.io/)
server that makes the full power of the
[RESILAND Intelligence](https://resilland.com) platform available to Claude
Desktop, Cursor, Continue, Windsurf, Zed, and any other MCP-capable client.

Ask your AI assistant questions like:

> *"Analyze cadastral parcel 1248 in Samarqand for drought-tolerant
> restoration, cite the Phase 4 policy documents, and generate a feasibility
> report in Turkish."*

…and the model will call the right sequence of tools — pulling cadastral
geometry, 12-month Sentinel-2 NDVI, OSM infrastructure proximity, country
climate indicators, curated species fit, and pgvector-backed policy RAG —
then synthesize the answer with Opus 4.7 on the RESILAND backend.

---

## Features

- 🗺️  **3,563 cadastral forest parcels** (Uzbekistan pilot) + all 5 RESILAND CA+ countries
- 🌱  **Curated species catalog** — 64 Central Asia tree/shrub species with
      climate profile, tolerances, restoration priorities, nursery availability
- 🛰️  **Sentinel-2 NDVI history** — 12-month median per parcel from local
      Cloud-Optimized GeoTIFFs
- 🌡️  **Country climate indicators** — ERA5 temperature, CHIRPS precipitation,
      GWIS FWI fire danger, SPI-3 drought, WRI water stress, Hansen tree-cover
      loss, MODIS dust
- 🛣️  **OSM infrastructure proximity** — nearest road / settlement / water body
      across ~370K features for all 5 countries
- 📄  **Phase 4 policy RAG** — pgvector semantic search across World Bank
      Phase 4 feasibility and nursery handbooks
- 🤖  **Opus 4.7 feasibility reports** — 10-section Phase 4-style markdown
      with citations and token/cost accounting
- 🌐  **Four-language output** — English · Türkçe · Русский · Oʻzbekcha

---

## Install

```bash
pip install mcp-resilland
```

Or, if your MCP client supports it (recommended for Claude Desktop):

```bash
uvx mcp-resilland
```

---

## Configure

Create an API key on the RESILAND dashboard:
[https://resilland.com/settings/api-keys](https://resilland.com/settings/api-keys)

*(Keys are free with soft daily/weekly/monthly quotas — no credit card.)*

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "resilland": {
      "command": "uvx",
      "args": ["mcp-resilland"],
      "env": {
        "RESILLAND_API_KEY": "rsi_live_..."
      }
    }
  }
}
```

### Cursor / Continue / Windsurf / Zed

Any MCP-capable client. Point the stdio transport at the
`mcp-resilland` binary with the same environment variable.

### Self-hosted backend

If you run your own RESILAND Intelligence instance, override the upstream:

```bash
export RESILLAND_BASE_URL=http://localhost:8000
export RESILLAND_API_KEY=rsi_live_...
mcp-resilland
```

---

## Capabilities

### Tools (16)

| Tool                          | What it does |
|-------------------------------|--------------|
| `get_balance`                 | Current API key quota state + totals |
| `list_models`                 | Available models + supported locales/countries |
| `list_parcels`                | Cadastral parcel search (country / viloyat / tuman / bbox) |
| `get_parcel`                  | Parcel detail + nearest OSM + nearest nurseries |
| `list_nurseries`              | Nurseries across the RESILAND region |
| `get_nursery`                 | Single nursery detail |
| `analyze_area`                | Full spatial context: NDVI · climate · species · infrastructure · RAG |
| `generate_feasibility_report` | Opus 4.7 Phase 4-style markdown report with citations |
| `translate_brief`             | EN ↔ TR ↔ RU ↔ UZ translation, markdown-preserving |
| `get_stats_overview`          | Platform-wide KPIs (docs, chunks, NDVI, parcels, area, reports) ⭐ v0.2 |
| `get_stats_summary`           | Viewport-scoped counts (bbox filter) ⭐ v0.2 |
| `list_reports`                | List owned feasibility reports (language / scope / status filter) ⭐ v0.2 |
| `get_report`                  | Full report detail — sections, siblings, shares, extra_metadata ⭐ v0.2 |
| `translate_report`            | Translate a report to another language (background task) ⭐ v0.2 |
| `create_report_share_link`    | Mint a 7-day public share URL ⭐ v0.2 |
| `get_report_pdf_url`          | Signed PDF URL (no binary streaming, MCP-friendly) ⭐ v0.2 |

### Resources (8)

Resources are URI-addressable, read-only views the host can surface as
"attach to chat" items, sidebar references, or autocomplete targets.

| URI                                 | Returns |
|-------------------------------------|---------|
| `resiland://info`                   | Server version + runtime config |
| `resiland://parcels/{parcel_id}`    | Parcel detail (same shape as `get_parcel`) |
| `resiland://nurseries`              | Full nursery collection |
| `resiland://species/{species_id}`   | Curated species record (climate profile, tolerances, restoration use-cases) |
| `resiland://climate/{country}`      | Country-level climate indicators |
| `resiland://reports`                | List of reports owned by the API-key user ⭐ v0.2 |
| `resiland://reports/{report_id}`    | Full report detail (sections, siblings, shares, extra_metadata) ⭐ v0.2 |
| `resiland://stats/overview`         | Live platform KPIs (same shape as the /stats dashboard) ⭐ v0.2 |

### Prompts (3)

Pre-canned conversation starters the user can pick from their client's prompt
picker.

| Prompt                   | Purpose |
|--------------------------|---------|
| `restoration_brief`      | Produce a structured restoration recommendation for an area |
| `species_matchmaker`     | Pick tree species matching given site conditions |
| `report_center_workflow` | Generate → translate → share → summarise a full Phase 4 report in one conversation ⭐ v0.2 |

---

## Example conversations

```text
You:   List all RESILAND-9 nurseries in Kazakhstan.
Claude: [calls list_nurseries(country="KAZ", category="RESILAND-9")]
        Here are the 9 RESILAND program nurseries in Kazakhstan…

You:   For parcel 1248, what are the top three drought-tolerant species?
Claude: [calls analyze_area(parcel_id=1248, query="drought tolerant")]
        Based on the curated species fit and Phase 4 RAG citations,
        the top three are Haloxylon ammodendron, Elaeagnus angustifolia,
        and Ulmus pumila…

You:   Generate a full feasibility report for the Dargom nursery in Turkish.
Claude: [calls generate_feasibility_report(nursery_id="…", locale="tr")]
        I've prepared a 2,300-word Turkish feasibility report.
        Estimated cost: $0.08. Sources cited: 7 Phase 4 chunks…
```

---

## Architecture

```
    MCP Client (Claude Desktop / Cursor / Continue / Windsurf / Zed)
                          │  stdio (JSON-RPC)
                          ▼
                    mcp-resilland
              (FastMCP 3.x · Python 3.10+)
                          │  httpx async
                          ▼
              RESILAND Intelligence backend
                  https://resilland.com/v1/public/*
                          │
          ┌───────────────┼────────────────┐
          ▼               ▼                ▼
       PostGIS         pgvector         Opus 4.7
   (parcels · OSM)   (Phase 4 RAG)    Sonnet 4.6
                                       Haiku 4.5
```

The MCP server is a stateless proxy. It does not compute, store, or cache —
all state lives on the RESILAND backend (PostGIS for geometry, pgvector for
RAG, MinIO for tiles, Redis for the Anthropic response cache).

---

## Development

```bash
git clone https://github.com/ilhankilic/mcp-resilland
cd mcp-resilland
pip install -e ".[dev]"

# Run against a local RESILAND backend:
RESILLAND_BASE_URL=http://localhost:8000 RESILLAND_API_KEY=rsi_live_... \
    python -m mcp_resilland

# Run tests:
pytest
```

### Project layout

```
mcp-resilland/
├── pyproject.toml           # hatchling · Apache-2.0 · Python 3.10+
├── README.md                # this file
├── LICENSE                  # Apache 2.0
├── src/mcp_resilland/
│   ├── __init__.py          # package metadata
│   ├── __main__.py          # mcp-resilland console script entrypoint
│   ├── server.py            # FastMCP instance + module wiring
│   ├── client.py            # httpx async client (bearer auth)
│   ├── tools.py             # 9 MCP tools
│   ├── resources.py         # 4 MCP resources (URIs)
│   └── prompts.py           # 2 MCP prompts
└── tests/                   # pytest + respx
```

---

## Authors

- **İlhan Kılıç** — lead engineer, architect

The biodiversity, soil and country-level climate datasets used by the
backend that feeds this MCP come from the public, Apache-2.0-licensed
[`enis1998/resilland-spatial`](https://github.com/enis1998/resilland-spatial)
project; attribution is preserved in `backend/data/external/enis/ATTRIBUTION.md`.

## Acknowledgments

We are grateful for the invaluable advisory support of:

- **İsmail Belen** — President, United Nations Forum on Forests (UNFF)
- **Doç. Dr. Hülya Hernandez** — FAO Türkiye Office
  *(Food and Agriculture Organization of the United Nations, Türkiye Office)*

Their guidance on international forest policy frameworks, landscape
restoration standards, and Central Asia ecological context was instrumental
in shaping this work.

We also thank the World Bank for the RESILAND CA+ Phase 4 feasibility
documentation that forms the semantic-search corpus of this platform.

---

## Links

- **Dashboard:** [resilland.com](https://resilland.com)
- **PyPI:** [pypi.org/project/mcp-resilland](https://pypi.org/project/mcp-resilland)
- **Issues:** [github.com/ilhankilic/mcp-resilland/issues](https://github.com/ilhankilic/mcp-resilland/issues)
- **Model Context Protocol:** [modelcontextprotocol.io](https://modelcontextprotocol.io/)
- **FastMCP:** [gofastmcp.com](https://gofastmcp.com/)
- **World Bank RESILAND CA+ Program:** [worldbank.org](https://www.worldbank.org/)

---

## License

Licensed under the **Apache License, Version 2.0**. See [LICENSE](LICENSE).

Copyright © 2026 İlhan Kılıç.
