jesse-mcp: Instructions file for Codex

Jesse MCP Development Guidelines

MCP server exposing Jesse's algorithmic trading framework to LLM agents. 46 tools across 6 phases.

External References

• jessegpt.md - Strategy writing, indicators, Jesse workflow
• docs/jesse-rest-api.md - Full REST API payload structures

Build/Lint/Test

pip install -e .                # Install editable
pytest                           # Run tests
pytest -v -s tests/test_x.py     # Verbose with print
flake8 jesse_mcp/ && black jesse_mcp/ && mypy jesse_mcp/  # Lint/format/typecheck
python -m jesse_mcp              # Run server (stdio)
python -m jesse_mcp --transport http --port 8000  # Run server (HTTP)

Code Style

• Formatting: black (88 chars), double quotes
• Imports: stdlib → third-party → local (blank lines between)
• Types: Use typing module (Dict[str, Any], Optional[T], etc.)
• Naming: PascalCase classes, snake_case functions, UPPER_SNAKE_CASE constants
• Errors: Return {"error": str(e), "error_type": type(e).__name__} from tools
• Logging: logger = logging.getLogger("jesse-mcp.phase3"), emoji prefixes (✅❌⚠️)

Jesse REST API Gotchas

These are the common mistakes that cause silent failures:

1. warm_up_candles in config - NOT at root level
2. exchanges requires balance - Missing balance causes errors
3. ID must be valid UUID - Use str(uuid.uuid4())
4. Symbol format: BTC-USDT with hyphen
5. Date format: YYYY-MM-DD string
6. Strategy name: Case-sensitive, must match class exactly

See docs/jesse-rest-api.md for full payload structures.

Architecture Patterns

Lazy Initialization (allows testing without Jesse)

jesse = None
_initialized = False

def _initialize_dependencies():
    global jesse, _initialized
    if _initialized: return
    # ... init logic
    _initialized = True

Singleton with Getter

_optimizer_instance = None

def get_optimizer(use_mock=None) -> Phase3Optimizer:
    global _optimizer_instance
    if _optimizer_instance is None:
        _optimizer_instance = Phase3Optimizer(use_mock=use_mock)
    return _optimizer_instance