mcp-solana-dex

MCP Solana DEX Server

This directory contains a a simple Decentralized Exchange (DEX) MCP server.

Purpose

This server provides basic DEX functionalities for tokens associated with ICOs managed by the main server:

• Creating sell orders.
• Cancelling sell orders.
• Executing sell orders (buying from existing orders).
• Retrieving the current order book for an ICO.

Features

• MCP Tools: Exposes DEX functions as MCP tools (create_order, cancel_order, execute_order, get_orders).
• File-Based Persistence: Stores the order book in a JSON file (data/order_book.json by default).
• ICO Association: Orders are associated with specific ico_ids.

Disclaimer: This is a simplified example. The execute_order tool performs server-side pre-condition checks (buyer SOL balance, seller token balance) before updating the internal order book. It does NOT execute the on-chain atomic swap. Clients interacting with this server are responsible for constructing and submitting the actual atomic swap transaction after receiving a success response from execute_order. This is NOT suitable for production without a robust client-side atomic swap implementation.

Configuration (./.env)

Create a .env file in this directory (./) with the following:

# Configuration for MCP Solana DEX Sub-project

# Solana RPC Endpoint (use the same as the main project or specify a different one)
RPC_ENDPOINT="http://localhost:8899"

# Path to the order book data file (relative to this directory)
ORDER_BOOK_FILE="data/order_book.json"

# Optional: Define the token mint address if needed globally
# TOKEN_MINT_ADDRESS="TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"

Usage

This server is intended to be run as a separate process from the main ICO server.

1. Ensure Dependencies: Make sure dependencies are installed (likely managed by the parent project's poetry install).

2. Navigate to Parent Directory: Open your terminal in the main project root.

3. Start the DEX Server:

   poetry run python mcp_solana_dex/server.py
   

4. Interact: Use an MCP client connected to the standard input/output of this process.

MCP Tools

• create_order: Creates a new sell order.
  • ico_id: (String) The ID of the ICO for the token.
  • amount: (Integer) Amount of tokens to sell (base units).
  • price: (Float) Price per token in SOL.
  • owner: (String) Public key of the seller.
• cancel_order: Cancels an existing order.
  • ico_id: (String) The ID of the ICO.
  • order_id: (String) The unique ID of the order to cancel.
  • owner: (String) Public key of the seller (must match order).
• execute_order: Performs pre-condition checks for executing a sell order and updates the internal order book if checks pass. Does not execute the on-chain swap.
  • ico_id: (String) The ID of the ICO.
  • order_id: (String) The ID of the order to buy from.
  • buyer: (String) Public key of the buyer.
  • amount: (Integer) Amount of tokens to buy (base units).
  • token_mint_address: (String) Mint address of the token.
  • token_decimals: (Integer) Decimals of the token.
  • Note: Clients must construct and submit the actual atomic swap transaction separately after successful pre-checks.
• get_orders: Retrieves the current sell orders for an ICO.
  • ico_id: (String) The ID of the ICO.
  • limit: (Integer, optional) Max orders to return (default 100).

Testing

This project uses pytest for integration testing. The tests primarily call the server's tool functions directly, mocking necessary external interactions (like Solana RPC calls) to verify the server's internal logic and state management.

1. Install Development Dependencies: Make sure you have the main dependencies installed, then install the development dependencies which include pytest and pytest-asyncio:

   # Navigate to the project root directory (where pyproject.toml is)
   poetry install --with dev
   

2. Run Tests: Execute pytest from the project root directory:

   poetry run pytest
   

   Pytest will automatically discover and run the tests located in the tests/ directory.

Future Considerations

• Client-Side Atomic Swaps: Ensure clients interacting with this server implement secure, atomic order execution (combining SOL payment and token transfer) using appropriate Solana transaction construction. The server only performs pre-checks.
• Database Persistence: Replace file storage with a database (e.g., SQLite, PostgreSQL) for better scalability and reliability.
• Buy Orders: Add support for creating and matching buy orders.
• Error Handling: Improve validation and error handling.
• Testing: Add comprehensive unit and integration tests.