open-stocks-mcp: Instructions file for Claude Code

CLAUDE.md

Project guidance for Claude Code when working with the Open Stocks MCP server.

Project Overview

Open Stocks MCP - Model Context Protocol server providing stock market data and trading tools through Robinhood and Charles Schwab broker APIs.

• Current Version: v0.6.5 with multi-broker support, enhanced authentication, and session management
• Framework: FastMCP for simplified MCP development
• APIs: Robin Stocks for Robinhood plus schwab-py for Charles Schwab
• Transport: HTTP with Server-Sent Events (SSE), configurable via --port (default 3000)
• Docker: Production-ready with persistent session/log storage

Quick Reference

Development Setup

uv sync   # installs project + all dev dependencies

Testing

Journey-Based Testing - 11 user journey categories for focused testing:

# All tests (skips exception tests by default)
pytest                           

# Fast journey testing (<30s each)
pytest -m "journey_account"      # Account management (16 tests, ~1.8s)
pytest -m "journey_portfolio"    # Portfolio & holdings (3 tests, ~1.7s)  
pytest -m "journey_market_data"  # Stock quotes & market info (19 tests, ~3.8s)
pytest -m "journey_research"     # Earnings, ratings, news (23 tests, ~3.0s)
pytest -m "journey_watchlists"   # Watchlist management (20 tests, ~16.7s)
pytest -m "journey_options"      # Options analysis (13 tests, ~9.7s)
pytest -m "journey_notifications" # Alerts & notifications (15 tests, ~1.6s)
pytest -m "journey_system"       # Health & monitoring (11 tests, ~1.9s)
pytest -m "journey_trading"      # Trading operations (1 test, ~1.6s)

# Combined journeys
pytest -m "journey_account or journey_portfolio"          # User account flows
pytest -m "journey_market_data or journey_research"       # Market intelligence
pytest -m "journey_options or journey_trading"            # Trading related

# Development workflows
pytest -m "not slow and not exception_test"               # Fast tests (recommended)
pytest -m "unit and journey_account"                      # Quick unit feedback
pytest tests/unit/                                        # Unit tests (fast)
pytest tests/integration/ -m integration                  # Integration (needs auth)
pytest -m rate_limited                                    # Live rate-limited API tests
RUN_RATE_LIMITED=1 pytest                                 # Include rate-limited tests in full run
OPEN_STOCKS_RUN_LIVE_MARKET=1 RUN_RATE_LIMITED=1 ENABLED_BROKERS=schwab uv run pytest tests/integration/test_schwab_live_journeys.py -m "live_market and auth_required and rate_limited" --run-live-market -q

# READ ONLY journeys (perfect for ADK evaluations)
pytest -m "journey_account or journey_portfolio or journey_market_data or journey_research or journey_notifications or journey_system"

# Failure-mode regression tests (network/auth failures, no live credentials needed)
uv run pytest tests/unit/test_error_handling.py tests/unit/test_auth_coordinator.py -k 'retry or timeout or connection or auth_failed' -q

# Performance/load benchmarks (mocked, CI-safe, no credentials needed)
uv run pytest -m performance tests/performance -v
RUN_PERFORMANCE=1 uv run pytest      # Include performance tests in a full run