Trading Simulator MCP Server

# Trading Simulator MCP Server - Development Guide ## Overview This document outlines the approach for building a Model Context Protocol (MCP) server that interfaces with the Trading Simulator API. The MCP server will allow language models and AI agents to perform the following operations through structured tool calls: 1. Check account balances and portfolio information 2. Check token prices across multiple blockchains 3. Execute trades between tokens, including cross-chain operations 4. View competition status and leaderboard information ## Architecture The MCP server will follow a modular architecture with these components: 1. **MCP Server Core** - Handles MCP protocol communication using the `@modelcontextprotocol/sdk` 2. **Trading Simulator API Client** - Manages authenticated requests to the Trading Simulator API 3. **Tool Handlers** - Processes tool requests from language models and returns formatted responses 4. **Environment Management** - Securely handles API credentials and configuration ## Implementation Steps ### 1. Project Setup 1. Initialize a new TypeScript project with the following structure: ``` trading-simulator-mcp/ ├── src/ │ ├── index.ts # Main server implementation │ ├── api-client.ts # Trading Simulator API client │ ├── types.ts # TypeScript type definitions │ └── env.ts # Environment variable management ├── .env.example # Example environment variables ├── .gitignore # Git ignore file ├── package.json # Project dependencies ├── tsconfig.json # TypeScript configuration └── README.md # Project documentation ``` 2. Configure package.json with required dependencies: - `@modelcontextprotocol/sdk` - For MCP server implementation - `dotenv` - For environment variable management - TypeScript and related development tools 3. Set up TypeScript configuration in tsconfig.json for a Node.js environment ### 2. API Client Implementation Create a client for the Trading Simulator API that handles: 1. Authentication with HMAC signatures 2. Request formatting and response parsing 3. Error handling and retries 4. Helper utilities for common operations The client should implement all endpoints from the API documentation: - Account endpoints (`/api/account/*`) - Price endpoints (`/api/price/*`) - Trading endpoints (`/api/trade/*`) - Competition endpoints (`/api/competition/*`) ### 3. MCP Server Implementation Implement the MCP server with the following features: 1. Tool definitions: - **Account Tools** - `get_balances` - Get token balances - `get_portfolio` - Get portfolio information - `get_trades` - Get trade history - **Price Tools** - `get_price` - Get token price - `get_token_info` - Get detailed token information - `get_price_history` - Get historical price data - **Trading Tools** - `execute_trade` - Execute a token trade - `get_quote` - Get a quote for a potential trade - **Competition Tools** - `get_competition_status` - Get competition information - `get_leaderboard` - Get competition leaderboard 2. Integration with the API client for handling tool requests 3. Proper error handling and response formatting 4. Support for required MCP protocol features ### 4. Environment and Security Implement secure credential management: 1. Load API key and secret from environment variables 2. Add protection against accidentally exposing credentials 3. Configure environment variables for API base URL and other settings 4. Create detailed documentation on secure setup and usage ### 5. Testing Implement a comprehensive testing strategy: 1. Unit tests for API client and tool handlers 2. Integration tests with the Trading Simulator API (using test accounts) 3. End-to-end tests with MCP clients (such as Cursor or Claude Desktop) ### 6. Documentation Create detailed documentation: 1. Installation and setup instructions 2. Tool usage examples and specifications 3. Security best practices 4. Troubleshooting guide ## MCP Tool Specifications Below are the detailed specifications for each MCP tool to be implemented: ### Account Tools #### get_balances - **Description**: Get token balances for your team - **Parameters**: None - **Returns**: List of tokens with their balances #### get_portfolio - **Description**: Get portfolio information for your team - **Parameters**: None - **Returns**: Portfolio value and token positions #### get_trades - **Description**: Get trade history for your team - **Parameters**: - `limit` (optional): Number of trades to return - `offset` (optional): Pagination offset - `token` (optional): Filter by token address - `chain` (optional): Filter by chain ("svm" or "evm") - **Returns**: List of trades with details ### Price Tools #### get_price - **Description**: Get the current price for a token - **Parameters**: - `token` (required): Token address - `chain` (optional): Blockchain type ("svm" or "evm") - `specificChain` (optional): Specific EVM chain - **Returns**: Token price information #### get_token_info - **Description**: Get detailed information about a token - **Parameters**: - `token` (required): Token address - `chain` (optional): Blockchain type - `specificChain` (optional): Specific EVM chain - **Returns**: Token details including chain information #### get_price_history - **Description**: Get historical price data for a token - **Parameters**: - `token` (required): Token address - `startTime` (optional): ISO timestamp - `endTime` (optional): ISO timestamp - `interval` (optional): Time interval - `chain` (optional): Blockchain type - `specificChain` (optional): Specific EVM chain - **Returns**: Historical price data ### Trading Tools #### execute_trade - **Description**: Execute a trade between two tokens - **Parameters**: - `fromToken` (required): Source token address - `toToken` (required): Destination token address - `amount` (required): Amount to trade - `slippageTolerance` (optional): Slippage tolerance percentage - **Returns**: Trade execution details #### get_quote - **Description**: Get a quote for a potential trade - **Parameters**: - `fromToken` (required): Source token address - `toToken` (required): Destination token address - `amount` (required): Amount to trade - **Returns**: Trade quote with estimated amounts ### Competition Tools #### get_competition_status - **Description**: Get the status of the current competition - **Parameters**: None - **Returns**: Competition information #### get_leaderboard - **Description**: Get the competition leaderboard - **Parameters**: None - **Returns**: Leaderboard with team rankings ## Implementation Notes 1. **Error Handling**: All tools should handle errors gracefully and return informative error messages 2. **Rate Limiting**: Consider implementing rate limiting to stay within API constraints 3. **Caching**: Implement caching for frequently requested data to improve performance 4. **Authentication**: Securely manage API credentials and regenerate signatures for each request 5. **Cross-Chain Support**: Support both Solana and Ethereum tokens and their specific chains ## Resources - Trading Simulator API Documentation in `/docs/api/API_DOCUMENTATION.md` - Example API client in `/docs/api/api-client.ts` ## Security Considerations 1. **API Credentials**: Never expose the API secret in responses 2. **Environment Variables**: Store sensitive credentials in environment variables 3. **Signature Generation**: Ensure HMAC signatures are correctly generated 4. **Error Messages**: Don't expose sensitive information in error messages This guide provides a comprehensive approach to building the Trading Simulator MCP server. Follow these instructions to implement a robust, secure, and feature-complete MCP server that allows AI agents to interact with the Trading Simulator API.