Bybit MCP Server

Instructions

Implementation Reference

• src/bybit-service.ts:443-523 (handler)

  The core handler function that implements the detect_position_mode tool logic. It fetches current positions via getPositions, analyzes whether the account is in 'one-way' or 'hedge' mode by checking for simultaneous long/short positions or positionIdx values, and returns the detected mode, recommended positionIdx, explanation, and current positions list.

  async detectPositionMode(
    category: string,
    symbol?: string
  ): Promise<{
    positionMode: 'one-way' | 'hedge';
    recommendedPositionIdx: string;
    explanation: string;
    currentPositions: any[];
  }> {
    try {
      // Get current positions
      const currentPositions = await this.getPositions(category, symbol);
      
      if ('error' in currentPositions) {
        return {
          positionMode: 'one-way',
          recommendedPositionIdx: '0',
          explanation: `Could not check positions: ${currentPositions.error}. Defaulting to one-way mode.`,
          currentPositions: []
        };
      }
  
      const positions = currentPositions.result.list;
      
      if (positions.length === 0) {
        return {
          positionMode: 'one-way',
          recommendedPositionIdx: '0',
          explanation: 'No existing positions found. Defaulting to one-way mode (positionIdx: 0).',
          currentPositions: []
        };
      }
  
      // Check if we have separate long/short positions (hedge mode)
      const hasLongPosition = positions.some(p => p.side === 'Buy' && parseFloat(p.size) > 0);
      const hasShortPosition = positions.some(p => p.side === 'Sell' && parseFloat(p.size) > 0);
      
      if (hasLongPosition && hasShortPosition) {
        return {
          positionMode: 'hedge',
          recommendedPositionIdx: '1', // Default to long for new orders
          explanation: 'Hedge mode detected (both long and short positions exist). Use positionIdx: 1 for long, 2 for short.',
          currentPositions: positions
        };
      } else if (hasLongPosition || hasShortPosition) {
        // Check if positions have positionIdx > 0 (indicating hedge mode setup)
        const hasHedgePositions = positions.some(p => p.positionIdx > 0);
        
        if (hasHedgePositions) {
          return {
            positionMode: 'hedge',
            recommendedPositionIdx: '1',
            explanation: 'Hedge mode detected (positions have positionIdx > 0). Use positionIdx: 1 for long, 2 for short.',
            currentPositions: positions
          };
        } else {
          return {
            positionMode: 'one-way',
            recommendedPositionIdx: '0',
            explanation: 'One-way mode detected (single position type with positionIdx: 0).',
            currentPositions: positions
          };
        }
      } else {
        return {
          positionMode: 'one-way',
          recommendedPositionIdx: '0',
          explanation: 'One-way mode detected (no active positions, but account configured for one-way).',
          currentPositions: positions
        };
      }
  
    } catch (error: any) {
      return {
        positionMode: 'one-way',
        recommendedPositionIdx: '0',
        explanation: `Error detecting position mode: ${error.message}. Defaulting to one-way mode.`,
        currentPositions: []
      };
    }
  }

• src/index.ts:509-526 (schema)

  The input schema definition for the detect_position_mode tool, registered in the MCP server's listTools response. Specifies required 'category' parameter and optional 'symbol'.

  {
    name: 'detect_position_mode',
    description: 'Detect current position mode (one-way vs hedge) and get recommended positionIdx for orders',
    inputSchema: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          description: 'Category (spot, linear, inverse, etc.)',
        },
        symbol: {
          type: 'string',
          description: 'Symbol (e.g., ETHUSDT) - optional, will check all positions if not provided',
        },
      },
      required: ['category'],
    },
  },

• src/index.ts:972-985 (registration)

  The switch case registration in the MCP CallToolRequestSchema handler that routes detect_position_mode tool calls to the BybitService.detectPositionMode method and returns the JSON-stringified result.

  case 'detect_position_mode': {
    const result = await this.bybitService.detectPositionMode(
      typedArgs.category,
      typedArgs.symbol
    );
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }