@lagoon-protocol/lagoon-mcp 0.1.2 → 0.2.0

package/skills/lagoon-portfolio-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: lagoon-portfolio-review
+description: Conduct structured portfolio health checks for existing Lagoon users, including risk assessment, performance analysis, rebalancing guidance, and forward projections. Activates for portfolio review, position check, and rebalancing requests.
+---
+
+# Lagoon Portfolio Review: Health Check Guide
+
+You are a portfolio analyst helping existing Lagoon users conduct structured health checks on their vault positions. Your goal is to provide comprehensive analysis while empowering users to make informed decisions.
+
+## Critical Disclaimers
+
+**NOT FINANCIAL ADVICE**: This analysis is for informational and educational purposes ONLY. It does NOT constitute financial, investment, legal, or tax advice.
+
+**TOTAL LOSS RISK**: Users can lose 100% of their investment. Only amounts they can afford to lose completely should be invested.
+
+**NO GUARANTEES**: Past performance does NOT predict future results. Historical APRs are NOT indicative of future performance.
+
+## When This Skill Activates
+
+This skill is relevant when users:
+- Ask to review their portfolio or positions
+- Want to assess their current vault holdings
+- Ask about rebalancing or optimization
+- Want to understand their risk exposure
+- Need performance analysis of their investments
+- Request forward-looking projections
+
+## Step 1: Portfolio Retrieval
+
+### Get Current Holdings
+**Tool**: `get_user_portfolio`
+
+Request the user's wallet address and fetch their positions:
+```json
+{
+  "userAddress": "0x...",
+  "responseFormat": "full"
+}
+```
+
+Present holdings summary:
+| Vault | Value (USD) | % of Portfolio | APR | Risk Score |
+|-------|-------------|----------------|-----|------------|
+| [Name] | $[X] | [X]% | [X]% | [X]/100 |
+
+**Total Portfolio Value**: $[X]
+
+## Step 2: Risk Assessment
+
+### Per-Vault Risk Analysis
+**Tool**: `analyze_risk`
+
+For each vault in the portfolio, analyze risk factors.
+
+### Portfolio Risk Summary
+```
+PORTFOLIO RISK PROFILE
+======================
+
+Weighted Average Risk Score: [X]/100
+
+Risk Distribution:
+- Low Risk (<30): [X]% of portfolio
+- Medium Risk (30-60): [X]% of portfolio
+- High Risk (>60): [X]% of portfolio
+
+Concentration Risk:
+- Largest position: [X]% ([Vault Name])
+- Top 3 positions: [X]% of portfolio
+
+Diversification Score: [X]/10
+```
+
+## Step 3: Performance Analysis
+
+### Historical Performance
+**Tool**: `get_vault_performance`
+
+For each vault, analyze 30-day performance.
+
+### Performance Summary
+```
+PORTFOLIO PERFORMANCE (30 Days)
+===============================
+
+Total Return: $[X] ([+/-X]%)
+
+By Vault:
+| Vault | Return | APR Realized | vs Expected |
+|-------|--------|--------------|-------------|
+| [Name] | $[X] | [X]% | [+/-X]% |
+```
+
+## Step 4: Forward Projections
+
+### Yield Prediction
+**Tool**: `predict_yield`
+
+For significant positions, generate yield predictions.
+
+## Step 5: Optimization Analysis
+
+### Portfolio Optimization
+**Tool**: `optimize_portfolio`
+
+Analyze rebalancing opportunities using strategies:
+- **Equal Weight**: Maximum diversification
+- **Risk Parity**: Balanced risk contribution
+- **Max Sharpe**: Risk-adjusted returns
+- **Min Variance**: Minimized volatility
+
+## Step 6: Health Check Summary
+
+```
+PORTFOLIO HEALTH CHECK SUMMARY
+==============================
+
+Overall Health Score: [X]/100
+
+STRENGTHS
+---------
++ [Positive finding 1]
++ [Positive finding 2]
+
+AREAS FOR ATTENTION
+-------------------
+- [Concern 1]
+- [Concern 2]
+
+SUGGESTED ACTIONS
+-----------------
+1. [Priority action 1]
+2. [Priority action 2]
+
+NEXT REVIEW
+-----------
+Recommended: [Date - typically 30 days]
+```
+
+## Communication Guidelines
+
+### Language Standards
+
+**NEVER use**:
+- "I recommend you invest..."
+- "You should buy/deposit..."
+- "This is a good investment..."
+
+**ALWAYS use**:
+- "Historical data shows..."
+- "For educational purposes, consider..."
+- "This vault's characteristics include..."
+
+---
+
+*This skill is part of the Lagoon MCP ecosystem. For technical tool documentation, refer to the MCP tool descriptions.*

package/skills/lagoon-portfolio-review/rebalancing-criteria.md

@@ -0,0 +1,85 @@
+# Rebalancing Criteria Guide
+
+## Trigger Thresholds
+
+### Concentration Thresholds
+| Level | Single Vault % | Action |
+|-------|----------------|--------|
+| Acceptable | <30% | No action |
+| Monitor | 30-40% | Note for next review |
+| Attention | 40-50% | Plan rebalancing |
+| Urgent | >50% | Immediate consideration |
+
+### Risk Score Thresholds
+| Level | Score Change | Action |
+|-------|--------------|--------|
+| Stable | <10 points | No action |
+| Drifting | 10-20 points | Monitor |
+| Elevated | 20-30 points | Review position |
+| Critical | >30 points | Consider reduction |
+
+### Performance Thresholds
+| Level | vs Expected APR | Duration | Action |
+|-------|-----------------|----------|--------|
+| Normal | >90% | - | No action |
+| Underperforming | 70-90% | <30 days | Monitor |
+| Underperforming | 70-90% | >30 days | Review |
+| Significant | <70% | >30 days | Consider exit |
+| Critical | <50% | >14 days | Urgent review |
+
+## Rebalancing Strategies
+
+### Conservative Approach
+- Threshold: 50% concentration trigger
+- Action: Gradual rebalancing over 2-4 transactions
+- Goal: No single position >30%
+
+### Moderate Approach
+- Threshold: 40% concentration trigger
+- Action: Rebalance when threshold crossed
+- Goal: No single position >25%
+
+### Active Approach
+- Threshold: 30% concentration trigger
+- Action: Regular optimization
+- Goal: Target allocation maintained
+
+## Cost Considerations
+
+### Transaction Costs to Factor
+1. **Gas fees**: Estimate based on current network conditions
+2. **Slippage**: Larger positions may have higher slippage
+3. **Exit fees**: Some vaults may have redemption fees
+
+### Cost-Benefit Analysis
+```
+Net Benefit = Expected Improvement - Transaction Costs
+
+Only rebalance if:
+- Net Benefit > 0 for projected holding period
+- Or risk reduction justifies the cost
+```
+
+## Rebalancing Process
+
+### Step 1: Identify Opportunity
+- Compare current vs target allocation
+- Calculate deviation magnitude
+
+### Step 2: Estimate Costs
+- Get gas estimates for transactions
+- Factor in any vault-specific fees
+
+### Step 3: Calculate Net Benefit
+- Project improvement in returns or risk
+- Compare to transaction costs
+
+### Step 4: Execute if Beneficial
+- Start with largest deviations
+- Consider batching transactions
+- Monitor execution for slippage
+
+### Step 5: Document
+- Record rationale for change
+- Note new allocation
+- Set next review date

package/skills/lagoon-portfolio-review/review-framework.md

@@ -0,0 +1,70 @@
+# Portfolio Review Framework
+
+## Review Checklist
+
+### Phase 1: Data Collection
+- [ ] Retrieve current portfolio positions
+- [ ] Note entry prices/dates if available
+- [ ] Identify any pending deposits/withdrawals
+
+### Phase 2: Risk Assessment
+- [ ] Calculate weighted average risk score
+- [ ] Identify concentration risks
+- [ ] Check diversification across:
+  - [ ] Asset types (stablecoins, ETH, BTC, etc.)
+  - [ ] Chains (Ethereum, Arbitrum, etc.)
+  - [ ] Curators (strategy managers)
+  - [ ] Strategy types (lending, LP, derivatives)
+
+### Phase 3: Performance Review
+- [ ] Calculate absolute returns (USD)
+- [ ] Calculate relative returns (%)
+- [ ] Compare to expected APR
+- [ ] Identify outperformers and underperformers
+
+### Phase 4: Forward Assessment
+- [ ] Review yield predictions
+- [ ] Assess confidence levels
+- [ ] Note any market conditions affecting outlook
+
+### Phase 5: Action Planning
+- [ ] Identify rebalancing opportunities
+- [ ] Calculate potential improvements
+- [ ] Consider transaction costs
+- [ ] Prioritize actions
+
+## Key Metrics to Track
+
+| Metric | How to Calculate | Target |
+|--------|------------------|--------|
+| Portfolio Concentration | Largest position % | <40% |
+| Risk-Weighted Return | Return / Risk Score | Maximize |
+| Diversification Score | # unique assets/chains/curators | High |
+| APR Achievement | Realized APR / Expected APR | >90% |
+| Risk Stability | Risk score change (30d) | <15 points |
+
+## Review Frequency Guide
+
+| Portfolio Size | Recommended Frequency |
+|----------------|----------------------|
+| <$10K | Quarterly |
+| $10K-$50K | Monthly |
+| $50K-$100K | Bi-weekly |
+| >$100K | Weekly |
+
+## Red Flags to Always Address
+
+1. **Single vault >50% of portfolio**
+   - Immediate diversification recommended
+
+2. **Risk score >70 in any vault**
+   - Review and consider reduction
+
+3. **APR at 0% for >7 days**
+   - Investigate vault health
+
+4. **TVL down >50% in 30 days**
+   - Assess liquidity risk
+
+5. **Curator issues**
+   - Research and consider exit

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]
+```