[FEATURE] Portfolio Personalization

[vitalune]

🚀 Feature Request Summary

Add persistent portfolio management with intelligent AI integration, enabling users to store their investment holdings locally and receive personalized, context-aware analysis from AI agents across all MaverickMCP tools.

💰 Financial Disclaimer Acknowledgment

• ✅ I understand this is educational software and not financial advice
• ✅ This feature request is for educational/technical purposes, not investment recommendations
• ✅ I understand that any financial analysis features will include appropriate disclaimers

🎯 Problem/Use Case

What problem does this feature solve?

Currently, MaverickMCP has excellent portfolio analysis tools (risk_adjusted_analysis, portfolio_correlation_analysis, compare_tickers, backtest_portfolio), but they have a critical limitation: users must manually specify tickers every single time. There's no persistent storage of holdings, cost basis, or purchase history.

This creates friction:

• ❌ "Analyze correlation in my portfolio" → User must list all tickers again
• ❌ AI agents don't know what the user actually owns
• ❌ No tracking of cost basis, entry dates, or position notes
• ❌ Risk analysis can't reference actual holdings
• ❌ Repetitive ticker entry for every analysis request

Who would benefit from this feature?

• ✅ Individual traders learning technical analysis (primary)
• ✅ MCP developers building financial tools
• ✅ Educational institutions teaching finance
• ✅ Open source contributors
• ☐ Other: ___________

💡 Proposed Solution

Describe your ideal solution:

A two-phase implementation that transforms MaverickMCP into a truly personalized AI financial assistant:

Phase 1: Persistent Portfolio Storage (Foundation)

4 new MCP tools for portfolio management:

• add_portfolio_position() - Store positions with cost basis averaging
• get_my_portfolio() - View all holdings with summary statistics
• remove_portfolio_position() - Remove specific positions
• clear_my_portfolio() - Clear all positions (with confirmation)

MCP Resource:

• portfolio://my-holdings - Makes portfolio automatically available as AI context

Data tracked per position:

• Ticker symbol
• Number of shares
• Cost basis (with automatic averaging for additional purchases)
• Purchase date (earliest for averaged positions)
• Optional notes (investment thesis, reminders)

Phase 2: Intelligent Integration (Transformation)

Enhance existing tools to auto-use stored portfolio:

Risk-Adjusted Analysis Enhancement

• Automatically detect if user owns the analyzed stock
• Display current P&L, position size vs. portfolio
• Personalized recommendations based on actual holdings

Correlation Analysis Enhancement

• portfolio_correlation_analysis() with no arguments → uses stored holdings
• No more manually listing tickers
• "How correlated is my portfolio?" just works

Comparison Tools Enhancement

• compare_tickers() with no arguments → compares YOUR holdings
• Automatic filtering of owned stocks in screening results

AI Context Enhancement

• Portfolio resource includes live P&L calculations
• Current values, unrealized gains/losses
• Position percentages, diversification metrics
• AI agents automatically reference holdings in all analysis

Alternative approaches you've considered:

1. External portfolio tracking integration (Rejected)

• Pros: Professional features, live sync
• Cons: Privacy concerns, API complexity, against MaverickMCP's local-first philosophy

2. Simple CSV import/export (Rejected as primary)

• Pros: Simple implementation
• Cons: Poor UX, no persistence, no AI integration

3. Separate portfolio database (Rejected)

• Pros: Clean separation
• Cons: Doesn't integrate with existing tools, defeats purpose

🔧 Technical Details

Component Area:

• ✅ Data fetching (current price lookups for P&L)
• ✅ Portfolio analysis (risk metrics, optimization)
• ✅ MCP tools (new tools, tool improvements)
• ✅ Database/Caching (portfolio storage)
• ✅ Claude Desktop integration (AI context injection)

Implementation Complexity:

• ☐ Simple
• ✅ Medium (new functionality, moderate effort)
• ☐ Complex
• ☐ I'm not sure

Phase 1 Complexity: Medium (2-3 days)

• Domain entities following existing DDD patterns
• Database models with SQLAlchemy
• Alembic migration
• MCP tools and resource
• Comprehensive tests

Phase 2 Complexity: Medium (1-2 days)

• Modify 3-4 existing tools
• Enhance portfolio resource with live data
• Integration tests
• Documentation updates

Dependencies:

• ✅ No new external APIs required
• ✅ Uses existing DataService for price lookups
• ✅ Follows existing SQLAlchemy/Alembic patterns
• ✅ Compatible with current DDD architecture

📊 Examples/Mockups

Phase 1: Portfolio Management

# Natural language with Claude Desktop:
"Add 10 shares of AAPL to my portfolio at $150 purchased on 2024-01-15"
# → add_portfolio_position("AAPL", 10, 150.00, "2024-01-15")

"Add 10 more AAPL shares at $170 on 2024-02-01"
# → Automatically averages: 20 shares @ $160.00 cost basis

"Show me my portfolio"
# → Returns:
{
    "name": "My Portfolio",
    "total_positions": 3,
    "total_invested": 12500.00,
    "positions": [
        {
            "ticker": "AAPL",
            "shares": 20,
            "cost_basis": 160.00,
            "total_cost": 3200.00,
            "purchase_date": "2024-01-15",
            "notes": "Long-term hold"
        },
        # ... more positions
    ]
}

"Remove MSFT from my portfolio"
# → remove_portfolio_position("MSFT")

Phase 2: Intelligent Integration

# BEFORE (current behavior):
"Analyze correlation in my portfolio"
# → ❌ Error: "Please provide ticker symbols"

# AFTER (with integration):
"Analyze correlation in my portfolio"
# → ✅ portfolio_correlation_analysis() automatically uses stored holdings
# → Analyzes correlation between AAPL, MSFT, NVDA, GOOGL (your holdings)

# BEFORE:
"Compare my tech stocks"
# → ❌ User must manually specify: compare_tickers(["AAPL", "MSFT", "GOOGL"])

# AFTER:
"Compare my tech stocks"
# → ✅ AI agent queries portfolio, filters tech sector, auto-compares

# Risk analysis with position awareness:
"Analyze MARA with my risk profile"
# → Returns:
{
    "symbol": "MARA",
    "risk_analysis": {...},
    "your_position": {
        "owned": true,
        "shares": 50,
        "cost_basis": 18.50,
        "current_price": 22.30,
        "current_value": 1115.00,
        "unrealized_pnl": 190.00,
        "pnl_percentage": 20.54,
        "position_size_vs_portfolio": "8.9%"
    },
    "recommendations": "Consider taking partial profits given 20%+ gain..."
}

AI Context Enhancement

# What AI agents automatically see:

USER PORTFOLIO CONTEXT (for personalized analysis):

Portfolio: My Portfolio
Total Positions: 4
Total Invested: $12,500.00
Current Value: $13,750.00
Total P&L: +$1,250.00 (+10.0%)

Current Holdings:
  • AAPL: 20 shares @ $160.00 cost basis
    Current: $175.50 | Value: $3,510.00 | P&L: +$310.00 (+9.7%)
    Notes: Long-term hold, core position
    
  • MARA: 50 shares @ $18.50 cost basis
    Current: $22.30 | Value: $1,115.00 | P&L: +$190.00 (+20.5%)
    Notes: Bitcoin mining exposure
    
  • NVDA: 5 shares @ $450.00 cost basis
    Current: $520.00 | Value: $2,600.00 | P&L: +$350.00 (+15.6%)
    
  • RIOT: 100 shares @ $12.00 cost basis
    Current: $13.50 | Value: $1,350.00 | P&L: +$150.00 (+12.5%)

Portfolio Metrics:
- Sector Exposure: Technology 72%, Bitcoin Mining 28%
- Largest Position: AAPL (25.5% of portfolio)
- Best Performer: MARA (+20.5%)
- Average Position Return: +12.4%

When providing analysis, reference the user's actual holdings and provide
personalized insights based on their specific portfolio composition, risk
exposure, and performance metrics.

Reference implementations:

• Personal Capital's portfolio tracking (but local-first)
• Fidelity's position tracking (but simplified)
• Interactive Brokers' portfolio view (but educational focus)

🎓 Educational Value

Learning objectives:

• Cost basis management - Understanding average cost calculation
• Position sizing - How much capital in each holding
• Diversification analysis - Sector concentration, correlation
• Risk management - Position size relative to portfolio
• Performance tracking - Unrealized P&L, percentage gains
• Portfolio construction - Building balanced portfolios over time

What financial concepts would this help users learn?

• Cost basis averaging (dollar-cost averaging effects)
• Portfolio diversification principles
• Position sizing strategies
• Risk-adjusted returns in context of actual holdings
• Correlation and how different assets move together
• Sector exposure and concentration risk

What technical skills would developers gain?

• Domain-Driven Design (DDD) architecture
• SQLAlchemy ORM with complex relationships
• Alembic migrations for schema evolution
• MCP protocol: tools + resources working together
• AI context injection and prompt engineering
• Financial calculations (P&L, averaging, percentages)
• Integration patterns between modular tools

Documentation needs:

• ✅ Code examples needed (natural language + tool calls)
• ✅ Tutorial/guide needed (getting started with portfolio)
• ✅ Financial concept explanation needed (cost basis, averaging)
• ✅ API documentation needed (tool parameters, return formats)

🤝 Contribution

Are you willing to contribute to this feature?

• ✅ Yes, I can implement this myself
• ✅ Yes, I can help with testing/documentation
• ✅ Yes, I can provide domain expertise
• ☐ I can help but need guidance
• ☐ I cannot contribute but would love to use it

Your relevant experience:

• Financial analysis background: ✅ Understanding of portfolio management, risk analysis, cost basis accounting
• Python development experience: ✅ Professional experience with Python, FastAPI, SQLAlchemy
• MCP protocol familiarity: ✅ Studied MaverickMCP architecture, FastMCP patterns
• Other relevant skills:
  • Domain-Driven Design (DDD) patterns
  • Database design and migrations
  • Testing best practices (pytest, fixtures)
  • Technical documentation

✅ Pre-submission Checklist

• ✅ I have searched existing issues to avoid duplicates
• ✅ This feature aligns with educational/personal-use goals
• ✅ I have considered the implementation complexity
• ✅ I understand this won't provide financial advice or guarantees
• ✅ I have provided clear examples and use cases

🏷️ Feature Classification

Priority:

• ☐ Critical (blocking important use cases)
• ✅ High (significant improvement to user experience)
• ☐ Medium (nice to have, moderate impact)
• ☐ Low (minor enhancement)

Justification: Transforms existing tools from "good" to "great" by eliminating repetitive ticker entry and enabling true personalization. Makes AI agents context-aware of user's actual holdings.

Effort Estimate:

• ☐ Small (1-3 days)
• ✅ Medium (1-2 weeks)
• ☐ Large (1+ months)
• ☐ Unknown

Breakdown:

• Phase 1 (Storage): 2-3 days
• Phase 2 (Integration): 1-2 days
• Testing & Documentation: 1-2 days
• Total: 4-7 days (depending on thoroughness)

Release Timeline:

• ✅ Next minor version (v0.6.0 or similar)
• ☐ Next major version
• ☐ Future consideration
• ☐ No preference

🌟 Additional Context

Related issues or discussions:

• Enhances existing portfolio tools without replacing them
• Builds on MaverickMCP's DDD architecture
• Follows established patterns in maverick_mcp/api/routers/portfolio.py
• Complements backtesting and screening features

Financial domain considerations:

• ✅ Educational disclaimers in all tools (required)
• ✅ No specific investment recommendations
• ✅ Local-first storage (privacy-respecting)
• ✅ Cost basis averaging follows FIFO/average cost principles
• ✅ P&L calculations for educational understanding only
• ⚠️ Not tax advice (users should consult tax professionals)

Community impact:

• Educational institutions: Example of portfolio management in code
• Individual learners: Hands-on portfolio tracking experience
• MCP developers: Reference implementation of stateful MCP tools
• Open source: Demonstrates AI context injection patterns
• Estimated users: All MaverickMCP users who manage multiple positions

Why this matters:

This feature represents the missing link between MaverickMCP's powerful analysis tools and real-world usage. Current tools are excellent but require users to repeatedly specify the same tickers. This creates friction that limits practical educational value.

By adding persistent portfolio storage with intelligent AI integration, MaverickMCP becomes a truly personalized AI financial assistant that:

• Remembers what you own
• Understands your positions automatically
• Personalizes every analysis to YOUR holdings
• Tracks your cost basis and performance
• Learns from your investment decisions over time

This transforms the user experience from "powerful but manual" to "intelligent and effortless."

Implementation Approach:

Following MaverickMCP's established patterns:

1. Domain entities (pure business logic)
2. SQLAlchemy models (data persistence)
3. Alembic migrations (schema evolution)
4. FastMCP tools (user interface)
5. MCP resources (AI context)
6. Comprehensive tests (reliability)

Privacy & Security:

• All data stored locally (SQLite/PostgreSQL)
• No external API calls for portfolio data
• User controls all data (add, view, remove, clear)
• No cloud sync or third-party sharing

📋 Implementation Checklist (for tracking)

Phase 1: Portfolio Storage

• ☐ Domain entities (Portfolio, Position)
• ☐ Database models (Portfolio, PortfolioPosition)
• ☐ Alembic migration
• ☐ MCP tools (add, get, remove, clear)
• ☐ MCP resource (portfolio://my-holdings)
• ☐ Unit tests (domain entities)
• ☐ Integration tests (database operations)
• ☐ Documentation (docs/PORTFOLIO.md)

Phase 2: AI Integration

• ☐ Enhance risk_adjusted_analysis with position awareness
• ☐ Enhance portfolio_correlation_analysis with auto-holdings
• ☐ Enhance compare_tickers with auto-holdings
• ☐ Enhance portfolio resource with live P&L
• ☐ Integration tests (cross-tool functionality)
• ☐ Update existing documentation
• ☐ Usage examples in docs

Phase 3: Polish

• ☐ Manual testing in Claude Desktop
• ☐ Performance optimization
• ☐ Error handling edge cases
• ☐ User experience refinements
• ☐ Final documentation review

---

Ready to implement! This feature has clear value, manageable scope, and follows established patterns. Will submit pull request after development complete.

Questions for Maintainers

1. Approval to proceed? Does this align with MaverickMCP's roadmap?
2. Architectural review? Any concerns with the proposed DDD structure?
3. Phase 2 integration? Should Phase 2 be in same PR or separate?
4. Naming conventions? Confirm mcp_portfolios and mcp_portfolio_positions table names?
5. User identification? Using "default" user_id for now, should this be configurable?

Thank you for considering this feature request! Happy to answer any questions or provide additional details.