@lagoon-protocol/lagoon-mcp 0.1.3 → 0.2.0

package/skills/lagoon-onboarding/risk-interpretation.md

@@ -0,0 +1,188 @@
+# Risk Interpretation Guide for Beginners
+
+How to explain risk concepts to first-time DeFi users.
+
+## Risk Score Explained Simply
+
+The overall risk score (0-100) is a composite measure of five factors. Lower is safer.
+
+### Visual Risk Scale
+
+```
+0    20    40    60    80    100
+|-----|-----|-----|-----|-----|
+ Very  Low   Med  High  Very
+ Low               High
+
+Conservative users: Stay under 40
+Moderate users: 30-60 acceptable
+Aggressive users: Up to 80 with awareness
+```
+
+## Factor-by-Factor Explanations
+
+### TVL Risk (Total Value Locked)
+
+**What it means**: How much money is deposited in the vault.
+
+**Why it matters**:
+- Higher TVL = more people trust this vault
+- Higher TVL = easier to withdraw without impact
+- Very low TVL = potential liquidity issues
+
+**User-friendly explanation**:
+> "Think of TVL like a swimming pool. A bigger pool (higher TVL) means more room for swimmers and easier to get in and out. A small pool can get crowded quickly."
+
+**Thresholds for beginners**:
+| TVL | Risk Level | Recommendation |
+|-----|------------|----------------|
+| >$10M | Very Low | Excellent liquidity |
+| $5M-$10M | Low | Good for most users |
+| $1M-$5M | Medium | Acceptable with awareness |
+| $500K-$1M | Higher | Caution advised |
+| <$500K | High | Not recommended for beginners |
+
+### Concentration Risk
+
+**What it means**: Whether a few large depositors dominate the vault.
+
+**Why it matters**:
+- High concentration = if one whale exits, it affects everyone
+- Low concentration = more distributed, more stable
+
+**User-friendly explanation**:
+> "Imagine a bus. If one person takes up half the seats, when they leave, the bus feels much emptier. We prefer vaults where no single person dominates."
+
+**Warning signs**:
+- Top 5 depositors hold >50% of TVL
+- Any single depositor >20% of TVL
+
+### Volatility Risk
+
+**What it means**: How much the vault's returns fluctuate.
+
+**Why it matters**:
+- High volatility = unpredictable returns
+- Low volatility = more consistent, easier to plan
+
+**User-friendly explanation**:
+> "Volatility is like weather predictability. Some places have consistent weather (low volatility), others have wild swings (high volatility). For beginners, consistent weather is easier to plan around."
+
+**Interpretation**:
+| APR Variation | Risk Level | Suitable For |
+|---------------|------------|--------------|
+| <5% range | Low | Conservatives |
+| 5-15% range | Medium | Most users |
+| >15% range | High | Risk-tolerant only |
+
+### Age Risk
+
+**What it means**: How long the vault has been operating.
+
+**Why it matters**:
+- Older vaults have proven their strategy works
+- Newer vaults are unproven, even if promising
+
+**User-friendly explanation**:
+> "Age is like a restaurant track record. A restaurant open for 5 years has proven it can stay in business. A new restaurant might be great, but it's less proven."
+
+**Guidelines**:
+| Vault Age | Risk Level | Recommendation |
+|-----------|------------|----------------|
+| >12 months | Very Low | Well-established |
+| 6-12 months | Low | Good track record |
+| 3-6 months | Medium | Monitor closely |
+| 1-3 months | Higher | Small amounts only |
+| <1 month | High | Not for beginners |
+
+### Curator Risk
+
+**What it means**: The reputation and experience of the vault manager.
+
+**Why it matters**:
+- Experienced curators know how to handle market conditions
+- New curators may lack experience during stress
+
+**User-friendly explanation**:
+> "The curator is like a fund manager. You want someone with a track record of managing money well, not their first day on the job."
+
+**Evaluation criteria**:
+- How long have they been curating?
+- How much total value do they manage?
+- What's their historical performance?
+- Are they publicly known and accountable?
+
+## Combining Risk Factors
+
+### The Complete Picture
+
+Don't look at factors in isolation. Consider:
+
+1. **Factor interactions**: Low TVL + High concentration = Double caution
+2. **Profile alignment**: High volatility might be okay for aggressive users
+3. **Compensating factors**: New vault but established curator = mitigates age risk
+
+### Risk Score Integration
+
+Present the overall picture:
+
+```
+Overall Risk Assessment: [Score]/100 - [Category]
+
+Strengths:
++ [Factor with good score]
++ [Another positive]
+
+Areas of Concern:
+- [Factor with concerning score]
+- [Explanation of why it matters]
+
+Profile Fit: [GOOD / ACCEPTABLE / CAUTION / MISMATCH]
+```
+
+## Red Flags Checklist
+
+### Automatic Disqualifiers
+
+- [ ] TVL under $100K
+- [ ] Curator unverified or anonymous
+- [ ] Recent security incident
+- [ ] APR seems impossibly high (>50% without clear source)
+
+### Yellow Flags (Proceed with Caution)
+
+- [ ] Vault less than 90 days old
+- [ ] Curator less than 6 months experience
+- [ ] TVL declining rapidly (>30% in 30 days)
+- [ ] Single depositor >30% of TVL
+- [ ] Strategy documentation unclear
+
+## User Communication Templates
+
+### When Risk is Appropriate
+
+> "This vault's risk score of [X] aligns well with your [profile] preferences. The main factors contributing to this score are [factors]. Based on the historical data, this appears suitable for your stated goals."
+
+### When Risk is Higher Than Profile
+
+> "This vault's risk score of [X] is higher than typically recommended for [profile] investors. The main concerns are [factors]. If you're still interested, consider: (1) reducing your deposit amount, (2) setting stricter monitoring triggers, or (3) exploring these lower-risk alternatives: [alternatives]."
+
+### When Risk Data is Limited
+
+> "This vault has limited historical data because it's relatively new ([X] days old). While the current metrics look [assessment], the limited track record means there's more uncertainty. For educational purposes, consider starting with a smaller amount than planned, and monitoring more frequently."
+
+## Questions Users Should Ask
+
+Help users develop critical thinking by suggesting questions:
+
+1. "What could cause this vault's APR to drop significantly?"
+2. "How quickly can I withdraw if I need to exit?"
+3. "What happens to my funds if the underlying protocol has issues?"
+4. "How does this curator handle market downturns?"
+5. "What are the fees and how do they affect my returns?"
+
+## Disclaimer Reminder
+
+Always conclude risk discussions with:
+
+> "Remember: All investments carry risk, including the potential loss of your entire deposit. This analysis is educational, not financial advice. Past performance does not guarantee future results. Consider consulting a financial advisor for personalized guidance."

package/skills/lagoon-onboarding/tool-sequences.md

@@ -0,0 +1,217 @@
+# Lagoon Onboarding Tool Sequences
+
+Detailed tool usage patterns for the onboarding workflow.
+
+## Quick Reference: Tool Selection
+
+| Analysis Need | Primary Tool | Fallback |
+|--------------|--------------|----------|
+| Find vaults matching profile | `search_vaults` | `query_graphql` |
+| Assess vault risk | `analyze_risk` | Manual analysis |
+| Check historical performance | `get_vault_performance` | `get_price_history` |
+| Project future returns | `simulate_vault` | Manual calculation |
+| Compare shortlisted vaults | `compare_vaults` | Side-by-side manual |
+
+## Detailed Tool Parameters by Profile
+
+### Conservative User Search
+
+```json
+{
+  "filters": {
+    "state_totalAssetsUsd_gte": 5000000,
+    "isVisible_eq": true
+  },
+  "orderBy": "totalAssetsUsd",
+  "orderDirection": "desc",
+  "maxResults": 5,
+  "responseFormat": "summary"
+}
+```
+
+**Post-filter**: Only recommend vaults where `analyze_risk` returns score <40.
+
+### Moderate User Search
+
+```json
+{
+  "filters": {
+    "state_totalAssetsUsd_gte": 1000000,
+    "isVisible_eq": true
+  },
+  "orderBy": "totalAssetsUsd",
+  "orderDirection": "desc",
+  "maxResults": 5,
+  "responseFormat": "summary"
+}
+```
+
+**Post-filter**: Accept vaults with risk score 30-60.
+
+### Aggressive User Search
+
+```json
+{
+  "filters": {
+    "state_totalAssetsUsd_gte": 500000,
+    "isVisible_eq": true
+  },
+  "orderBy": "totalAssetsUsd",
+  "orderDirection": "desc",
+  "maxResults": 5,
+  "responseFormat": "summary"
+}
+```
+
+**Post-filter**: Accept higher risk scores but flag concerns.
+
+## Risk Analysis Workflow
+
+### Step 1: Call analyze_risk
+
+```json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "responseFormat": "detailed"
+}
+```
+
+### Step 2: Interpret Results
+
+**Risk Score Mapping**:
+| Score Range | Category | User Action |
+|-------------|----------|-------------|
+| 0-20 | Very Low | Excellent for conservatives |
+| 21-40 | Low | Good for most profiles |
+| 41-60 | Medium | Moderate profile appropriate |
+| 61-80 | High | Aggressive only, with warnings |
+| 81-100 | Very High | Discourage for beginners |
+
+### Step 3: Factor-by-Factor Explanation
+
+For each risk factor, explain in user-friendly terms:
+
+- **TVL Risk**: "This measures how much total value is in the vault. Higher TVL generally means more stability and easier exits."
+
+- **Concentration Risk**: "This shows if a few large depositors dominate the vault. High concentration means one large withdrawal could impact everyone."
+
+- **Volatility Risk**: "This reflects how much the vault's returns have fluctuated. Lower volatility means more predictable returns."
+
+- **Age Risk**: "Newer vaults have less track record. More established vaults have proven their strategy over time."
+
+- **Curator Risk**: "This assesses the vault manager's experience and reputation. Established curators with good track records score lower risk."
+
+## Performance Analysis Workflow
+
+### Step 1: Get Historical Data
+
+```json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "timeRange": "30d",
+  "responseFormat": "summary"
+}
+```
+
+### Step 2: Key Metrics to Highlight
+
+1. **APR Trend**: Is it stable, increasing, or declining?
+2. **Volatility**: High volatility = unpredictable returns
+3. **Consistency**: Does APR stay within a reasonable range?
+
+### Step 3: Interpretation Guidelines
+
+| APR Behavior | Interpretation | Recommendation |
+|--------------|----------------|----------------|
+| Stable within 5% | Consistent strategy | Good sign |
+| Gradual increase | Growing efficiency | Positive |
+| Gradual decrease | Strategy underperforming | Monitor closely |
+| High volatility | Unpredictable returns | Caution for beginners |
+
+## Simulation Workflow
+
+### Step 1: Gather User Inputs
+
+- Deposit amount (in asset units)
+- Expected APR (from performance analysis)
+- Time horizon (from profile assessment)
+
+### Step 2: Call simulate_vault
+
+```json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "newTotalAssets": "current_tvl + user_deposit",
+  "includeAPRCalculations": true
+}
+```
+
+### Step 3: Present Scenarios
+
+Always present multiple scenarios:
+- **Expected**: Based on current APR
+- **Conservative**: 20% lower APR
+- **Optimistic**: 20% higher APR (if sustainable)
+
+**Important**: Always caveat that these are projections, not guarantees.
+
+## Comparison Workflow
+
+When user has shortlisted 2-3 vaults:
+
+### Step 1: Call compare_vaults
+
+```json
+{
+  "vaultAddresses": ["0x...", "0x...", "0x..."],
+  "chainId": 1,
+  "responseFormat": "summary"
+}
+```
+
+### Step 2: Create Comparison Matrix
+
+| Metric | Vault A | Vault B | Vault C | Best For |
+|--------|---------|---------|---------|----------|
+| APR | | | | Highest yield |
+| TVL | | | | Most liquidity |
+| Risk Score | | | | Lowest risk |
+| Age | | | | Most established |
+
+### Step 3: Profile-Based Recommendation
+
+Map comparison results back to user profile:
+- Conservative: Prioritize lowest risk score
+- Moderate: Balance APR and risk
+- Aggressive: Prioritize APR with acceptable risk
+
+## Error Handling
+
+### Tool Fails
+
+If a tool call fails:
+1. Acknowledge the limitation
+2. Explain what information is missing
+3. Proceed with available data
+4. Recommend user verify on-chain
+
+### Insufficient Data
+
+If vault has limited history:
+1. Clearly state the data limitation
+2. Increase caution recommendations
+3. Suggest smaller initial deposit
+4. Recommend more frequent monitoring
+
+## Caching Considerations
+
+Tool data has different freshness:
+- `search_vaults`: 10 min cache (discovery is okay)
+- `analyze_risk`: 15 min cache (relatively stable)
+- `get_vault_performance`: 30 min cache (historical data)
+- `simulate_vault`: No cache (real-time calculation)
+
+For time-sensitive decisions, remind users to verify current on-chain data.

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