the-weather-oracle by jneums - MCP Server

The Weather Oracle ☀️🌧️

A production-ready Model Context Protocol (MCP) server that provides accurate weather forecasts using the Visual Crossing Weather API. Built on the Internet Computer and integrated with the Prometheus Protocol ecosystem.

Mainnet Canister ID: ipor5-bqaaa-aaaai-q33xa-cai
Version: 1.0.4

Overview

The Weather Oracle provides two powerful weather forecasting tools:

get_weather_for_day - Get hourly weather forecasts for the next 24 hours (FREE)
get_weather_for_week - Get daily weather forecasts for the next 7 days (PAID)

Features

✅ Comprehensive Weather Data: Temperature, humidity, precipitation, wind speed, UV index, cloud cover, and more
✅ OAuth 2.0 Authentication: Secure access via Internet Identity or API keys
✅ Monetization Ready: Paid tools with ICRC-1 token integration
✅ Usage Analytics: Optional beacon for ecosystem growth tracking
✅ Treasury Management: Built-in payment collection and withdrawal system
✅ HTTP Outcalls: Real-time weather data from Visual Crossing API

Prerequisites

Before you begin, make sure you have the following tools installed:

DFX: The DFINITY Canister SDK - Installation Guide
Node.js: Version 18.0 or higher - Download
MOPS: The Motoko Package Manager - Installation Guide
Visual Crossing API Key: Sign up at Visual Crossing

Quick Start (Local Development)

1. Clone and Install

git clone https://github.com/jneums/the-weather-oracle.git
cd the-weather-oracle
npm install
npm run mops:install

2. Deploy Locally

Start the local Internet Computer replica:

npm run start

In a new terminal, deploy the canister:

npm run deploy

3. Configure API Key

Set your Visual Crossing API key (owner only):

dfx canister call my_mcp_server set_api_key '("YOUR_VISUAL_CROSSING_API_KEY")'

4. Test with MCP Inspector

Launch the MCP Inspector:

npm run inspector

Connect to your local canister:

http://127.0.0.1:4943/mcp/?canisterId=YOUR_LOCAL_CANISTER_ID

Try calling the get_weather_for_day tool with:

{
  "location": "Denver, CO"
}

🎉 Success! You now have a working Weather Oracle.

Production Setup (Mainnet)

Authentication & Monetization

This project has authentication enabled with the following configuration:

OAuth Issuer: https://bfggx-7yaaa-aaaai-q32gq-cai.icp0.io
Allowance URL: https://prometheusprotocol.org
Required Scopes: ["openid"]

The weekly forecast tool requires payment:

Ledger: 53nhb-haaaa-aaaar-qbn5q-cai (ICRC-1 token)
Amount: 30,000 tokens per query

Usage Analytics Beacon

The canister includes an optional usage beacon enabled to help the Prometheus Protocol DAO understand ecosystem growth:

Beacon Canister: m63pw-fqaaa-aaaai-q33pa-cai
Reporting Interval: Every 15 minutes

API Reference

Weather Tools

`get_weather_for_day`

Get hourly weather forecast for the next 24 hours.

Input:

{
  "location": "City name or zip code"
}

Output:

{
  "report": "Weather for today in Denver, CO:\n2025-11-13: 66.8F, Partially cloudy\n...",
  "forecast": [
    {
      "datetime": "2025-11-13",
      "conditions": "Partially cloudy",
      "temp": 66.8,
      "tempmax": 81.9,
      "tempmin": 52.3,
      "humidity": 42.7,
      "precipprob": 13,
      "windspeed": 9.1,
      "uvindex": 8,
      "hours": [ /* 24 hourly forecasts */ ]
    }
  ]
}

Payment: FREE

`get_weather_for_week`

Get daily weather forecast for the next 7 days.

Input: Same as get_weather_for_day

Output: Same structure with 7 daily forecasts (no hourly data)

Payment: 30,000 tokens (ICRC-1 ledger: 53nhb-haaaa-aaaar-qbn5q-cai)

Canister Methods

Owner Methods

set_api_key(key : Text) : async ()

Set the Visual Crossing API key (owner only).

set_owner(new_owner : Principal) : async Result<(), TreasuryError>

Transfer ownership to a new principal (owner only).

withdraw(ledger_id : Principal, amount : Nat, destination : Destination) : async Result<Nat, TreasuryError>

Withdraw collected tokens from treasury (owner only).

Public Methods

get_owner() : async Principal

Get the current owner principal.

get_treasury_balance(ledger_id : Principal) : async Nat

Check the canister's token balance for a specific ledger.

Authenticated Methods

create_my_api_key(name : Text, scopes : [Text]) : async Text

Create a new API key (returns the raw key - only shown once!).

list_my_api_keys() : async [ApiKeyMetadata]

List all your API keys.

revoke_my_api_key(key_id : Text) : async ()

Revoke an API key.

Development Guide

Project Structure

the-weather-oracle/
├── src/
│   └── main.mo              # Main canister logic
├── dfx.json                 # Canister configuration
├── mops.toml                # Motoko package dependencies
├── package.json             # Node.js dependencies
├── prometheus.yml           # Prometheus Protocol manifest
├── FRONTEND_SPEC.md         # Frontend development specification
├── MOTOKO_INTERFACE.md      # Complete API documentation
└── README.md               # This file

Key Dependencies

Motoko Packages:

mcp-motoko-sdk - MCP server implementation
ic - Internet Computer integration
json - JSON parsing and serialization
map - Hash map implementation
http-types - HTTP type definitions

Node.js Packages:

@modelcontextprotocol/inspector - MCP testing tool
@prometheus-protocol/app-store-cli - Publishing tool
@prometheus-protocol/auth-cli - Authentication management

Testing

Use the MCP Inspector for interactive testing:

npm run inspector

For automated testing, integrate with your preferred testing framework using the HTTP endpoints.

Publishing Updates

Make your changes and commit:

git add .
git commit -m "feat: your feature description"

Get your commit hash:
```
git rev-parse HEAD
```
Publish to Prometheus Protocol:
```
npm run app-store publish "1.0.5"
```

The Prometheus Protocol will audit and deploy your update automatically.

Treasury Management

Check Balance

dfx canister call my_mcp_server get_treasury_balance '(principal "53nhb-haaaa-aaaar-qbn5q-cai")' --network ic

Withdraw Funds

dfx canister call my_mcp_server withdraw '(
  principal "53nhb-haaaa-aaaar-qbn5q-cai",
  100000,
  record {
    owner = principal "YOUR_PRINCIPAL";
    subaccount = null;
  }
)' --network ic

Security Considerations

API Key Storage: The Visual Crossing API key is stored in canister state (owner only access)
Authentication: OAuth 2.0 with JWT validation via JWKS
API Keys: User API keys are hashed using SHA-256 before storage
Payments: ICRC-1 token transfers are validated before tool execution
HTTP Outcalls: Use 30 billion cycles per request to prevent DoS

Cost Analysis

Cycles Consumption

HTTP Outcall: ~30B cycles per weather query
Storage: Minimal (resources stored in memory)
Authentication: JWKS validation requires HTTP outcalls (~30B cycles)

Token Economics

Daily Forecast: FREE
Weekly Forecast: 30,000 tokens per query
All payments go to canister treasury (withdrawable by owner)

Frontend Integration

See FRONTEND_SPEC.md for a comprehensive guide to building a frontend for The Weather Oracle, including:

User interface specifications
Authentication flows
Payment integration
API key management
Design mockups

See MOTOKO_INTERFACE.md for complete API documentation with TypeScript examples.

Troubleshooting

"API key not set"

Solution: Set the Visual Crossing API key using set_api_key

"HTTP request failed with status 401"

Solution: Check your Visual Crossing API key is valid

"Authentication is not enabled"

Solution: Authentication is enabled in this project - ensure you're authenticated

OAuth connection issues

Solution: Verify the issuer URL is accessible and JWKS validation is working

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Resources

Live Canister: https://ipor5-bqaaa-aaaai-q33xa-cai.icp0.io
GitHub: https://github.com/jneums/the-weather-oracle
MCP Protocol: https://modelcontextprotocol.io/
Prometheus Protocol: https://prometheusprotocol.org
Visual Crossing API: https://www.visualcrossing.com/weather-api
Internet Computer: https://internetcomputer.org

License

MIT License - See LICENSE file for details

Built with ❤️ on the Internet Computer