# Upstream Lens MCP

> Upstream Lens monitors environmental assets and conservation projects using satellite imagery and field data. It lets your AI client analyze geospatial metadata, track changes over time, and pull project notes directly from a natural conversation. You can list all active projects, query available imagery layers (Sentinel, Landsat), and verify property details without leaving the chat window.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** satellite-imagery, environmental-monitoring, remote-sensing, geospatial-data, conservation, data-analysis

## Description

This server hooks your AI client up to Upstream Lens. You can run complex geospatial queries using plain language, pulling environmental data—like satellite images and field reports—and making it actionable right in the chat window. 

**Getting Started & Scope:**
To make sure everything's running clean, you first need to check the connection status with `check_api_health`. For background info on your account, run `get_organization_info`; that pulls core metadata for your entire organization within Upstream Lens. You can scope out all the conservation work you manage by calling `list_portfolios`, which shows every high-level portfolio. If you need to know what projects are active right now, `list_projects` gives you a list of every environmental project ID and name.

**Property Deep Dive:**
When you zero in on a specific piece of land, the server lets you pull down detailed records using `get_property_details`, which takes a known property feature ID to fetch all its specifics. For that same property, you can check what satellite images are available by calling `list_property_imagery`; this tool lists all layers—like Sentinel and Landsat—so you know if you're looking at true color or NDVI data. If you just want the basics on a specific asset, you can also pull up comprehensive metadata about it using `get_property_details`.

**Tracking Changes & History:**
Environmental monitoring is all about tracking time. You don't have to leave the chat window to build an auditable timeline of site changes. If you need written field notes—the stuff people actually wrote down when they were out there—use `list_project_notes`. This lets you filter those observations by date for a specific project, so you can see exactly what was documented and when. To get the granular details on what folks saw, use `list_project_observations`; this lists detailed records of every observation tied to a project. You can comb through all the historical documentation by targeting these tools against any given project ID.

**Putting It All Together:**
When you combine these calls, your AI client acts like it's sitting at the site with you. If you tell it, 'Show me all active projects and what imagery is available for the property associated with Project XYZ,' it pulls together a complete picture. You can see every portfolio (`list_portfolios`), confirm the API is live (`check_api_health`), get the project list (`list_projects`), pull down the latest satellite metadata (`list_property_imagery`)—and then, if you want to dig into the history of that spot, it pulls both the general notes (`list_project_notes`) and the specific observation records (`list_project_observations`). It keeps your conservation data structured, verifiable, and immediately ready for whatever question you've got. You don't just get a list; you get the actionable context you need to make decisions.

## Tools

### get_property_details
Fetches specific, detailed records for a known property feature ID.

### get_organization_info
Retrieves core metadata about your entire organization within Upstream Lens.

### check_api_health
Confirms if the Upstream Lens API is currently active and connected.

### list_property_imagery
Lists available satellite image layers (Sentinel, Landsat) for a specific property feature ID.

### list_project_notes
Retrieves written field observations and notes, allowing filtering by update date for a project.

### list_project_observations
Lists detailed records of specific observations made during the course of a project.

### list_portfolios
Lists all the high-level conservation portfolios you manage.

### list_projects
Gathers a list of every active environmental project ID and name.

## Prompt Examples

**Prompt:** 
```
List all active environmental projects in my Lens account.
```

**Response:** 
```
I've retrieved your projects. You have access to: 'Amazon Rainforest Restoration', 'Coral Reef Protection', and 'Midwest Soil Health'. Which one would you like to inspect?
```

**Prompt:** 
```
Show me the latest field notes for the 'Amazon Restoration' project.
```

**Response:** 
```
I've fetched the project notes. There are 2 recent observations: 'Tree growth rate 15% higher than Q3' and 'New sensor installed at station B'. Shall I retrieve the previous history?
```

**Prompt:** 
```
List available satellite imagery layers for property 'feat_10293'.
```

**Response:** 
```
I found 3 available imagery layers for property feat_10293: 'Sentinel-2 (True Color)', 'Sentinel-2 (NDVI)', and 'Landsat 8'. The most recent capture was yesterday. Shall I retrieve the download metadata?
```

## Capabilities

### Discover all active projects
Lists every environmental project or portfolio managed under the Upstream Lens account.

### Analyze property imagery layers
Retrieves metadata about available satellite images (e.g., true color, NDVI) for a specific geographic area.

### Track historical field data
Pulls project notes and detailed observations to build an auditable timeline of changes at a site.

### Get organization status
Retrieves the metadata for your connected Upstream Lens account or verifies API health.

## Use Cases

### Compliance Check for a Portfolio
The analyst needs to verify environmental compliance across three sites. They first run `list_projects` to get the IDs, then use those IDs with `get_property_details` and `list_property_imagery` sequentially. The agent aggregates all metadata to create a single report on feature boundaries and available imagery.

### Reviewing Site Changes
A manager wants to know if site 'ABC' has seen any changes since last quarter. They use `list_project_notes` and filter by date, cross-referencing the results with `list_property_observations` to ensure all physical reports match the recorded history.

### Initial Project Scoping
A sustainability team member starts a new assessment. They first call `list_portfolios` to see which umbrella goals apply, then use that knowledge to run `list_projects`, quickly narrowing down the scope of work for the AI client.

### Deep Dive into One Feature
The team needs all available data on a single feature ID. They start by running `get_property_details` to grab metadata, then follow up with `list_property_imagery` and `get_organization_info` to build a complete context file for the client.

## Benefits

- Check system status immediately. Use `check_api_health` to confirm the API is running before initiating any data retrieval, preventing failed jobs.
- Manage assets by listing all projects using `list_projects`. This gives you a clean list of every site without needing to navigate multiple dashboards.
- Track history with ease. Running `list_project_notes` pulls recorded field observations and notes, building an immediate timeline that's ready for reporting.
- Compare images directly in the chat. Calling `list_property_imagery` shows you exactly what satellite layers are available for a property ID, saving time on manual checks.
- Get site specifics instantly. Need to know the details of one feature? `get_property_details` pulls all necessary metadata into your agent's context.

## How It Works

The bottom line is that you use natural language commands to run complex geospatial queries across your entire environmental asset base.

1. Subscribe to this server and get your Upstream Tech Lens API Key.
2. Provide the key to your AI client (Claude, Cursor, etc.).
3. Ask a direct question: 'List all projects in the Amazon region' or 'Show me imagery for feat_10293'.

## Frequently Asked Questions

**How do I find all my environmental projects using list_projects?**
Just ask your agent to 'List all active environmental projects.' The `list_projects` tool runs immediately and gives you a clean, actionable roster of every project ID available in the system.

**Can I check if the API is working before running any report?**
Yes. Run `check_api_health`. This simple call tells your agent instantly if the Upstream Lens connection is live, saving you from running expensive queries against a downed service.

**Which tool do I use to find available satellite imagery?**
Use `list_property_imagery` and provide a specific property ID. This call tells you exactly which layers (Sentinel, Landsat) are available for that piece of land.

**What's the difference between list_project_notes and list_project_observations?**
Project notes (`list_project_notes`) hold general text summaries written by field staff. Observations (`list_project_observations`) are typically structured, quantitative data points or metrics recorded at a specific time.

**What does the `get_organization_info` tool retrieve about my Upstream Tech Lens account?**
The tool fetches core metadata for your entire organization. This helps confirm account configuration and verify basic credentials before you run larger, resource-intensive reports.

**When should I use `get_property_details` instead of listing projects?**
Use this when you need the full metadata record for one specific feature. It retrieves deep details about a property—far beyond what general listings provide.

**Can I use `list_project_notes` to filter observations by date range?**
Yes, you can specify an update date range when calling the tool. This lets you focus only on notes written between two specific dates for targeted analysis.

**How does `list_portfolios` help manage my environmental assets?**
Portfolios group related projects and sites into a single container. Running this tool shows the high-level organizational structure of your conservation work.

**Can I see if new satellite images are available for my project?**
Yes! Use the `list_property_imagery` tool and provide the Property ID. Your agent will retrieve all available imagery layers (Sentinel, Landsat, etc.) with their respective capture dates.

**How do I retrieve field notes for a specific conservation project?**
Run the `list_project_notes` query with your Project ID. You can also provide an optional timestamp to filter only notes updated after a specific date.

**Is it possible to see the geospatial metadata for a property feature?**
Absolutely. Use the `get_property_details` tool with the Feature ID to retrieve detailed geospatial data and metadata for any monitored property.