feat(mcp): support discord approvals

- add Discord approval manager plumbing and CLI/server flags
- gate write-capable Schwab tools behind reviewer approval or override
- surface progress keepalives so long-running approvals don’t timeout
- document Discord bot setup steps and expand test coverage

Author: jkoelker

README.md

@@ -14,7 +14,7 @@ the MCP [python-sdk](https://github.com/modelcontextprotocol/python-sdk).
 - Access order and transaction history
 - Comprehensive order building and placement capabilities
 - Advanced order strategies (OCO, trigger-based, and bracket orders)
-- Modify account state with special tools (requires `--jesus-take-the-wheel` flag)
+- Modify account state with special tools gated behind Discord approvals (bypass with `--jesus-take-the-wheel`)
 - Designed to integrate with Large Language Models (LLMs)
 
 ## Installation
@@ -57,24 +57,61 @@ After authentication, you can run the server:
 
 ```bash
 # Run the server with default token path
-uv run schwab-mcp server --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL
+uv run schwab-mcp server \
+  --client-id YOUR_CLIENT_ID \
+  --client-secret YOUR_CLIENT_SECRET \
+  --callback-url YOUR_CALLBACK_URL \
+  --discord-token YOUR_DISCORD_BOT_TOKEN \
+  --discord-channel-id YOUR_APPROVAL_CHANNEL_ID \
+  --discord-approver DISCORD_USER_ID [--discord-approver ANOTHER_USER_ID ...]
 
 # Run with a custom token path
-uv run schwab-mcp server --token-path /path/to/token.json --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL
+uv run schwab-mcp server \
+  --token-path /path/to/token.json \
+  --client-id YOUR_CLIENT_ID \
+  --client-secret YOUR_CLIENT_SECRET \
+  --callback-url YOUR_CALLBACK_URL \
+  --discord-token YOUR_DISCORD_BOT_TOKEN \
+  --discord-channel-id YOUR_APPROVAL_CHANNEL_ID
+
+# Run with account modification tools auto-approved (no Discord prompt)
+uv run schwab-mcp server \
+  --jesus-take-the-wheel \
+  --client-id YOUR_CLIENT_ID \
+  --client-secret YOUR_CLIENT_SECRET \
+  --callback-url YOUR_CALLBACK_URL
 
-# Run with account modification tools enabled
-uv run schwab-mcp server --jesus-take-the-wheel --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --callback-url YOUR_CALLBACK_URL
 ```
 
 Token age is validated - if older than 5 days, you will be prompted to re-authenticate.
 
+Discord-related flags can also be provided via environment variables:
+- `SCHWAB_MCP_DISCORD_TOKEN`
+- `SCHWAB_MCP_DISCORD_CHANNEL_ID`
+- `SCHWAB_MCP_DISCORD_TIMEOUT` (optional, defaults to 600 seconds)
+- `SCHWAB_MCP_DISCORD_APPROVERS` (optional comma-separated list of Discord user IDs)
+
+### Discord approval setup
+
+1. Create or open your application at <https://discord.com/developers/applications>, add a **Bot**, reset the token, and paste it into `SCHWAB_MCP_DISCORD_TOKEN`.
+2. In the **Installation** tab (left sidebar) set *Install Link* to `None` so the default authorization link is disabled.
+3. Open the **Bot** tab, toggle **Public Bot** off.
+4. Use **OAuth2 → URL Generator** to build the invite link by selecting the `bot` scope. When the permissions matrix appears, grant the bot:
+   - View Channel
+   - Send Messages
+   - Embed Links
+   - Add Reactions
+   - Read Message History
+   - Manage Messages
+5. Copy the generated URL (the permissions integer reflects the boxes you checked), open it while logged into the Discord account that owns the approval server, and authorize the bot into the channel where approvals should post.
+
 > **WARNING**: Using the `--jesus-take-the-wheel` flag enables tools that can modify your account state. Use with caution as this allows LLMs to cancel orders and potentially perform other actions that change account state.
 
 ## Available Tools
 
 The server exposes the following MCP tools:
 
-> **Note**: Tools 28-35 require the `--jesus-take-the-wheel` flag as they can modify account state by placing orders.
+> **Note**: Tools 27-39 will pause for Discord approval before executing. Pass `--jesus-take-the-wheel` to bypass the approval workflow entirely.
 
 ### Date and Market Information
 1. `get_datetime` - Get the current datetime in ISO format

pyproject.toml

@@ -10,6 +10,7 @@ requires-python = ">=3.10"
 dependencies = [
     "anyio>=4.11.0",
     "click>=8.3.0",
+    "discord.py>=2.4.0",
     "httpx>=0.27.2",
     "mcp>=1.17.0",
     "platformdirs>=4.5.0",

src/schwab_mcp/approvals/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from schwab_mcp.approvals.base import (
+    ApprovalDecision,
+    ApprovalManager,
+    ApprovalRequest,
+    NoOpApprovalManager,
+)
+from schwab_mcp.approvals.discord import (
+    DiscordApprovalManager,
+    DiscordApprovalSettings,
+)
+
+__all__ = [
+    "ApprovalDecision",
+    "ApprovalManager",
+    "ApprovalRequest",
+    "NoOpApprovalManager",
+    "DiscordApprovalManager",
+    "DiscordApprovalSettings",
+]

src/schwab_mcp/approvals/base.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass
+from enum import Enum
+from typing import Mapping
+
+
+class ApprovalDecision(str, Enum):
+    """Decision returned by an approval workflow."""
+
+    APPROVED = "approved"
+    DENIED = "denied"
+    EXPIRED = "expired"
+
+
+@dataclass(slots=True, frozen=True)
+class ApprovalRequest:
+    """Details about a write tool invocation requiring approval."""
+
+    id: str
+    tool_name: str
+    request_id: str
+    client_id: str | None
+    arguments: Mapping[str, str]
+
+
+class ApprovalManager(abc.ABC):
+    """Interface for asynchronous approval backends."""
+
+    async def start(self) -> None:
+        """Perform any startup/connection work."""
+
+    async def stop(self) -> None:
+        """Clean up resources."""
+
+    @abc.abstractmethod
+    async def require(self, request: ApprovalRequest) -> ApprovalDecision:
+        """Require approval for the provided request."""
+
+
+class NoOpApprovalManager(ApprovalManager):
+    """Approval manager that always approves requests."""
+
+    async def require(self, request: ApprovalRequest) -> ApprovalDecision:  # noqa: ARG002
+        return ApprovalDecision.APPROVED
+
+
+__all__ = [
+    "ApprovalDecision",
+    "ApprovalManager",
+    "ApprovalRequest",
+    "NoOpApprovalManager",
+]