# cTrader MCP Server

This project builds an MCP server for cTrader using the Alpaca reference architecture, adapted to the cTrader API and the bundled OpenApiPy library.

## Features

- **16 cTrader tools** across account, market, positions, and trading categories
- **OpenAPI-first generation** using FastMCP from spec-driven sources
- **Custom overrides** for complex operations (create_order, amend_order, close_position)
- **Trust boundary security** with parameter validation and account isolation
- **Backdoor authentication** (no OAuth) using pre-provisioned credentials
- **Azure Key Vault integration** for credential management
- **Comprehensive documentation** generation from tool registry

## Project Structure

```
ctrader-mcp-server/
├── src/ctrader_mcp_server/
│   ├── config.py              # Runtime config & Azure Key Vault loading
│   ├── ctrader_session.py     # Backdoor session bootstrap (ProtoOA auth)
│   ├── server.py              # FastMCP server construction with overrides
│   ├── tool_registry.py       # 16 tool definitions with metadata
│   ├── toolsets.py            # Tool organization by category
│   ├── overrides.py           # Custom handlers for complex operations
│   ├── security.py            # Trust boundary & parameter validation
│   ├── readme_docs.py         # Documentation generation
│   └── specs/
│       └── ctrader-api.json   # OpenAPI spec (all 16 endpoints)
├── tests/
│   ├── test_config.py         # Config & Key Vault loading
│   ├── test_ctrader_session.py  # Session bootstrap
│   ├── test_overrides.py      # Override validation logic
│   ├── test_security.py       # Security & trust boundary
│   ├── test_readme_docs.py    # Documentation generation
│   └── test_server_construction.py # Server build & tools
└── OpenApiPy/                 # cTrader client library (submodule)
```

## Available Tools

The server exposes 16 tools organized into 4 categories:

### Account (3 tools)
- `get_account_status` - Current account status and session
- `get_trader` - Trader profile and account metadata
- `get_account_list_by_access_token` - Accounts for access token

### Market (4 tools)
- `list_symbols` - Available instruments with metadata
- `get_symbol` - Detailed symbol information
- `list_symbol_categories` - Symbol category organization
- `get_market_data` - Recent market data and quotes

### Positions (4 tools)
- `list_positions` - Open positions and status
- `get_position_unrealized_pnl` - Position unrealized P&L
- `close_position` - Close position (with override validation)
- `list_deals_by_position_id` - Deal history for position

### Trading (5 tools)
- `list_orders` - Open orders with filtering
- `get_order_details` - Specific order information
- `create_order` - Create new order (with override validation)
- `amend_order` - Update order parameters (with override validation)
- `cancel_order` - Cancel open order

## Authentication

The server uses a **backdoor authentication model** (no OAuth required):

1. **Application Auth**: `ProtoOAApplicationAuthReq` with app credentials
2. **Account Auth**: `ProtoOAAccountAuthReq` with access token and account ID
3. **Session Ready**: All subsequent tool requests use authenticated session

```python
from ctrader_mcp_server.config import CTraderRuntimeConfig
from ctrader_mcp_server.ctrader_session import CTraderBackdoorSession

# Load credentials from env or Azure Key Vault
config = CTraderRuntimeConfig.from_env()

# Initialize session with backdoor auth
session = CTraderBackdoorSession(config)

# Session sends auth requests automatically
session.authenticate(client)
```

## Configuration

### Environment Variables

```bash
export ctrader-app-client-id="your-app-id"
export ctrader-app-client-secret="your-app-secret"
export ctrader-access-token-icmarkets="your-token"
export ctrader-account-id-icmarkets="your-account-id"
```

### Azure Key Vault

Alternatively, set the vault URL:

```bash
export AZURE_KEY_VAULT_URL="https://ctrader.vault.azure.net"
```

The app automatically retrieves:
- `ctrader-app-client-id`
- `ctrader-app-client-secret`
- `ctrader-access-token-icmarkets`
- `ctrader-account-id-icmarkets`

## Security

The server implements trust boundary protection via [security.py](src/ctrader_mcp_server/security.py):

- **Account Isolation**: Requests always bound to authenticated account
- **Parameter Validation**: Trading volumes, prices, sides validated
- **Output Wrapping**: Structured responses wrapped in security envelopes
- **Override Validation**: Custom functions validate complex requests

## Custom Overrides

[overrides.py](src/ctrader_mcp_server/overrides.py) provides targeted handling for complex operations:

```python
# Create order with volume validation
await override_create_order(
    account_id="123",
    symbol="EURUSD",
    side="BUY",
    order_type="MARKET",
    volume=100
)

# Close position with optional partial close
await override_close_position(
    account_id="123",
    position_id="pos-456",
    volume=50  # Optional: partial close
)

# Amend order with price/volume updates
await override_amend_order(
    account_id="123",
    order_id="order-789",
    price=1.2500  # Optional
)
```

## Architecture

- **OpenAPI-first MCP generation** - Tools derived from spec-driven sources
- **FastMCP integration** - Mounts spec-generated tools on startup
- **Override pattern** - Narrow custom handlers for non-trivial endpoints
- **Security wrappers** - Trust boundary enforcement at request/response boundary
- **Aligned with Alpaca reference** - Follows established MCP server patterns

## Reference Implementation

The Alpaca MCP server provides the architectural blueprint:

- [alpaca-mcp-server/README.md](alpaca-mcp-server/README.md)
- [alpaca-mcp-server/AGENTS.md](alpaca-mcp-server/AGENTS.md)