robinhood-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents (Claude Code, Cursor, Codex, etc.) when working with this repository. It is the single source of truth; CLAUDE.md imports it via @AGENTS.md.

Project Overview

robinhood-mcp is a read-only MCP (Model Context Protocol) server that wraps the robin_stocks Python library to expose Robinhood portfolio data as research tools for AI assistants. It is strictly a research/educational tool — no trading functionality is exposed.

Core purpose:

• Translate MCP tool calls into robin_stocks Robinhood API requests over stdio
• Provide read-only portfolio, quote, fundamentals, news, and order-history research
• Support multi-account Robinhood logins (taxable, IRA, etc.) via optional account selection

Read-only is a hard invariant

The server never exposes order placement, cancellation, or any account-modifying call. There are no order_buy_*, order_sell_*, or cancel_* tools, and none should ever be added. Every tool delegates to read-only robin_stocks endpoints (rh.profiles.*, rh.stocks.*, rh.account.* getters, rh.orders.get_all_stock_orders, rh.options.get_open_option_positions). When adding a tool, preserve this invariant; the order-history tool explicitly documents "Read-only — this never places or cancels orders" (tools.py:639).

Build & Development

# Install with dev dependencies (editable)
pip install -e ".[dev]"

# Lint and format-check (ruff; line-length 100, target py311)
ruff check .
ruff format --check .

# Run tests
pytest -v

# Run tests with coverage
pytest --cov=src --cov-report=html

# Smoke test (import + server instantiation + entry point)
./scripts/smoke.sh

# Run the MCP server (stdio mode)
robinhood-mcp

robinhood-mcp is the console-script entry point, wired to robinhood_mcp.server:main (pyproject.toml:36-37). Python >= 3.11 is required (pyproject.toml:11). Runtime dependencies: fastmcp, robin_stocks, python-dotenv, pyotp (pyproject.toml:21-26).