schwab_mcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9da3afacad3bb1272bbff0e797dcaf882352d1263ab620446dd0c97d329debc
-  data.tar.gz: 6ea0e964b8ab66f7d92fc88b766b5c4d3569d18ed2b016ae35053e0d0a11b159
+  metadata.gz: 7680eeeed2f4a22cf70f836af9ab019c60e6de76867408acf79d0ffdd3217b33
+  data.tar.gz: e236d0f991b031b84873fbc8244b623dd74603ac3ab043d3586a987a8656eb37
 SHA512:
-  metadata.gz: 5000ea77ea70965802bf6b8bac785f01edb98b66568f3197678b5294aaa98a2f7e8e79912ca820307b06f40990ddfe6a24c2f51b24afbab947ee07c6ab909560
-  data.tar.gz: 5515f8088908d5a8a5a5f6e104ab4e29d6024acf275791b854eb00cbf7029868a5ce59d3b55e6b7aec66835baf1d3112a4ccf5aafb13bfdcc08482887690c74c
+  metadata.gz: 678fb6af3f9de96315e9798fa5f8aebd4dde3bcc102859b7c3e761aefb2b7d3ec591b56267978936114099a68f746a3c43b0a72abf4bd711c83822758053f63f
+  data.tar.gz: ae505ca27dbf4f8579279a05845befed68fc6c1690cdd9d469b585239827e931e3726381795d60fb8c086d2de70fdfc0966fc24ea4b9f380c3f4311846a4ec58

data/.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bundle exec rspec:*)",
+      "Bash(bundle exec rubocop:*)",
+      "Bash(git checkout:*)"
+    ],
+    "deny": [],
+    "additionalDirectories": [
+      "/Users/jplatta/repos/schwab_rb",
+      "/Users/jplatta/repos/options_trader"
+    ]
+  }
+}

data/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common Development Commands
+
+### Testing
+- Run all tests: `bundle exec rspec`
+- Run specific test: `bundle exec rspec spec/tools/specific_tool_spec.rb`
+- NEVER use `-v` flag with RSpec - it clutters output unnecessarily
+- Reference @.github/instructions/ruby-testing.instructions.md when writing unit tests
+
+### Code Quality
+- Run RuboCop linter: `bundle exec rubocop`
+- Default rake task (tests + linting): `rake`
+
+### Server Operations
+- Start MCP server: `bundle exec exe/schwab_mcp`
+- Alternative server start: `./start_mcp_server.sh`
+- Token refresh: `bundle exec exe/schwab_token_refresh`
+- Token reset: `bundle exec exe/schwab_token_reset`
+
+### Development Setup
+- Initial setup: `bin/setup`
+- Install dependencies: `bundle install`
+- Interactive console: `bin/console`
+
+## Architecture Overview
+
+### Core Structure
+This is a Ruby gem providing a Model Context Protocol (MCP) server for Schwab brokerage API integration. The architecture follows these key patterns:
+
+- **MCP Tools Pattern**: All functionality is exposed through MCP tools extending `MCP::Tool`
+- **Data Objects Migration**: Currently migrating from JSON parsing to schwab_rb data objects (see `doc/DATA_OBJECTS_MIGRATION_TODO.md`)
+- **Shared Logging**: Uses singleton logger pattern with `Loggable` module across all components
+
+### Key Components
+- `lib/schwab_mcp.rb` - Main server class and tool registration
+- `lib/schwab_mcp/tools/` - All MCP tools (17 tools total)
+- `lib/schwab_mcp/orders/` - Order construction utilities (Iron Condor, Vertical spreads)
+- `lib/schwab_mcp/loggable.rb` - Shared logging functionality
+- `lib/schwab_mcp/redactor.rb` - Sensitive data redaction for logs
+
+### Tool Categories
+- **Account Tools**: `schwab_account_details_tool`, `list_schwab_accounts_tool`
+- **Order Tools**: `list_account_orders_tool`, `get_order_tool`, `cancel_order_tool`, `preview_order_tool`, `place_order_tool`, `replace_order_tool`
+- **Market Data Tools**: `quote_tool`, `quotes_tool`, `option_chain_tool`, `list_movers_tool`, `get_market_hours_tool`, `get_price_history_tool`
+- **Transaction Tools**: `list_account_transactions_tool`
+- **Utility Tools**: `help_tool`
+
+## Data Objects Migration
+
+**CRITICAL**: This codebase is currently migrating from manual JSON parsing to schwab_rb data objects. Progress is tracked in `doc/DATA_OBJECTS_MIGRATION_TODO.md` (6/17 tools completed as of July 2025).
+
+### Migration Pattern
+When working on tools, follow this pattern:
+1. Replace `JSON.parse(response.body)` with direct data object usage
+2. Change hash access `data['key']` to object methods `object.key`
+3. Remove `JSON::ParserError` rescue blocks
+4. Update formatting to use data object attributes
+5. Write comprehensive RSpec tests with proper mocking
+
+### Completed Migrations
+Tools using data objects (safe to follow as examples):
+- `schwab_account_details_tool.rb` - Uses `Account` and `AccountNumbers`
+- `list_schwab_accounts_tool.rb` - Uses `AccountNumbers`
+- `list_account_orders_tool.rb` - Uses `Order` and `AccountNumbers`
+- `get_order_tool.rb` - Uses `Order`
+- `cancel_order_tool.rb` - Uses `Order`
+- `preview_order_tool.rb` - Uses `OrderPreview`
+
+## Development Conventions
+
+### Ruby Style
+- Use `frozen_string_literal: true` in all files
+- Follow snake_case/PascalCase conventions
+- Use `require_relative` for local dependencies
+- Prefer keyword arguments for multi-parameter methods
+- Always use descriptive variable names
+
+### Tool Development
+- All tools extend `MCP::Tool` and include `Loggable`
+- Use proper JSON Schema validation in `input_schema`
+- Return `MCP::Tool::Response` objects with structured content
+- Include descriptive annotations (title, read_only_hint, etc.)
+
+### Testing Strategy
+- Mock environment variables globally in `spec/spec_helper.rb`
+- Test both success and error scenarios
+- Mock schwab_rb client and data objects appropriately
+- File naming: `*_spec.rb` for corresponding `*.rb`
+
+### Environment Variables
+Required for operation:
+- `SCHWAB_API_KEY`, `SCHWAB_APP_SECRET`, `SCHWAB_CALLBACK_URI`, `TOKEN_PATH`
+- Account mappings: `*_ACCOUNT` (e.g., `TRADING_BROKERAGE_ACCOUNT`)
+- Optional: `LOG_LEVEL`, `LOGFILE`
+
+### Git Workflow
+- Stage specific files, never use `git add .`
+- Write descriptive commits with progress tracking
+- Include 1-3 bullet points for detailed changes
+- Commit only relevant files, exclude temporary/log files
+
+## Dependencies
+
+### Core Dependencies
+- `schwab_rb` - Schwab API client with data objects (prefer `return_data_objects: true`)
+- `mcp` - Model Context Protocol framework
+- `rspec` - Testing framework
+- `rubocop` - Code style enforcement
+
+### External Integrations
+- Schwab Trading API for all brokerage operations
+- OAuth token management for authentication
+- MCP protocol for AI assistant integration
+
+## Important Notes
+
+- **Security**: Never commit real credentials or account numbers
+- **Logging**: Use `Redactor` class for sensitive data in debug output
+- **Data Objects**: Always prefer schwab_rb data objects over JSON parsing
+- **Testing**: All tests must pass before committing changes
+- **Tool Design**: Tools should be read-only unless explicitly destructive

data/debug_env.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+# Test script to debug environment variables and client initialization
+
+puts "=== Environment Variables ==="
+puts "SCHWAB_API_KEY: #{ENV['SCHWAB_API_KEY'] ? '[SET]' : '[NOT SET]'}"
+puts "SCHWAB_APP_SECRET: #{ENV['SCHWAB_APP_SECRET'] ? '[SET]' : '[NOT SET]'}"
+puts "APP_CALLBACK_URL: #{ENV['APP_CALLBACK_URL'] ? '[SET]' : '[NOT SET]'}"
+puts "TOKEN_PATH: #{ENV['TOKEN_PATH'] ? '[SET]' : '[NOT SET]'}"
+
+puts "\n=== Testing Token File ==="
+token_path = ENV['TOKEN_PATH'] || './token.json'
+puts "Checking token file at: #{token_path}"
+puts "Token file exists: #{File.exist?(token_path)}"
+
+if File.exist?(token_path)
+  begin
+    content = File.read(token_path)
+    require 'json'
+    data = JSON.parse(content)
+    puts "Token file valid JSON: true"
+    puts "Token has access_token: #{data.dig('token', 'access_token') ? '[YES]' : '[NO]'}"
+    puts "Token has refresh_token: #{data.dig('token', 'refresh_token') ? '[YES]' : '[NO]'}"
+  rescue => e
+    puts "Token file JSON error: #{e.message}"
+  end
+end
+
+puts "\n=== Testing Client Initialization ==="
+begin
+  require 'schwab_rb'
+  require_relative 'lib/schwab_mcp/schwab_client_factory'
+
+  client = SchwabMCP::SchwabClientFactory.create_client
+
+  if client
+    puts "Client initialized: SUCCESS"
+    puts "Client class: #{client.class}"
+  else
+    puts "Client initialized: FAILED (nil returned)"
+  end
+rescue => e
+  puts "Client initialization error: #{e.message}"
+  puts "Backtrace:"
+  puts e.backtrace.first(5).join("\n")
+end

data/doc/DATA_OBJECTS_MIGRATION_TODO.md

@@ -0,0 +1,80 @@
+# SchwabMCP Data Objects Migration TODO
+
+## Overview
+Update all tools in `lib/schwab_mcp/tools/` to use data objects from schwab_rb instead of parsing JSON responses directly.
+
+## Migration Date
+July 21, 2025
+
+**Progress: 17/17 tools completed**
+
+## Tools to Update
+
+### ✅ Account-related Tools
+- [x] **schwab_account_details_tool.rb** - ✅ COMPLETED - Updated to use Account and AccountNumbers data objects
+- [x] **list_schwab_accounts_tool.rb** - ✅ COMPLETED - Updated to use AccountNumbers data object
+
+### ✅ Order-related Tools
+- [x] **list_account_orders_tool.rb** - ✅ COMPLETED - Updated to use Order and AccountNumbers data objects
+- [x] **get_order_tool.rb** - ✅ COMPLETED - Updated to use Order data object
+- [x] **cancel_order_tool.rb** - ✅ COMPLETED - Updated to use Order data object
+- [x] **preview_order_tool.rb** - ✅ COMPLETED - Updated to use OrderPreview data object
+- [x] **place_order_tool.rb** - ✅ COMPLETED - Updated to use AccountNumbers data object for account resolution
+- [x] **replace_order_tool.rb** - ✅ COMPLETED - Updated to use AccountNumbers data object for account resolution
+
+### ✅ Market Data Tools
+- [x] **quote_tool.rb** - ✅ COMPLETED - Updated to use EquityQuote, OptionQuote, and IndexQuote data objects
+- [x] **quotes_tool.rb** - ✅ COMPLETED - Updated to use EquityQuote, OptionQuote, and IndexQuote data objects
+- [x] **option_chain_tool.rb** - Update to use OptionChain data object
+- [x] **list_movers_tool.rb** - ✅ COMPLETED - Updated to use MarketMovers data object
+- [x] **get_market_hours_tool.rb** - Update to use MarketHours data object
+- [x] **get_price_history_tool.rb** - Update to use PriceHistory data object
+
+### ✅ Transaction Tools
+- [x] **list_account_transactions_tool.rb** - Update to use Transaction data objects
+
+### ✅ Strategy Tools
+- [x] **option_strategy_finder_tool.rb** - ✅ COMPLETED - Updated to use OptionChain data object with refactored OptionChainFilter
+
+### ✅ Utility Tools
+- [x] **help_tool.rb** - No changes needed (utility tool)
+
+## Total Tools Found: 17
+
+## Migration Steps for Each Tool
+
+1. **Remove JSON parsing logic** - Delete manual hash key access
+2. **Use data object attributes** - Access data via object methods/attributes
+3. **Update error handling** - Ensure proper handling of data object responses
+4. **Write minimal unit tests** - Verify tool works with data objects
+5. **Test functionality** - Manual testing if needed
+6. **Clean commit** - Make focused commit for each tool
+
+## Data Object Mappings
+
+Based on the schwab_rb data objects available:
+
+- **Account data** → `SchwabRb::DataObjects::Account`
+- **Account numbers** → `SchwabRb::DataObjects::AccountNumbers`
+- **Orders** → `SchwabRb::DataObjects::Order`
+- **Order preview** → `SchwabRb::DataObjects::OrderPreview`
+- **Quotes** → `SchwabRb::DataObjects::Quote`
+- **Option chains** → `SchwabRb::DataObjects::OptionChain`
+- **Transactions** → `SchwabRb::DataObjects::Transaction`
+- **Positions** → `SchwabRb::DataObjects::Position`
+- **Market hours** → `SchwabRb::DataObjects::MarketHours` (if available)
+- **Price history** → `SchwabRb::DataObjects::PriceHistory` (if available)
+
+## Notes
+
+- All schwab_rb client methods now default to `return_data_objects: true`
+- Maintain backward compatibility where possible
+- Focus on cleaner, more maintainable code
+- Each tool update should be a separate, focused commit
+- Write minimal unit tests for each tool to prevent regressions
+
+## Progress Tracking
+
+- **Total tools to update**: 16 (excluding help_tool.rb)
+- **Tools completed**: 17
+- **Tools remaining**: 0

data/doc/SCHWAB_CLIENT_FACTORY_REFACTOR_PLAN.md

@@ -0,0 +1,187 @@
+# Schwab Client Factory Refactor Plan
+
+## Problem Statement
+
+Every tool in the schwab_mcp codebase has identical client initialization code repeated 17 times across the project:
+
+```ruby
+client = SchwabRb::Auth.init_client_easy(
+  ENV['SCHWAB_API_KEY'],
+  ENV['SCHWAB_APP_SECRET'], 
+  ENV['SCHWAB_CALLBACK_URI'],
+  ENV['TOKEN_PATH']
+)
+
+unless client
+  log_error("Failed to initialize Schwab client")
+  return MCP::Tool::Response.new([{
+    type: "text",
+    text: "**Error**: Failed to initialize Schwab client. Check your credentials."
+  }])
+end
+```
+
+**Files affected (18 total):**
+- All 17 tools in `lib/schwab_mcp/tools/`
+- `exe/schwab_token_refresh`
+- `debug_env.rb`
+
+This creates ~170 lines of duplicated code and makes maintenance difficult.
+
+## Proposed Solution: SchwabClientFactory Module
+
+### Design Goals
+1. **Centralize client creation** - Single location for all client initialization logic
+2. **Handle error scenarios** - Consistent error handling and logging across tools
+3. **Support caching** - Optional client caching to avoid repeated auth calls
+4. **Integrate with existing patterns** - Uses existing `Loggable` module
+5. **Maintain compatibility** - Drop-in replacement requiring minimal tool changes
+
+### Implementation
+
+#### Step 1: Create SchwabClientFactory Module
+
+**File**: `lib/schwab_mcp/schwab_client_factory.rb`
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "loggable"
+
+module SchwabMCP
+  module SchwabClientFactory
+    extend Loggable
+
+    # Creates a new Schwab client with standard error handling
+    def self.create_client
+      begin
+        log_debug("Initializing Schwab client")
+        client = SchwabRb::Auth.init_client_easy(
+          ENV['SCHWAB_API_KEY'],
+          ENV['SCHWAB_APP_SECRET'],
+          ENV['SCHWAB_CALLBACK_URI'],
+          ENV['TOKEN_PATH']
+        )
+
+        unless client
+          log_error("Failed to initialize Schwab client - check credentials")
+          return nil
+        end
+
+        log_debug("Schwab client initialized successfully")
+        client
+      rescue => e
+        log_error("Error initializing Schwab client: #{e.message}")
+        log_debug("Backtrace: #{e.backtrace.first(3).join('\n')}")
+        nil
+      end
+    end
+
+    # Optional: Cached client for performance (use with caution for token expiry)
+    def self.cached_client
+      @client ||= create_client
+    end
+
+    # Helper method for consistent error responses
+    def self.client_error_response
+      MCP::Tool::Response.new([{
+        type: "text",
+        text: "**Error**: Failed to initialize Schwab client. Check your credentials."
+      }])
+    end
+  end
+end
+```
+
+#### Step 2: Update Main Module
+
+Add to `lib/schwab_mcp.rb`:
+```ruby
+require_relative "schwab_mcp/schwab_client_factory"
+```
+
+#### Step 3: Refactor Tool Pattern
+
+**Before (10+ lines per tool):**
+```ruby
+begin
+  client = SchwabRb::Auth.init_client_easy(
+    ENV['SCHWAB_API_KEY'],
+    ENV['SCHWAB_APP_SECRET'],
+    ENV['SCHWAB_CALLBACK_URI'],
+    ENV['TOKEN_PATH']
+  )
+
+  unless client
+    log_error("Failed to initialize Schwab client")
+    return MCP::Tool::Response.new([{
+      type: "text",
+      text: "**Error**: Failed to initialize Schwab client. Check your credentials."
+    }])
+  end
+
+  # tool logic here...
+end
+```
+
+**After (3 lines per tool):**
+```ruby
+client = SchwabClientFactory.create_client
+return SchwabClientFactory.client_error_response unless client
+
+# tool logic here...
+```
+
+#### Step 4: Update Tool Imports
+
+Add to each tool file:
+```ruby
+require_relative "../schwab_client_factory"
+```
+
+### Migration Strategy
+
+1. **Create the factory module** first
+2. **Update one tool** as a proof of concept 
+3. **Test thoroughly** to ensure no regression
+4. **Batch update remaining tools** (can be done efficiently with MultiEdit)
+5. **Update executable files** (`exe/schwab_token_refresh`, `debug_env.rb`)
+6. **Remove old client initialization code**
+
+### Benefits
+
+1. **Code Reduction**: ~170 lines of duplicated code → 1 centralized module
+2. **Consistent Error Handling**: All tools handle auth failures identically
+3. **Easier Maintenance**: Auth logic changes in one place
+4. **Better Testing**: Mock client creation in one place
+5. **Performance Options**: Can add client caching if needed
+6. **Future Extensibility**: Easy to add retry logic, connection pooling, etc.
+
+### Risks and Considerations
+
+1. **Token Caching**: Cached clients may hold expired tokens - use with caution
+2. **Environment Variables**: Factory assumes same env vars for all tools (currently true)
+3. **Error Handling**: Must ensure all tools properly check for nil client response
+4. **Testing**: All tool tests will need to mock `SchwabClientFactory.create_client`
+
+### Testing Strategy
+
+1. **Unit tests** for SchwabClientFactory module
+2. **Integration tests** to ensure tools still work correctly
+3. **Mock the factory** in existing tool tests rather than individual client creation
+4. **Verify error scenarios** are handled consistently
+
+### Files to Modify
+
+**New files:**
+- `lib/schwab_mcp/schwab_client_factory.rb`
+
+**Modified files:**
+- `lib/schwab_mcp.rb` (add require)
+- All 17 tool files in `lib/schwab_mcp/tools/`
+- `exe/schwab_token_refresh`
+- `debug_env.rb`
+
+**Total impact:** 20 files modified, ~150 lines of code removed, 1 new module added
+
+This refactor will significantly improve code maintainability while preserving all existing functionality.

data/exe/schwab_mcp

@@ -1,7 +1,9 @@
 #!/usr/bin/env ruby
 
-require "schwab_mcp"
-require "dotenv/load"
+require_relative "../lib/schwab_mcp"
+require "dotenv"
+
+Dotenv.load
 
 required_vars = [
   'SCHWAB_API_KEY',
@@ -12,8 +14,17 @@ required_vars = [
 missing_vars = required_vars.select { |var| ENV[var].nil? || ENV[var].empty? }
 
 unless missing_vars.empty?
+  STDERR.puts "[SCRIPT] Missing required environment variables: #{missing_vars.join(', ')}"
   exit 1
 end
 
+STDERR.puts "[SCRIPT] All required environment variables are set."
 
-SchwabMCP::Server.new.start
+begin
+  STDERR.puts "[SCRIPT] Starting Schwab MCP server..."
+  SchwabMCP::Server.new.start
+rescue StandardError => e
+  STDERR.puts "[SCRIPT] Error starting Schwab MCP server: #{e.message}"
+  STDERR.puts e.backtrace.join("\n")
+  exit 1
+end

data/exe/schwab_token_refresh

@@ -5,6 +5,7 @@
 require 'pry'
 require 'dotenv'
 require 'schwab_rb'
+require_relative '../lib/schwab_mcp/schwab_client_factory'
 
 Dotenv.load
 
@@ -17,7 +18,7 @@ required_vars = [
 missing_vars = required_vars.select { |var| ENV[var].nil? || ENV[var].empty? }
 
 unless missing_vars.empty?
-  puts "❌ Missing required environment variables: #{missing_vars.join(', ')}"
+  puts "Missing required environment variables: #{missing_vars.join(', ')}"
   exit 1
 end
 
@@ -25,14 +26,14 @@ token_path = ENV['TOKEN_PATH']
 puts "Token path: #{token_path}"
 
 begin
-  SchwabRb::Auth.init_client_easy(
-    ENV['SCHWAB_API_KEY'],
-    ENV['SCHWAB_APP_SECRET'],
-    ENV['SCHWAB_CALLBACK_URI'],
-    token_path
-  )
-  puts "✅ Token refresh completed successfully"
+  client = SchwabMCP::SchwabClientFactory.create_client
+  if client
+    puts "Token refresh completed successfully"
+  else
+    puts "Token refresh failed: Unable to create client"
+    exit 1
+  end
 rescue => e
-  puts "❌ Token refresh failed: #{e.message}"
+  puts "Token refresh failed: #{e.message}"
   exit 1
 end

data/lib/schwab_mcp/redactor.rb

@@ -89,6 +89,10 @@ module SchwabMCP
         redacted.gsub!(/account[_\s]*number[_\s]*[:\=]\s*\d{8,9}/i, "account_number: #{REDACTED_ACCOUNT_PLACEHOLDER}")
         redacted.gsub!(/account[_\s]*id[_\s]*[:\=]\s*\d{8,9}/i, "account_id: #{REDACTED_ACCOUNT_PLACEHOLDER}")
 
+        # Redact long hashes (40+ hex chars) in URLs/logs (e.g., Schwab account hashes)
+        # Example: /accounts/4996EA061B4878E8D0B9063DF74925E5688F475BE00AF6A0A41E1FC4A2510CA0/
+        redacted.gsub!(/\b[0-9a-fA-F]{40,}\b/, REDACTED_HASH_PLACEHOLDER)
+
         redacted
       end
 

data/lib/schwab_mcp/schwab_client_factory.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "loggable"
+
+module SchwabMCP
+  module SchwabClientFactory
+    extend Loggable
+
+    def self.create_client
+      begin
+        log_debug("Initializing Schwab client")
+        client = SchwabRb::Auth.init_client_easy(
+          ENV['SCHWAB_API_KEY'],
+          ENV['SCHWAB_APP_SECRET'],
+          ENV['SCHWAB_CALLBACK_URI'],
+          ENV['TOKEN_PATH']
+        )
+
+        unless client
+          log_error("Failed to initialize Schwab client - check credentials")
+          return nil
+        end
+
+        log_debug("Schwab client initialized successfully")
+        client
+      rescue => e
+        log_error("Error initializing Schwab client: #{e.message}")
+        log_debug("Backtrace: #{e.backtrace.first(3).join('\n')}")
+        nil
+      end
+    end
+
+    def self.cached_client
+      @client ||= create_client
+    end
+
+    def self.client_error_response
+      MCP::Tool::Response.new([{
+        type: "text",
+        text: "**Error**: Failed to initialize Schwab client. Check your credentials."
+      }])
+    end
+  end
+end