@lagoon-protocol/lagoon-mcp 0.1.3 → 0.2.1

package/skills/lagoon-protocol-health/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: lagoon-protocol-health
+description: Monitor protocol-wide KPIs, identify TVL trends, generate executive summaries, and flag at-risk vaults for the internal operations team. Activates for protocol overview, daily/weekly reports, and health monitoring requests.
+---
+
+# Lagoon Protocol Health: KPI Monitoring Guide
+
+You are a protocol analytics specialist helping the Lagoon operations team monitor protocol health, identify trends, and generate executive summaries.
+
+## When This Skill Activates
+
+This skill is relevant when internal users:
+- Request protocol-wide metrics or KPIs
+- Ask about TVL trends, vault growth, or protocol performance
+- Need executive summaries or reports
+- Want to identify underperforming or at-risk vaults
+- Request comparisons across time periods
+
+## Step 1: Define Monitoring Scope
+
+### Time Period Selection
+> "What time period should this analysis cover?"
+- **Daily**: Last 24 hours vs previous day
+- **Weekly**: Last 7 days vs previous week
+- **Monthly**: Last 30 days vs previous month
+- **Custom**: Specific date range
+
+### Metric Focus
+> "Which KPIs are most important for this review?"
+- **TVL**: Total protocol TVL, growth rate, distribution
+- **Activity**: Deposits, redemptions, active vaults
+- **Performance**: APR distribution, yield delivery
+- **Risk**: Risk score distribution, alerts
+
+## Step 2: Tool Workflow Sequence
+
+### 2.1 Protocol Overview
+**Tool**: `search_vaults`
+
+Fetch all active vaults for aggregate analysis:
+```json
+{
+  "filters": { "isVisible_eq": true },
+  "orderBy": "totalAssetsUsd",
+  "orderDirection": "desc",
+  "maxResults": 50,
+  "responseFormat": "summary"
+}
+```
+
+Present aggregate metrics:
+| Metric | Value |
+|--------|-------|
+| Total Vaults | [N] |
+| Total TVL | $[X]M |
+| Avg APR | [X]% |
+
+### 2.2 Performance Deep Dive
+**Tool**: `get_vault_performance`
+
+For top 10 vaults by TVL, analyze performance trends:
+```json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "timeRange": "30d",
+  "responseFormat": "summary"
+}
+```
+
+### 2.3 Risk Distribution
+**Tool**: `analyze_risk`
+
+Sample risk scores across vault categories:
+```json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "responseFormat": "summary"
+}
+```
+
+Categorize vaults by risk level:
+| Risk Level | Count | % of TVL |
+|------------|-------|----------|
+| Low (<30) | [N] | [X]% |
+| Medium (30-60) | [N] | [X]% |
+| High (>60) | [N] | [X]% |
+
+## Step 3: KPI Framework
+
+### Core Metrics Dashboard
+
+| KPI | Current | Trend | Status |
+|-----|---------|-------|--------|
+| Total TVL | $[X]M | [+/-X]% | [GREEN/YELLOW/RED] |
+| Active Vaults | [N] | [+/-N] | [GREEN/YELLOW/RED] |
+| Avg Risk Score | [X] | [+/-X] | [GREEN/YELLOW/RED] |
+| High-Risk Vaults | [N]% | [+/-X]% | [GREEN/YELLOW/RED] |
+
+### Alert Conditions
+
+**RED ALERT** (Immediate action required):
+- TVL drop >10% in 24h
+- Any vault risk score >80
+- Vault with >$1M TVL showing anomalous activity
+- APR dropping to 0% unexpectedly
+
+**YELLOW WARNING** (Monitor closely):
+- TVL drop >5% in 7d
+- Vault risk score increased >20 points
+- APR variance >30% from 30d average
+- New vault with rapid TVL growth (potential instability)
+
+**GREEN HEALTHY**:
+- All metrics within thresholds
+- Positive or stable TVL trend
+- Risk scores stable or improving
+- Consistent APR delivery
+
+## Step 4: Report Generation
+
+### Executive Summary Template
+```
+LAGOON PROTOCOL HEALTH REPORT
+=============================
+Period: [Start Date] - [End Date]
+Generated: [Timestamp]
+
+KEY METRICS
+-----------
+Protocol TVL: $[X]M ([+/-X]% vs prior period)
+Active Vaults: [N] ([+/-N] vs prior period)
+Avg APR: [X]% ([+/-X]% vs prior period)
+Avg Risk Score: [X]/100 ([+/-X] vs prior period)
+
+TOP PERFORMERS (by TVL growth)
+------------------------------
+1. [Vault Name]: +$[X]M ([+X]%)
+2. [Vault Name]: +$[X]M ([+X]%)
+3. [Vault Name]: +$[X]M ([+X]%)
+
+CONCERNS
+--------
+- [Issue 1 if any]
+- [Issue 2 if any]
+
+WATCHLIST
+---------
+- [Vault requiring attention]
+
+RECOMMENDATIONS
+---------------
+- [Action 1]
+- [Action 2]
+```
+
+## Communication Guidelines
+
+### Internal Reporting Standards
+- Use precise numbers, not approximations
+- Include period-over-period comparisons
+- Flag any data quality issues
+- Note any vaults excluded from analysis and why
+- Prioritize actionable insights over raw data
+- Use tables for easy scanning
+- Highlight anomalies prominently
+
+---
+
+*This skill is part of the Lagoon MCP ecosystem. For technical tool documentation, refer to the MCP tool descriptions.*

package/skills/lagoon-protocol-health/kpi-thresholds.md

@@ -0,0 +1,50 @@
+# KPI Thresholds Reference
+
+## TVL Thresholds
+
+| Metric | Healthy (Green) | Warning (Yellow) | Critical (Red) |
+|--------|-----------------|------------------|----------------|
+| Protocol TVL Growth (7d) | >0% | -5% to 0% | <-5% |
+| Protocol TVL Growth (30d) | >5% | 0% to 5% | <0% |
+| Single Vault TVL Drop (24h) | <-5% | -5% to -15% | >-15% |
+| Single Vault TVL Drop (7d) | <-10% | -10% to -30% | >-30% |
+| Vault TVL Minimum | >$100K | $50K-$100K | <$50K |
+
+## Risk Thresholds
+
+| Metric | Healthy (Green) | Warning (Yellow) | Critical (Red) |
+|--------|-----------------|------------------|----------------|
+| Avg Protocol Risk Score | <40 | 40-60 | >60 |
+| High-Risk Vault % (score >60) | <10% | 10-20% | >20% |
+| Risk Score Change (7d) | <+10 | +10 to +20 | >+20 |
+| Max Single Vault Risk | <70 | 70-80 | >80 |
+
+## Performance Thresholds
+
+| Metric | Healthy (Green) | Warning (Yellow) | Critical (Red) |
+|--------|-----------------|------------------|----------------|
+| APR Delivery Rate | >90% | 70-90% | <70% |
+| APR Volatility (30d CV) | <20% | 20-40% | >40% |
+| Vaults with APR = 0 | 0 | 1-2 | >2 |
+
+## Activity Thresholds
+
+| Metric | Healthy (Green) | Warning (Yellow) | Critical (Red) |
+|--------|-----------------|------------------|----------------|
+| Daily Active Vaults | >80% | 60-80% | <60% |
+| Weekly New Deposits | >10 | 5-10 | <5 |
+| Deposit/Redemption Ratio | >0.8 | 0.5-0.8 | <0.5 |
+
+## Escalation Procedures
+
+### Red Alert Actions
+1. Notify ops lead immediately via Slack #lagoon-alerts
+2. Identify affected vaults and users
+3. Prepare incident report within 1 hour
+4. Schedule emergency review if systemic issue
+
+### Yellow Warning Actions
+1. Add to daily standup agenda
+2. Monitor for escalation over 24-48 hours
+3. Document in weekly report
+4. Consider proactive user communication

package/skills/lagoon-protocol-health/report-templates.md

@@ -0,0 +1,149 @@
+# Report Templates
+
+## Daily Standup Report
+
+```markdown
+# Daily Protocol Health - [YYYY-MM-DD]
+
+## Quick Stats
+| Metric | Value | 24h Change |
+|--------|-------|------------|
+| TVL | $[X]M | [+/-X]% |
+| Vaults | [N] | [+/-N] |
+| Avg APR | [X]% | [+/-X]% |
+
+## Alerts
+- [List any red/yellow alerts or "No alerts"]
+
+## Today's Focus
+- [Key priority or "Business as usual"]
+
+## Notes
+- [Any relevant observations]
+```
+
+## Weekly Summary Report
+
+```markdown
+# Weekly Protocol Health Summary
+Week: [Start Date] - [End Date]
+
+## Executive Summary
+[2-3 sentence overview of the week]
+
+## KPI Dashboard
+| KPI | Start | End | Change | Status |
+|-----|-------|-----|--------|--------|
+| TVL | $[X]M | $[X]M | [+/-X]% | [STATUS] |
+| Vaults | [N] | [N] | [+/-N] | [STATUS] |
+| Avg Risk | [X] | [X] | [+/-X] | [STATUS] |
+
+## Top Performers
+1. **[Vault Name]**: [Highlight]
+2. **[Vault Name]**: [Highlight]
+
+## Areas of Concern
+- [Concern 1]
+- [Concern 2]
+
+## Watchlist for Next Week
+- [Item 1]
+- [Item 2]
+
+## Action Items
+- [ ] [Action 1]
+- [ ] [Action 2]
+```
+
+## Monthly Executive Report
+
+```markdown
+# Monthly Protocol Health Report
+Month: [Month Year]
+
+## Executive Summary
+[Paragraph summarizing month's performance]
+
+## Key Metrics
+
+### TVL Growth
+- Start of Month: $[X]M
+- End of Month: $[X]M
+- Net Change: [+/-$X]M ([+/-X]%)
+- Peak: $[X]M on [Date]
+- Trough: $[X]M on [Date]
+
+### Vault Activity
+- Total Vaults: [N]
+- New Vaults: [N]
+- Inactive Vaults: [N]
+
+### Performance Distribution
+| APR Range | Vault Count | TVL Share |
+|-----------|-------------|-----------|
+| >20% | [N] | [X]% |
+| 10-20% | [N] | [X]% |
+| 5-10% | [N] | [X]% |
+| <5% | [N] | [X]% |
+
+### Risk Overview
+| Risk Level | Vault Count | TVL Share |
+|------------|-------------|-----------|
+| Low (<30) | [N] | [X]% |
+| Medium (30-60) | [N] | [X]% |
+| High (>60) | [N] | [X]% |
+
+## Highlights
+- [Major achievement 1]
+- [Major achievement 2]
+
+## Incidents
+- [Incident 1 if any, with resolution]
+
+## Recommendations
+1. [Strategic recommendation 1]
+2. [Strategic recommendation 2]
+
+## Next Month Focus
+- [Priority 1]
+- [Priority 2]
+```
+
+## Ad-Hoc Investigation Template
+
+```markdown
+# Investigation: [Issue Title]
+Date: [YYYY-MM-DD]
+Analyst: [Name]
+
+## Issue Summary
+[Brief description of the issue]
+
+## Affected Components
+- Vault(s): [List]
+- Chain(s): [List]
+- Users: [Estimate]
+
+## Timeline
+| Time | Event |
+|------|-------|
+| [Time] | [Event] |
+
+## Analysis
+[Detailed analysis]
+
+## Root Cause
+[Identified cause or "Under investigation"]
+
+## Impact Assessment
+- TVL Impact: $[X]
+- User Impact: [Description]
+- Reputation Impact: [Low/Medium/High]
+
+## Recommended Actions
+1. [Action 1]
+2. [Action 2]
+
+## Status
+[Open/Resolved/Monitoring]
+```

package/skills/lagoon-risk-expert/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: lagoon-risk-expert
+version: 1.0.0
+description: Deep risk analysis for advanced users seeking comprehensive understanding of vault risk factors
+audience: customer-advanced
+category: risk
+triggers:
+  - deep risk analysis
+  - comprehensive risk
+  - risk factors
+  - risk breakdown
+  - detailed risk
+  - advanced risk
+  - risk decomposition
+  - volatility analysis
+  - drawdown analysis
+  - stress test
+  - scenario analysis
+  - risk assessment
+  - risk profile
+  - correlation analysis
+  - risk-adjusted returns
+  - sharpe ratio
+tools:
+  - analyze_risk
+  - get_vault_performance
+  - get_price_history
+  - compare_vaults
+estimated_tokens: 2200
+---
+
+# Lagoon Risk Expert: Deep Risk Analysis Guide
+
+You are a DeFi risk analyst providing comprehensive risk assessments for advanced users. Your goal is to deliver detailed, multi-factor risk analysis that enables informed investment decisions.
+
+## When This Skill Activates
+
+This skill is relevant when users:
+- Request deep or detailed risk analysis
+- Ask about specific risk factors or components
+- Want to understand risk decomposition
+- Need correlation or concentration analysis
+- Request stress testing or scenario analysis
+- Ask about volatility patterns or drawdowns
+
+## Step 1: Comprehensive Risk Assessment
+
+### Multi-Factor Risk Analysis
+**Tool**: `analyze_risk`
+
+Request detailed risk breakdown:
+```json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "responseFormat": "detailed"
+}
+```
+
+### Risk Factor Decomposition
+
+Present risk breakdown using this framework:
+
+```
+COMPREHENSIVE RISK ANALYSIS
+===========================
+
+Vault: [Name]
+Analysis Date: [Date]
+Overall Risk Score: [X]/100 - [Risk Level]
+
+RISK FACTOR BREAKDOWN
+---------------------
+
+1. TVL Risk (Weight: 25%)
+   Score: [X]/100
+   Analysis: [Interpretation of TVL risk]
+
+2. Concentration Risk (Weight: 20%)
+   Score: [X]/100
+   Analysis: [Interpretation of concentration]
+
+3. Volatility Risk (Weight: 20%)
+   Score: [X]/100
+   Analysis: [Interpretation of volatility]
+
+4. Age Risk (Weight: 15%)
+   Score: [X]/100
+   Analysis: [Interpretation of operational maturity]
+
+5. Curator Risk (Weight: 20%)
+   Score: [X]/100
+   Analysis: [Interpretation of curator reliability]
+```
+
+## Step 2: Historical Performance Analysis
+
+### Performance Deep Dive
+**Tool**: `get_vault_performance`
+
+Analyze multiple timeframes for comprehensive view.
+
+## Step 3: Price History Analysis
+
+### Price Trend Examination
+**Tool**: `get_price_history`
+
+Analyze share price behavior and volatility patterns.
+
+## Step 4: Comparative Risk Analysis
+
+### Peer Comparison
+**Tool**: `compare_vaults`
+
+Compare against similar vaults for context.
+
+## Step 5: Scenario Analysis
+
+Present stress testing and scenario analysis for different market conditions.
+
+## Step 6: Risk Recommendations
+
+Provide actionable risk assessment summary with suitability guidance.
+
+## Critical Disclaimers
+
+**NOT FINANCIAL ADVICE**: This analysis is for informational purposes only and does not constitute investment advice.
+
+**TOTAL LOSS RISK**: DeFi investments can result in complete loss of principal.
+
+**NO GUARANTEES**: Past performance does not guarantee future results.

package/skills/lagoon-risk-expert/risk-frameworks.md

@@ -0,0 +1,124 @@
+# Risk Analysis Frameworks
+
+## Risk Scoring Methodology
+
+### Factor Weights
+| Factor | Weight | Rationale |
+|--------|--------|-----------|
+| TVL Risk | 25% | Liquidity and market validation |
+| Concentration Risk | 20% | Diversification and exposure |
+| Volatility Risk | 20% | Price stability and predictability |
+| Age Risk | 15% | Operational maturity |
+| Curator Risk | 20% | Management quality |
+
+### Risk Score Interpretation
+| Score Range | Risk Level | Description |
+|-------------|------------|-------------|
+| 0-20 | Very Low | Excellent risk profile, suitable for conservative investors |
+| 21-40 | Low | Good risk management, moderate exposure acceptable |
+| 41-60 | Medium | Balanced risk-reward, requires active monitoring |
+| 61-80 | High | Elevated risk, suitable only for risk-tolerant investors |
+| 81-100 | Very High | Significant risk, speculative allocation only |
+
+## Volatility Analysis Framework
+
+### Volatility Metrics
+- **Daily Volatility**: Standard deviation of daily returns
+- **Weekly Volatility**: Rolling 7-day volatility
+- **Implied Volatility**: Market-expected future volatility
+- **Historical Volatility**: Past price movement analysis
+
+### Volatility Interpretation
+| Volatility | Assessment | Implication |
+|------------|------------|-------------|
+| <5% | Very Low | Stable, predictable returns |
+| 5-15% | Low | Normal market conditions |
+| 15-30% | Medium | Typical DeFi volatility |
+| 30-50% | High | Significant price swings expected |
+| >50% | Very High | Extreme volatility, high risk |
+
+## Drawdown Analysis
+
+### Maximum Drawdown Categories
+| Drawdown | Severity | Recovery Expectation |
+|----------|----------|----------------------|
+| <5% | Minor | Days to weeks |
+| 5-15% | Moderate | Weeks to months |
+| 15-30% | Significant | Months |
+| 30-50% | Severe | Months to quarters |
+| >50% | Critical | Extended recovery or permanent loss |
+
+### Recovery Analysis
+- **Recovery Factor**: Return / Max Drawdown
+- **Recovery Time**: Days to recover previous high
+- **Ulcer Index**: Measure of downside risk duration
+
+## Correlation Analysis
+
+### Asset Correlation Matrix
+Analyze how vault returns correlate with:
+- BTC/ETH market movements
+- DeFi sector performance
+- Protocol-specific factors
+- Macroeconomic indicators
+
+### Diversification Benefits
+| Correlation | Diversification |
+|-------------|-----------------|
+| <0.3 | Strong diversification benefit |
+| 0.3-0.6 | Moderate diversification |
+| 0.6-0.8 | Limited diversification |
+| >0.8 | High correlation, similar exposure |
+
+## Stress Testing Scenarios
+
+### Standard Stress Tests
+1. **Market Crash**: 50% decline in underlying assets
+2. **Liquidity Crisis**: Unable to exit position at fair value
+3. **Protocol Failure**: Smart contract exploit or failure
+4. **Correlation Breakdown**: Historical correlations don't hold
+5. **Black Swan Event**: Unprecedented market conditions
+
+### Scenario Impact Assessment
+For each scenario, evaluate:
+- Potential loss magnitude
+- Probability of occurrence
+- Recovery time estimate
+- Mitigation strategies available
+
+## Risk-Adjusted Return Metrics
+
+### Sharpe Ratio Interpretation
+| Sharpe | Quality |
+|--------|---------|
+| <0 | Negative risk-adjusted return |
+| 0-0.5 | Poor |
+| 0.5-1.0 | Adequate |
+| 1.0-2.0 | Good |
+| >2.0 | Excellent |
+
+### Sortino Ratio
+- Focuses on downside deviation
+- More relevant for asymmetric return distributions
+- Higher is better (only penalizes downside volatility)
+
+### Calmar Ratio
+- Return / Max Drawdown
+- Measures return per unit of drawdown risk
+- Higher indicates better drawdown-adjusted returns
+
+## Position Sizing Framework
+
+### Risk-Based Sizing
+| Risk Level | Max Allocation |
+|------------|----------------|
+| Very Low | Up to 25% of portfolio |
+| Low | Up to 15% of portfolio |
+| Medium | Up to 10% of portfolio |
+| High | Up to 5% of portfolio |
+| Very High | Up to 2% of portfolio |
+
+### Concentration Guidelines
+- No single vault >25% of total DeFi allocation
+- No single chain >50% of total allocation
+- No single strategy type >40% of allocation