# Required
Node.js >= 18.0.0
pnpm >= 8.0.0 (REQUIRED - do not use npm or yarn)

# Optional
Docker & Docker Compose (for containerized deployment)
Private key for transaction execution

# Clone the repository
git clone https://github.com/Tairon-ai/telos-mcp.git
cd telos-mcp

# Install dependencies (MUST use pnpm)
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start the server
pnpm run start

# Development mode with hot reload
pnpm run start:dev

# MCP stdio server for Claude Desktop
pnpm run start:mcp

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

{
  "mcpServers": {
    "telos-mcp": {
      "command": "node",
      "args": ["/path/to/telos-mcp/dist/stdio/mcp-server.js"],
      "env": {
        "RPC_URL": "https://rpc.telos.net/evm",
        "PRIVATE_KEY": "your_private_key_without_0x"
      }
    }
  }
}

GET  /           # Server status and info
GET  /health     # Health check
GET  /mcp        # MCP server information
POST /mcp        # MCP protocol endpoint
GET  /mcp/tools  # List available tools
GET  /info       # Server capabilities

GET /sse         # Server-Sent Events for real-time updates
GET /stdio       # Stdio process status
POST /stdio      # Send request to stdio MCP server

// Stake 100 TLOS to earn 13% APY
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "telos_stake",
    "arguments": {
      "amount": "100",
      "address": "0x..."
    }
  },
  "id": 1
}

// Automatically convert USDC to TLOS and stake
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "smart_deposit_auto",
    "arguments": {
      "inputToken": "USDC",
      "amount": "1000",
      "address": "0x..."
    }
  },
  "id": 1
}

// Get quote for swapping 1000 TLOS to USDC
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "swapsicle_quote",
    "arguments": {
      "tokenIn": "TLOS",
      "tokenOut": "USDC",
      "amount": "1000"
    }
  },
  "id": 1
}

// Get top 5 stable coin yield opportunities
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "telos_top_stable_yields",
    "arguments": {
      "limit": 5
    }
  },
  "id": 1
}

"Check my TLOS balance and all token holdings at address 0x..."

"Show me the value of my portfolio in USD at 0x..."

"What's my sTLOS staking position and current rewards?"

"Calculate my total DeFi positions across all Telos protocols"

"I want to stake 500 TLOS to earn yield. My address is 0x..."

"Help me unstake 200 sTLOS back to TLOS"

"What's the current APY for sTLOS staking?"

"Show me my staking rewards and when I can claim them"

"Calculate how much I'll earn staking 1000 TLOS for 30 days"

"Find the best route to swap 1000 TLOS to USDC on Swapsicle"

"I have 500 USDT and want to convert it to TLOS with minimal slippage"

"Execute a swap of 2 ETH to USDC with maximum 1% slippage"

"Compare swap rates for 1000 TLOS to USDC across all DEXes"

"I have 1000 USDC and want to automatically convert and stake for best yield"

"Help me deposit and stake 500 USDT using smart deposit"

"Auto-convert my 2 ETH to TLOS and stake it all"

"What's the optimal deposit strategy for 5000 USDC?"

"Show me the top 10 liquidity pools on Telos by TVL"

"What are the best stable coin yield opportunities right now?"

"Find trending tokens on Telos with highest 24h volume"

"Show me real-time trading data for TLOS/USDC pair"

"What's the total TVL across all Telos DeFi protocols?"

"Get the current price of TLOS in USD"

"Show me the top 20 TLOS holders"

"Who are the biggest holders of ZAPPY token?"

"List all supported tokens with their current prices"

"Search for 'CHARM' token and show me its liquidity pools"

"What are the top 5 stable yields on Telos?"

"Show me the best APY opportunities for USDC"

"Compare yields between different stablecoin pools"

"Find the highest yielding pools with over $100k TVL"

"Calculate my potential returns for providing liquidity to TLOS/USDC"

"Check current gas prices on Telos network"

"Estimate transaction cost for staking 1000 TLOS"

"Show me my last 10 transactions"

"What's the optimal gas price for a fast transaction?"

# Run all tests
pnpm test

# Run with coverage
pnpm test:cov

# Run specific test suites
pnpm test:unit
pnpm test:integration
pnpm test:e2e

# Test specific modules
pnpm test:blockchain
pnpm test:staking
pnpm test:swaps

# Check server health
curl http://localhost:8080/health

# Get MCP server info
curl http://localhost:8080/mcp

# List all available tools
curl http://localhost:8080/mcp/tools

# Execute a tool
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_balance",
      "arguments": {
        "token": "TLOS",
        "address": "0x..."
      }
    },
    "id": 1
  }'

# Build for production
pnpm run build

# Start production server
pnpm run start:prod

# Build MCP server
pnpm run build:mcp

# With PM2
pm2 start dist/main.js --name telos-mcp

# With Docker
docker build -t telos-mcp .
docker run -d -p 8080:8080 --env-file .env telos-mcp

# Required
PORT=8080
RPC_URL=https://rpc.telos.net/evm
CHAIN_ID=40
PRIVATE_KEY=your_private_key_without_0x
TELOS_API_URL=https://api.teloscan.io

# Optional
LOG_LEVEL=info
AUTO_EXECUTE=true
TRANSACTION_MODE=interactive
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100

# Fork and clone
git fork https://github.com/Tairon-ai/telos-mcp
git clone https://github.com/Tairon-ai/telos-mcp

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
pnpm test
pnpm run lint

# Commit and push
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature

# Open Pull Request