schwab-mcp: Instructions file for Codex

Repository Guidelines

Project Structure

src/
  index.ts                    # CLI entry point (commander)
  server.ts                   # SchwabMCPServer class, MCP SDK integration
  client.ts                   # SchwabClient — authenticated fetch wrapper
  auth.ts                     # OAuth2 browser flow (local HTTPS callback)
  tokens.ts                   # Token load/save/refresh, credentials management
  resources.ts                # MCP resource definitions (order statuses)
  types.ts                    # TypeScript types from OpenAPI schemas
  tools/
    index.ts                  # registerTools() aggregator
    utils.ts                  # Shared helpers (date parsing, formatResult)
    market.ts                 # get_datetime, get_market_hours, get_movers, get_instruments
    accounts.ts               # Account and preferences tools (6 tools)
    quotes.ts                 # get_quotes
    history.ts                # Price history tools (8 tools, factory pattern)
    orders.ts                 # get_order, get_orders (multi-status merge)
    transactions.ts           # get_transactions, get_transaction
    technical.ts              # 12 TA indicators via technicalindicators
tests/
  setup.ts                    # makeMockClient() factory
  *.test.ts                   # Mirror source structure
  tools/*.test.ts             # Tool-specific tests
package.json
tsconfig.json
docs/
  openapi/                    # Schwab API OpenAPI 3.x specifications

Important: Read-Only Server

This is a read-only fork. All trading, order placement, order cancellation, options tools, approval workflows, and Discord integration have been removed. Every registered tool has readOnlyHint: true. Do not add write operations.

Build, Test, and Development Commands

# Install dependencies
bun install

# Run the CLI
bun run src/index.ts --help
bun run src/index.ts server --help

# Type checking
bun run typecheck    # or: tsc --noEmit

# Run full test suite
bun test

# Run a single test file
bun test tests/tools/market.test.ts

# Run tests matching a pattern
bun test --grep "get_order"

# Build standalone binary
bun build src/index.ts --compile --outfile schwab-mcp

# Combined check before commit
tsc --noEmit && bun test

# MCP Inspector
npx @modelcontextprotocol/inspector bun run src/index.ts server