MCP Resources Reference

Resources in MCP provide direct access to data through URI-based endpoints. SolarSens MCP provides two main resources for accessing plant and inverter performance data.

What are MCP Resources?

MCP Resources are URI-addressable data endpoints that AI assistants can read directly. Unlike tools (which are function calls), resources use a URI pattern like plant://2024-10-01/daily_plant_values to access data.

When to use Resources vs Tools:

• Resources: Direct data access when you know exactly what you need (e.g., "get plant data for 2024-10-01")
• Tools: Higher-level operations with business logic (e.g., "analyze plant history" with fuzzy matching, authorization checks)

Plant Resources

plant://{date_str}/daily_plant_values

Provides daily performance data for all authorized plants.

URI Pattern

plant://{date_str}/daily_plant_values

Parameters

Parameter	Type	Required	Description
date_str	string	Yes	Date in YYYY-MM-DD format
plant_ids	array	No	Optional list of specific plant IDs to filter. If not provided, returns all authorized plants.
end_date_str	string	No	Optional end date in YYYY-MM-DD format. If provided, returns data for the date range from date_str to end_date_str.

Example URIs

Single date:

plant://2024-10-01/daily_plant_values

Date range (passed as parameters):

plant://2024-10-01/daily_plant_values?end_date_str=2024-10-31

Specific plants:

plant://2024-10-01/daily_plant_values?plant_ids=["plant_123","plant_456"]

Response Format

{
  "data": [
    {
      "date": "2024-10-01",
      "daily_rev": 125.50,
      "daily_s_yield": 4.2,
      "daily_pr": 0.85,
      "daily_total_pr": 0.84,
      "daily_yield": 12500.5,
      "mthly_pr": 0.83,
      "daily_slope_rad": 5.5,
      "meter_reading": 1500000.0,
      "avg_tcell": 45.2,
      "daily_availability": 0.98,
      "plant_soiling": 0.02,
      "plant_curtailment": 0.01,
      "label": "Ho_Chi_Minh_City_1"
    }
  ],
  "row_count": 1
}

Data Fields

Field	Type	Description
date	string	Date of the data point
daily_rev	float	Daily revenue
daily_s_yield	float	Daily specific yield (kWh/kWp)
daily_pr	float	Daily performance ratio (0-1)
daily_total_pr	float	Daily total performance ratio (0-1)
daily_yield	float	Daily energy yield (kWh)
mthly_pr	float	Monthly performance ratio (0-1)
daily_slope_rad	float	Daily slope radiation
meter_reading	float	Meter reading value
avg_tcell	float	Average cell temperature (°C)
daily_availability	float	Daily availability (0-1)
plant_soiling	float	Plant soiling factor (0-1)
plant_curtailment	float	Plant curtailment factor (0-1)
label	string	Plant name/label

Authorization

• Automatically filters data to only authorized plants for the authenticated user
• Returns empty data array if user has no authorized plants
• Plant authorization is managed through Auth0 user claims

---

Inverter Resources

inverter://{plant_id}/{date_str}/daily_inverter_values

Provides daily inverter performance data for a specific plant.

URI Pattern

inverter://{plant_id}/{date_str}/daily_inverter_values

Parameters

Parameter	Type	Required	Description
plant_id	string	Yes	Plant ID to query inverters for
date_str	string	Yes	Date in YYYY-MM-DD format
device_ids	array	No	Optional list of specific device IDs to filter
end_date_str	string	No	Optional end date in YYYY-MM-DD format for date range queries

Example URIs

Single date:

inverter://plant_123/2024-10-01/daily_inverter_values

Date range:

inverter://plant_123/2024-10-01/daily_inverter_values?end_date_str=2024-10-31

Specific devices:

inverter://plant_123/2024-10-01/daily_inverter_values?device_ids=["device_456","device_789"]

Response Format

{
  "data": [
    {
      "date": "2024-10-01",
      "plant_id": "plant_123",
      "name": "CMES-PR018-I06",
      "label": "CMES-PR018-I06",
      "device_id": "device_456",
      "Daily Yield": 607.8,
      "Total Yield": 866211.4,
      "Daily Derating Loss": 0,
      "Daily Operation Time": 729,
      "availability_sum": 144,
      "interval_count": 144,
      "Total Operation Time": 20811,
      "availability": 1.0
    }
  ],
  "row_count": 1
}

Data Fields

Field	Type	Description
date	string	Date of the data point
plant_id	string	Plant identifier
name	string	Inverter name
label	string	Inverter label
device_id	string	Device identifier
Daily Yield	float	Daily energy yield (kWh)
Total Yield	float	Cumulative energy yield (kWh)
Daily Derating Loss	float	Daily derating loss (kWh)
Daily Operation Time	int	Daily operation time (minutes)
availability_sum	int	Sum of availability intervals
interval_count	int	Number of data collection intervals
Total Operation Time	int	Cumulative operation time (hours)
availability	float	Availability ratio (0-1)

Authorization

• Validates that the user has access to the specified plant_id
• Returns an error if the plant is not in the user's authorized plants
• Only returns inverter data for authorized plants

Error Response

{
  "Error": "Access denied. Plant ID xyz123 is not in your authorized plants."
}

---

Technical Details

Data Storage

All resources read from Delta Lake tables stored in S3-compatible storage (DigitalOcean Spaces):

• Plant data: {base_s3_path}/daily_plant_values
• Inverter data: {base_s3_path}/daily_inverter_values

Performance Considerations

• Timeout: 30 seconds for all resource queries
• Caching: User authorization data is cached in Redis with 1-day TTL
• Connection timeout: 25 seconds for S3 operations
• Async operations: All data fetching is asynchronous

Error Handling

Resources handle several error scenarios:

1. Timeout errors:

   {
     "Error": "Operation timed out after 30 seconds - possible network or S3 issue"
   }

2. Access denied:

   {
     "Error": "Access denied. Plant ID xyz123 is not in your authorized plants."
   }

3. General errors:

   {
     "Error": "Error reading Delta table: {error_details}"
   }

4. No authorized plants:

   {
     "data": [],
     "row_count": 0
   }

Using Resources in AI Conversations

Resources are typically used by the AI assistant automatically when you ask for specific data:

Example conversation:

You: "Get plant data for October 1, 2024"

AI: I'll fetch that data using the plant resource...
[Reads plant://2024-10-01/daily_plant_values]

Here's the performance data for October 1, 2024:
[Data summary...]

Resources vs Tools

Feature	Resources	Tools
Access pattern	URI-based, direct data access	Function-based, business logic
Example	plant://2024-10-01/daily_plant_values	analyze_plant_history("Ho Chi Minh", ...)
Use case	When you know exact date/plant	When you need analysis, fuzzy matching
Authorization	Built into resource	Handled by middleware + tool logic
Complexity	Low-level data access	High-level operations

Next Steps

• View Tools documentation - Higher-level analysis functions
• View Prompts documentation - Pre-built prompt templates
• Usage examples - See resources in action