finance-agent/
├── src/
│   ├── agent/
│   │   ├── finance_advisor.py      # Core financial analysis
│   │   ├── portfolio_manager.py    # Portfolio optimization
│   │   ├── expense_tracker.py      # Expense categorization
│   │   ├── tax_optimizer.py        # Tax strategy engine
│   │   └── mcp_server.py           # MCP server implementation
│   ├── api/
│   │   ├── main.py                 # FastAPI application
│   │   └── routes/                 # API endpoints
│   ├── models/
│   │   ├── database.py             # SQLAlchemy models
│   │   └── schemas.py              # Pydantic schemas
│   ├── services/
│   │   ├── market_data.py          # Real-time market data
│   │   ├── plaid_service.py        # Banking integration
│   │   └── notification.py         # Alert system
│   └── utils/
│       ├── calculations.py         # Financial calculations
│       └── indicators.py           # Technical indicators
├── mcp/
│   ├── tools/                      # MCP tool definitions
│   └── prompts/                    # MCP prompt templates
├── alembic/                        # Database migrations
├── tests/
├── requirements.txt
└── docker-compose.yml

cd finance-agent

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Setup database
createdb finance_agent
alembic upgrade head

# Pull Ollama model
ollama pull llama3.2

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start services
docker-compose up -d  # PostgreSQL, Redis

# Run API server
uvicorn src.api.main:app --reload

# Run MCP server (separate terminal)
python src/agent/mcp_server.py

POST /api/v1/expenses
{
  "amount": 45.50,
  "description": "Grocery shopping",
  "date": "2024-01-15",
  "category": "auto"  # AI auto-categorizes
}

GET /api/v1/budget/analysis?month=2024-01

POST /api/v1/portfolio/positions
{
  "symbol": "AAPL",
  "quantity": 10,
  "purchase_price": 175.50,
  "purchase_date": "2024-01-10"
}

GET /api/v1/portfolio/performance

POST /api/v1/ask
{
  "question": "Should I rebalance my portfolio?",
  "context": "current_holdings"
}

from finance_agent import FinanceAgent

# Initialize agent
agent = FinanceAgent(api_key="your_key")

# Track expense with auto-categorization
expense = agent.track_expense(
    amount=125.00,
    description="Dinner at Italian restaurant"
)
print(f"Categorized as: {expense.category}")

# Analyze portfolio
analysis = agent.analyze_portfolio()
print(f"Total Value: ${analysis.total_value:,.2f}")
print(f"Return: {analysis.total_return_pct:.2f}%")
print(f"Risk Score: {analysis.risk_score}/10")

# Get AI recommendations
recommendations = agent.get_recommendations(
    risk_tolerance="moderate",
    investment_horizon="long-term"
)

for rec in recommendations:
    print(f"{rec.action}: {rec.symbol} - {rec.reason}")

# Tax optimization
tax_strategies = agent.optimize_taxes(tax_year=2024)
print(f"Potential Tax Savings: ${tax_strategies.estimated_savings:,.2f}")

# MCP tools available:
# - get_portfolio_value: Get current portfolio value
# - analyze_stock: Analyze individual stock
# - calculate_risk: Calculate portfolio risk metrics
# - suggest_rebalance: Get rebalancing suggestions
# - find_tax_opportunities: Find tax-loss harvesting opportunities

# Example MCP conversation
from mcp import MCPClient

client = MCPClient("http://localhost:5000")

response = client.send_message(
    "I have $10,000 to invest. I'm 30 years old and want moderate risk. What should I do?"
)

# Agent uses MCP tools to:
# 1. Assess risk tolerance
# 2. Analyze current portfolio
# 3. Research suitable investments
# 4. Generate allocation strategy
# 5. Provide actionable recommendations

# Database
DATABASE_URL=postgresql://user:pass@localhost/finance_agent

# Redis
REDIS_URL=redis://localhost:6379/0

# Ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2

# Plaid (optional)
PLAID_CLIENT_ID=your_client_id
PLAID_SECRET=your_secret
PLAID_ENV=sandbox

# Market Data
ALPHA_VANTAGE_KEY=your_key  # optional

# MCP Server
MCP_HOST=0.0.0.0
MCP_PORT=5000

# Security
JWT_SECRET=your_secret_key
ENCRYPTION_KEY=your_encryption_key

# Run all tests
pytest tests/

# Test with coverage
pytest --cov=src tests/

# Test specific module
pytest tests/test_portfolio_manager.py

# Docker Compose (recommended)
docker-compose -f docker-compose.prod.yml up -d

# Kubernetes
kubectl apply -f k8s/

# Environment variables
kubectl create secret generic finance-agent-secrets \
  --from-env-file=.env.prod