@lagoon-protocol/lagoon-mcp 0.1.3 → 0.2.1

package/dist/skills/portfolio-review.js

@@ -0,0 +1,464 @@
+/**
+ * Lagoon Portfolio Review Skill
+ *
+ * Provides structured portfolio health checks for existing Lagoon users,
+ * including risk assessment, performance analysis, and rebalancing guidance.
+ *
+ * @module skills/portfolio-review
+ */
+import { COMMON_DISCLAIMERS, COMMUNICATION_GUIDELINES } from './shared.js';
+/**
+ * Main skill instructions
+ */
+const INSTRUCTIONS = `# 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.
+
+${COMMON_DISCLAIMERS.full}
+
+## 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:
+\`\`\`json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "responseFormat": "detailed"
+}
+\`\`\`
+
+### 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
+(Based on asset types, chains, curators, strategies)
+\`\`\`
+
+## Step 3: Performance Analysis
+
+### Historical Performance
+**Tool**: \`get_vault_performance\`
+
+For each vault:
+\`\`\`json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "timeRange": "30d",
+  "responseFormat": "detailed"
+}
+\`\`\`
+
+### Performance Summary
+\`\`\`
+PORTFOLIO PERFORMANCE (30 Days)
+===============================
+
+Total Return: $[X] ([+/-X]%)
+
+By Vault:
+| Vault | Return | APR Realized | vs Expected |
+|-------|--------|--------------|-------------|
+| [Name] | $[X] | [X]% | [+/-X]% |
+
+Performance Assessment:
+- Outperforming: [N] vaults
+- Meeting expectations: [N] vaults
+- Underperforming: [N] vaults
+\`\`\`
+
+## Step 4: Forward Projections
+
+### Yield Prediction
+**Tool**: \`predict_yield\`
+
+For significant positions:
+\`\`\`json
+{
+  "vaultAddress": "0x...",
+  "chainId": 1,
+  "timeRange": "30d",
+  "responseFormat": "detailed"
+}
+\`\`\`
+
+### Projection Summary
+\`\`\`
+PROJECTED RETURNS (Next 30 Days)
+================================
+
+Based on current positions and historical trends:
+
+| Vault | Current APR | Predicted APR | Confidence |
+|-------|-------------|---------------|------------|
+| [Name] | [X]% | [X]% | [High/Med/Low] |
+
+Total Projected Return: $[X] - $[X]
+(Range based on confidence intervals)
+
+Note: Projections are estimates based on historical trends.
+Actual results may vary significantly.
+\`\`\`
+
+## Step 5: Optimization Analysis
+
+### Portfolio Optimization
+**Tool**: \`optimize_portfolio\`
+
+Analyze rebalancing opportunities:
+\`\`\`json
+{
+  "vaultAddresses": ["0x...", "0x..."],
+  "chainId": 1,
+  "currentPositions": [
+    {"vaultAddress": "0x...", "valueUsd": 10000}
+  ],
+  "strategy": "max_sharpe",
+  "responseFormat": "detailed"
+}
+\`\`\`
+
+### Optimization Strategies
+- **Equal Weight**: Maximum diversification
+- **Risk Parity**: Balanced risk contribution
+- **Max Sharpe**: Risk-adjusted returns
+- **Min Variance**: Minimized volatility
+
+## Step 6: Recommendations Framework
+
+### Health Check Summary
+
+Present findings using this framework:
+
+\`\`\`
+PORTFOLIO HEALTH CHECK SUMMARY
+==============================
+
+Overall Health Score: [X]/100
+
+STRENGTHS
+---------
++ [Positive finding 1]
++ [Positive finding 2]
+
+AREAS FOR ATTENTION
+-------------------
+- [Concern 1]
+- [Concern 2]
+
+REBALANCING TRIGGERS
+--------------------
+The following conditions suggest rebalancing may be beneficial:
+
+[x] Single position >40% of portfolio
+[ ] Risk score >60 in any vault
+[x] APR underperformance >30% for 30+ days
+[ ] Vault TVL declined >50%
+
+SUGGESTED ACTIONS
+-----------------
+1. [Priority action 1]
+2. [Priority action 2]
+
+NEXT REVIEW
+-----------
+Recommended: [Date - typically 30 days]
+\`\`\`
+
+## Rebalancing Decision Framework
+
+### When to Consider Rebalancing
+
+**Strong Signals** (Consider immediate action):
+- Single position grew to >50% of portfolio
+- Vault risk score increased >30 points
+- Curator issues or reputation concerns
+- Persistent underperformance (>50% below target for 60+ days)
+
+**Moderate Signals** (Monitor and plan):
+- Single position at 35-50% of portfolio
+- Risk score increased 15-30 points
+- Moderate underperformance (30-50% below target)
+- New vaults offering better risk/return
+
+**Weak Signals** (Note for next review):
+- Minor position drift (<35% concentration)
+- Small risk score changes (<15 points)
+- Temporary underperformance (<30 days)
+
+### Rebalancing Considerations
+
+Before suggesting rebalancing:
+1. **Transaction costs**: Factor in gas fees and slippage
+2. **Tax implications**: Note potential taxable events
+3. **Timing**: Consider market conditions
+4. **Lock-ups**: Check vault exit conditions
+
+${COMMUNICATION_GUIDELINES}
+
+## Post-Review Guidance
+
+### Immediate Actions
+1. Document key findings for future reference
+2. Set reminder for next review (30 days recommended)
+3. Monitor any flagged concerns weekly
+
+### Ongoing Monitoring
+- Check vault performance weekly
+- Review risk scores bi-weekly
+- Full portfolio review monthly or quarterly`;
+/**
+ * Review framework resource
+ */
+const REVIEW_FRAMEWORK = `# 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`;
+/**
+ * Rebalancing criteria resource
+ */
+const REBALANCING_CRITERIA = `# 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`;
+/**
+ * Lagoon Portfolio Review Skill Definition
+ */
+export const lagoonPortfolioReviewSkill = {
+    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.',
+    triggers: [
+        'portfolio review',
+        'review my portfolio',
+        'portfolio health',
+        'check my portfolio',
+        'portfolio analysis',
+        'how is my portfolio',
+        'position check',
+        'check my positions',
+        'my vaults',
+        'my holdings',
+        'rebalance',
+        'should i rebalance',
+        'portfolio optimization',
+        'optimize my portfolio',
+        'portfolio performance',
+        'how are my investments doing',
+        'portfolio assessment',
+        'quarterly review',
+    ],
+    audience: 'customer-existing',
+    instructions: INSTRUCTIONS,
+    resources: {
+        framework: REVIEW_FRAMEWORK,
+        rebalancing: REBALANCING_CRITERIA,
+    },
+    metadata: {
+        version: '1.0.0',
+        category: 'portfolio',
+        primaryTools: [
+            'get_user_portfolio',
+            'analyze_risk',
+            'get_vault_performance',
+            'predict_yield',
+            'optimize_portfolio',
+        ],
+        estimatedTokens: 3200,
+        lastUpdated: '2024-12-15',
+    },
+};
+export default lagoonPortfolioReviewSkill;
+//# sourceMappingURL=portfolio-review.js.map

package/dist/skills/portfolio-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portfolio-review.js","sourceRoot":"","sources":["../../src/skills/portfolio-review.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE3E;;GAEG;AACH,MAAM,YAAY,GAAG;;;;EAInB,kBAAkB,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkOvB,wBAAwB;;;;;;;;;;;;6CAYmB,CAAC;AAE9C;;GAEG;AACH,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAqEO,CAAC;AAEjC;;GAEG;AACH,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAoFN,CAAC;AAExB;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAgB;IACrD,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EACT,iPAAiP;IACnP,QAAQ,EAAE;QACR,kBAAkB;QAClB,qBAAqB;QACrB,kBAAkB;QAClB,oBAAoB;QACpB,oBAAoB;QACpB,qBAAqB;QACrB,gBAAgB;QAChB,oBAAoB;QACpB,WAAW;QACX,aAAa;QACb,WAAW;QACX,oBAAoB;QACpB,wBAAwB;QACxB,uBAAuB;QACvB,uBAAuB;QACvB,8BAA8B;QAC9B,sBAAsB;QACtB,kBAAkB;KACnB;IACD,QAAQ,EAAE,mBAAmB;IAC7B,YAAY,EAAE,YAAY;IAC1B,SAAS,EAAE;QACT,SAAS,EAAE,gBAAgB;QAC3B,WAAW,EAAE,oBAAoB;KAClC;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,OAAO;QAChB,QAAQ,EAAE,WAAW;QACrB,YAAY,EAAE;YACZ,oBAAoB;YACpB,cAAc;YACd,uBAAuB;YACvB,eAAe;YACf,oBAAoB;SACrB;QACD,eAAe,EAAE,IAAI;QACrB,WAAW,EAAE,YAAY;KAC1B;CACF,CAAC;AAEF,eAAe,0BAA0B,CAAC"}

package/dist/skills/protocol-health.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Lagoon Protocol Health Skill
+ *
+ * Enables internal operations team to monitor protocol-wide KPIs,
+ * identify trends, generate executive summaries, and flag at-risk vaults.
+ *
+ * @module skills/protocol-health
+ */
+import type { LagoonSkill } from './types.js';
+/**
+ * Lagoon Protocol Health Skill Definition
+ */
+export declare const lagoonProtocolHealthSkill: LagoonSkill;
+export default lagoonProtocolHealthSkill;
+//# sourceMappingURL=protocol-health.d.ts.map

package/dist/skills/protocol-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-health.d.ts","sourceRoot":"","sources":["../../src/skills/protocol-health.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAoZ9C;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAuCvC,CAAC;AAEF,eAAe,yBAAyB,CAAC"}