Сервер Luno MCP

Сервер Model Context Protocol (MCP) для API криптовалютной биржи Luno. Этот сервер предоставляет стандартизированный интерфейс для моделей и приложений ИИ для взаимодействия с API Luno для торговли криптовалютой.

 _                        __  __  ____ ____   
| |    _   _ _ __   ___  |  \/  |/ ___|  _ \  
| |   | | | | '_ \ / _ \ | |\/| | |   | |_) | 
| |___| |_| | | | | (_) || |  | | |___|  __/  
|_____|\__,_|_| |_|\___/ |_|  |_|\____|_|     

Функции

• Информация о ценах криптовалют в режиме реального времени через API Luno

• Обзор рынка по всем торговым парам

• Запросы баланса счета

• Управление заказами (размещение, отмена, статус)

• Извлечение истории транзакций

• Информация о сборах

• Стандартизированный интерфейс JSON-RPC 2.0

• Простая интеграция с приложениями ИИ

Related MCP server: Alpaca MCP Server

Предпосылки

• Python 3.8+ (рекомендуется Python 3.9+)

• uv для управления пакетами

• Учетная запись Luno с ключами API (для полной функциональности)

Установка

1. Клонировать этот репозиторий

git clone https://github.com/amanasmuei/mcp-luno.git
cd mcp-luno

2. Создать виртуальную среду с помощью uv

uv venv
source .venv/bin/activate  # On macOS/Linux
# On Windows use: .venv\Scripts\activate

3. Установить зависимости

uv pip install -r requirements.txt

4. Настройте учетные данные API Luno (выберите один способ):

Поддержка докера

Вы можете запустить сервер MCP с помощью Docker для более простого развертывания и обеспечения единообразной среды на разных платформах.

Использование Docker Compose (рекомендуется)

1. Скопируйте пример файла среды и настройте свои учетные данные:

cp .env.example .env
# Edit .env file with your Luno API credentials

2. Запустите сервер:

docker compose up -d

Сервер будет доступен по адресу ws://localhost:8765 в режиме WebSocket.

3. Просмотр журналов:

docker compose logs -f

4. Остановите сервер:

docker compose down

Использование Docker напрямую

Создайте изображение:

docker build -t mcp-luno .

Запустите контейнер:

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

Использование с помощниками на основе искусственного интеллекта

После запуска контейнера Docker вы можете подключить различных помощников на основе искусственного интеллекта для использования сервера Luno MCP:

Курсор

Добавьте следующее в конфигурацию курсора:

{
  "mcp_servers": {
    "luno": {
      "type": "websocket",
      "url": "ws://localhost:8765"
    }
  }
}

Клод Десктоп

В настройках Claude Desktop у вас есть два варианта настройки сервера MCP:

Вариант 1: использование Docker (рекомендуется)

{
  "mcpServers": {
    "luno": {
      "command": "docker",
      "args": ["compose", "up"],
      "cwd": "/path/to/mcp-luno",
      "transport": "websocket",
      "url": "ws://localhost:8765",
      "env": {
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

Эта конфигурация запускает сервер в контейнере Docker и подключается через WebSocket.

Вариант 2: использование прямого выполнения Python

{
  "mcpServers": {
    "luno": {
      "command": "python",
      "args": ["-m", "src.main", "--transport", "stdio"],
      "cwd": "/path/to/mcp-luno",
      "transport": "stdio",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

Эта конфигурация запускает сервер Python напрямую с использованием транспорта STDIO.

Примечание: замените /path/to/mcp-luno фактическим путем, по которому вы клонировали репозиторий.

Клайн

Добавьте следующее в файл конфигурации Cline:

{
  "mcp": {
    "servers": {
      "luno": {
        "transport": "websocket",
        "url": "ws://localhost:8765"
      }
    }
  }
}

Поддержка SSL с Docker

Чтобы использовать SSL с контейнером Docker:

1. Сгенерируйте сертификаты с помощью предоставленного скрипта:

./generate_certificates.sh

2. Смонтируйте каталог сертификатов при запуске контейнера:

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

Ручная установка

Вариант А : использование файла .env

cp .env.example .env

Затем отредактируйте файл .env , чтобы добавить свои учетные данные API Luno:

LUNO_API_KEY=your_api_key_here
LUNO_API_SECRET=your_api_secret_here

Вариант B : использование конфигурации VS Code MCP

Отредактируйте файл .vscode/mcp.json и добавьте свои учетные данные в раздел env :

"env": {
  "PYTHONPATH": "${workspaceFolder}",
  "LUNO_API_KEY": "your_api_key_here",
  "LUNO_API_SECRET": "your_api_secret_here",
  "LOG_LEVEL": "INFO"
}

Примечание : Без действительных учетных данных API будут доступны только публичные конечные точки. Рекомендация : В целях безопасности предпочитайте переменные среды при совместном использовании кода.

Запуск сервера

Вы можете запустить сервер MCP в двух различных транспортных режимах:

Транспорт STDIO (по умолчанию, один клиент)

Это режим по умолчанию, который поддерживает одно клиентское соединение через стандартный ввод/вывод:

python -m src.main --transport stdio

Транспорт WebSockets (несколько клиентов)

Для поддержки нескольких клиентских подключений одновременно запустите сервер в режиме WebSocket:

python -m src.main --transport websocket [--host HOST] [--port PORT]

По умолчанию сервер WebSocket запустится по адресу ws://localhost:8765 .

Тестирование сервера WebSocket

Вы можете протестировать сервер WebSocket с помощью прилагаемого тестового клиента:

python test_websocket_client.py

Это помогает убедиться, что сервер правильно обрабатывает соединения WebSocket и отвечает на запросы.

Параметры командной строки

• --transport {stdio,websocket} : используемый транспортный механизм (по умолчанию: stdio)

• --host HOST : Хост для привязки при использовании транспорта WebSocket (по умолчанию: localhost)

• --port PORT : Порт для привязки при использовании транспорта WebSocket (по умолчанию: 8765)

Переменные среды

Вы также можете настроить транспорт с помощью переменных среды:

• MCP_TRANSPORT : Транспортный механизм («stdio» или «websocket»)

• MCP_HOST : Хост для привязки к транспорту WebSocket

• MCP_PORT : порт для привязки к транспорту WebSocket

Тестирование со стандартным клиентом

Для тестирования транспорта STDIO используйте прилагаемый тестовый клиент:

python test_client.py

Интеграция протокола MCP

Этот сервер реализует протокол контекста модели, который позволяет моделям ИИ взаимодействовать с ним через стандартизированные сообщения JSON-RPC 2.0. Сервер работает через STDIO по умолчанию, что упрощает интеграцию с расширениями VS Code и другими MCP-совместимыми клиентами.

Интеграция VS-кода

Файл .vscode/mcp.json настраивает сервер для использования с VS Code. Предоставляются две конфигурации сервера:

1. luno-mcp-server-stdio — использует транспорт STDIO (поведение MCP по умолчанию)

2. luno-mcp-server-websocket — использует транспорт WebSocket для поддержки нескольких клиентов

Конфигурация VS-кода

Для использования транспорта WebSocket с VS Code файл mcp.json включает конфигурацию типа процесса:

"luno-mcp-server-websocket": {
  "type": "process",
  "command": "python",
  "args": ["-m", "src.main", "--transport", "websocket"],
  "env": {
    // environment variables
  }
}

При использовании транспорта WebSocket VS Code запустит сервер как фоновый процесс, а не будет взаимодействовать через STDIO.

Настройка MCP-сервера в VS Code

Вы можете настроить сервер непосредственно из файла .vscode/mcp.json :

{
  "servers": {
    "luno-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src.main"],
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Эта конфигурация будет использоваться расширениями VS Code, поддерживающими протокол MCP, что упрощает интеграцию с моделями ИИ и другими инструментами.

Доступные методы

Примеры запросов

Получить возможности сервера:

{
  "jsonrpc": "2.0",
  "method": "describe_capabilities",
  "params": {},
  "id": 1
}

Получить цену Bitcoin-ZAR:

{
  "jsonrpc": "2.0",
  "method": "get_crypto_price",
  "params": {"pair": "XBTZAR"},
  "id": 2
}

Разработка

Структура проекта

├── .env                 # Environment variables (API credentials)
├── .gitignore           # Git ignore configuration
├── .vscode/             # VS Code specific settings
│   └── mcp.json         # MCP configuration for VS Code
├── src/                 # Source code
│   ├── main.py          # Entry point
│   └── luno_mcp_server/ # MCP server implementation
│       ├── luno_client.py # Luno API client
│       └── server.py    # MCP server core
├── tests/               # Test suite
├── test_client.py       # Simple test client for the MCP server
├── requirements.txt     # Project dependencies
└── setup.py             # Package setup

Проведение тестов

python -m pytest tests/

Добавление новых функций

Чтобы добавить новые возможности API Luno:

1. Расширьте класс LunoClient в src/luno_mcp_server/luno_client.py новыми методами API

2. Добавьте соответствующие методы в класс LunoMCPServer в src/luno_mcp_server/server.py

3. Обновите список MCP_METHODS в server.py и зарегистрируйте свои методы в функции _register_methods

4. Добавьте тесты в каталог tests/

Архитектура

Сервер MCP использует простую архитектуру:

• JSON-RPC 2.0 для связи

• Стандартный ввод/вывод (STDIO) для транспорта

• Клиент API Luno для криптовалютных операций

Поиск неисправностей

Распространенные проблемы

• Ошибки аутентификации API : убедитесь, что ключи API Luno правильно установлены либо в файле .env , либо в .vscode/mcp.json

• Ошибки импорта : убедитесь, что вы активировали виртуальную среду.

• Ограничение скорости : API Luno имеет ограничения скорости — реализуйте логику повторных попыток для использования в производстве.

Приоритет конфигурации

При запуске сервера значения конфигурации загружаются в следующем порядке приоритета:

1. Переменные среды, проходящие через конфигурацию MCP (наивысший приоритет)

2. Значения в файле .env

3. Значения по умолчанию в коде (самый низкий приоритет)

Это означает, что вы можете задать значения в конфигурации MCP, чтобы переопределить любые существующие значения в вашем файле .env .

Поддержка нескольких клиентов

Этот сервер MCP поддерживает несколько клиентских подключений одновременно через WebSockets. Для получения подробной информации см. MULTI_CLIENT_SUPPORT.md .

Варианты транспорта

Сервер поддерживает два транспортных механизма:

1. STDIO (по умолчанию): стандартный ввод/вывод — один клиент, используется VS Code MCP

2. WebSockets : сетевой транспорт — несколько клиентов с функциями безопасности

Работа с WebSockets Transport

Основное использование:

python -m src.main --transport websocket --host localhost --port 8765

С опциями безопасности:

python -m src.main --transport websocket --host localhost --port 8765 \
  --max-connections 50 --max-message-size 1048576 --rate-limit 100

С шифрованием SSL/TLS:

# First generate certificates
./generate_certificates.sh

# Then run with SSL support
python -m src.main --transport websocket --ssl-cert ./certs/server.crt --ssl-key ./certs/server.key

Инструменты клиента WebSocket

Репозиторий включает два клиентских инструмента:

1. test_websocket_client.py : Простой тестовый клиент

   python test_websocket_client.py

2. enhance_websocket_client.py : Расширенный клиент с многоклиентской симуляцией

   # Single client mode
   python enhanced_websocket_client.py --mode single
   
   # Multi-client simulation (3 clients)
   python enhanced_websocket_client.py --mode multi --clients 3

Лицензия

Лицензия Массачусетского технологического института

Авторские права (c) 2025

Настоящим предоставляется разрешение любому лицу на бесплатное получение копии данного программного обеспечения и связанных с ним файлов документации.