# MCP MT4 Connector - Tools Specification

**Version:** 0.1.0
**Date:** 2026-01-04
**Total Tools:** 6

---

## Tool Overview

| Tool Name | Description | Risk Level |
|-----------|-------------|------------|
| `mt4_get_account` | Get account information | Low |
| `mt4_get_positions` | List open positions | Low |
| `mt4_get_quote` | Get current price quote | Low |
| `mt4_execute_trade` | Execute market order | HIGH |
| `mt4_close_position` | Close a position | HIGH |
| `mt4_modify_position` | Modify SL/TP | Medium |

---

## mt4_get_account

### Description
Retrieves comprehensive account information from the connected MT4 terminal including balance, equity, margin, leverage, and broker details.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| - | - | - | No parameters required |

### Return Value
```json
{
  "success": true,
  "data": {
    "balance": 10000.00,
    "equity": 10250.50,
    "margin": 500.00,
    "freeMargin": 9750.50,
    "marginLevel": 2050.10,
    "profit": 250.50,
    "currency": "USD",
    "leverage": 100,
    "name": "Demo Account",
    "server": "ICMarkets-Demo",
    "company": "IC Markets"
  }
}
```

### Example Usage
```typescript
// Get account info
const result = await mt4_get_account({});

// Response content:
// MT4 Account Information
// =======================
// Account Name: Demo Account
// Server: ICMarkets-Demo
// Broker: IC Markets
// Leverage: 1:100
//
// Financial Summary
// -----------------
// Balance: 10000.00 USD
// Equity: 10250.50 USD
// Profit/Loss: +250.50 USD
```

### Errors
| Code | Message | Solution |
|------|---------|----------|
| - | MT4 terminal is not connected | Check MT4 Gateway connection |

---

## mt4_get_positions

### Description
Lists all currently open trading positions from the MT4 terminal. Can optionally filter by symbol.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `symbol` | string | No | Filter positions by symbol (e.g., XAUUSD) |

### Return Value
```json
{
  "success": true,
  "data": {
    "positions": [
      {
        "ticket": 123456,
        "symbol": "XAUUSD",
        "type": "buy",
        "lots": 0.10,
        "openPrice": 2650.50,
        "currentPrice": 2655.00,
        "stopLoss": 2640.00,
        "takeProfit": 2680.00,
        "profit": 45.00,
        "swap": -1.20,
        "openTime": "2026-01-04T10:30:00Z",
        "magic": 12345,
        "comment": "AI Signal"
      }
    ],
    "totalProfit": 45.00,
    "count": 1
  }
}
```

### Example Usage
```typescript
// Get all positions
const result = await mt4_get_positions({});

// Get only XAUUSD positions
const goldPositions = await mt4_get_positions({ symbol: "XAUUSD" });
```

### Errors
| Code | Message | Solution |
|------|---------|----------|
| - | MT4 terminal is not connected | Check MT4 Gateway connection |

---

## mt4_get_quote

### Description
Retrieves the current bid/ask prices for a trading symbol. Also calculates the spread in points/pips.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `symbol` | string | Yes | Trading symbol (e.g., XAUUSD, EURUSD) |

### Return Value
```json
{
  "success": true,
  "data": {
    "symbol": "XAUUSD",
    "bid": 2650.50,
    "ask": 2650.80,
    "spread": 0.30,
    "timestamp": "2026-01-04T12:00:00.000Z"
  }
}
```

### Example Usage
```typescript
// Get gold price
const quote = await mt4_get_quote({ symbol: "XAUUSD" });

// Response content:
// Price Quote: XAUUSD
// =========================
// Bid: 2650.50
// Ask: 2650.80
// Spread: 0.30 (3.0 pips)
// Time: 2026-01-04T12:00:00.000Z
```

### Errors
| Code | Message | Solution |
|------|---------|----------|
| - | No quote data available for {symbol} | Verify symbol is available on broker |

---

## mt4_execute_trade

### Description
Opens a new trading position with a market order. Supports BUY and SELL orders with optional stop loss and take profit levels.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `symbol` | string | Yes | Trading symbol (e.g., XAUUSD) |
| `action` | string | Yes | Trade direction: "buy" or "sell" |
| `lots` | number | Yes | Volume in lots (e.g., 0.01, 0.1, 1.0) |
| `stopLoss` | number | No | Stop loss price level |
| `takeProfit` | number | No | Take profit price level |
| `slippage` | number | No | Maximum slippage in points (default: 3) |
| `magic` | number | No | Magic number for EA identification (default: 12345) |
| `comment` | string | No | Order comment (max 31 chars) |

### Return Value
```json
{
  "success": true,
  "data": {
    "success": true,
    "ticket": 123456,
    "message": "Order placed successfully",
    "symbol": "XAUUSD",
    "action": "buy",
    "lots": 0.1
  }
}
```

### Example Usage
```typescript
// Simple buy order
const result = await mt4_execute_trade({
  symbol: "XAUUSD",
  action: "buy",
  lots: 0.1
});

// Buy with risk management
const result = await mt4_execute_trade({
  symbol: "XAUUSD",
  action: "buy",
  lots: 0.1,
  stopLoss: 2640.00,
  takeProfit: 2680.00,
  comment: "AI Signal - Gold Long"
});

// Sell order
const result = await mt4_execute_trade({
  symbol: "EURUSD",
  action: "sell",
  lots: 0.5,
  stopLoss: 1.1050,
  takeProfit: 1.0900
});
```

### Validation Rules
- For BUY orders: stopLoss must be below takeProfit
- For SELL orders: stopLoss must be above takeProfit
- Lots must be positive and reasonable (max 100)

### Errors
| Code | Message | Solution |
|------|---------|----------|
| - | For BUY orders, stop loss must be below take profit | Fix SL/TP levels |
| - | For SELL orders, stop loss must be above take profit | Fix SL/TP levels |
| - | Trade execution failed | Check margin, market hours |

---

## mt4_close_position

### Description
Closes an open position by ticket number. Can optionally close only a partial volume.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticket` | number | Yes | Position ticket number to close |
| `lots` | number | No | Partial volume to close (default: close all) |
| `slippage` | number | No | Maximum slippage in points (default: 3) |

### Return Value
```json
{
  "success": true,
  "data": {
    "success": true,
    "ticket": 123456,
    "message": "Position closed"
  }
}
```

### Example Usage
```typescript
// Close entire position
const result = await mt4_close_position({
  ticket: 123456
});

// Close partial position (0.5 of 1.0 lots)
const result = await mt4_close_position({
  ticket: 123456,
  lots: 0.5
});
```

### Errors
| Code | Message | Solution |
|------|---------|----------|
| - | Position with ticket {x} not found | Verify ticket number |
| - | Requested lots exceeds position size | Reduce lots parameter |

---

## mt4_modify_position

### Description
Modifies the stop loss and/or take profit levels of an existing open position.

### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticket` | number | Yes | Position ticket number to modify |
| `stopLoss` | number | No | New stop loss price level |
| `takeProfit` | number | No | New take profit price level |

### Return Value
```json
{
  "success": true,
  "data": {
    "success": true,
    "ticket": 123456,
    "message": "Position modified successfully"
  }
}
```

### Example Usage
```typescript
// Set both SL and TP
const result = await mt4_modify_position({
  ticket: 123456,
  stopLoss: 2640.00,
  takeProfit: 2680.00
});

// Update only take profit (trailing)
const result = await mt4_modify_position({
  ticket: 123456,
  takeProfit: 2700.00
});

// Set only stop loss (risk management)
const result = await mt4_modify_position({
  ticket: 123456,
  stopLoss: 2650.00
});
```

### Validation Rules
- At least one of stopLoss or takeProfit must be provided
- For BUY positions: stopLoss must be below takeProfit
- For SELL positions: stopLoss must be above takeProfit

### Errors
| Code | Message | Solution |
|------|---------|----------|
| - | At least one of stopLoss or takeProfit must be provided | Add SL or TP |
| - | Position with ticket {x} not found | Verify ticket number |
| - | For BUY positions, stop loss must be below take profit | Fix SL/TP levels |

---

## Common Error Responses

### Connection Error
```json
{
  "success": false,
  "error": "MT4 terminal is not connected"
}
```

### Validation Error
```json
{
  "success": false,
  "error": "Validation error",
  "details": [
    {
      "path": ["symbol"],
      "message": "Required"
    }
  ]
}
```

### Trading Error
```json
{
  "success": false,
  "error": "Trade execution failed: Insufficient margin"
}
```

---

## Usage Examples with AI Agent

### Scenario 1: Check Account and Open Trade
```
Agent: "Check my account balance and if equity is above 10000, buy 0.1 lots of XAUUSD"

1. Call mt4_get_account({})
2. Parse response, check equity > 10000
3. Call mt4_execute_trade({ symbol: "XAUUSD", action: "buy", lots: 0.1 })
```

### Scenario 2: Risk Management
```
Agent: "Set stop loss at 2640 and take profit at 2680 for my gold position"

1. Call mt4_get_positions({ symbol: "XAUUSD" })
2. Get ticket number from response
3. Call mt4_modify_position({ ticket: 123456, stopLoss: 2640, takeProfit: 2680 })
```

### Scenario 3: Close Profitable Trades
```
Agent: "Close all profitable gold positions"

1. Call mt4_get_positions({ symbol: "XAUUSD" })
2. Filter positions where profit > 0
3. For each: Call mt4_close_position({ ticket: ticketNumber })
```

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 0.1.0 | 2026-01-04 | Initial release with 6 core tools |