get_positions

Instructions

Implementation Reference

• src/tools/GetPositions.ts:79-133 (handler)

  The `toolCall` method provides the execution logic for the 'get_positions' tool: validates input using Zod schema, prepares parameters, fetches position data from Bybit API, formats the response, and handles errors.

  async toolCall(request: z.infer<typeof CallToolRequestSchema>) {
    try {
      this.logInfo("Starting get_positions tool call")
  
      // Parse and validate input
      const validationResult = inputSchema.safeParse(request.params.arguments)
      if (!validationResult.success) {
        throw new Error(`Invalid input: ${validationResult.error.message}`)
      }
  
      const {
        category,
        symbol,
        baseCoin,
        settleCoin,
        limit = "200"
      } = validationResult.data
  
      this.logInfo(`Validated arguments - category: ${category}, symbol: ${symbol}, limit: ${limit}`)
  
      // Prepare request parameters
      const params: PositionInfoParamsV5 = {
        category,
        symbol,
        baseCoin,
        settleCoin,
        limit: parseInt(limit, 10)
      }
  
      // Execute API request with rate limiting and retry logic
      const response = await this.executeRequest(async () => {
        return await this.getPositionsData(params)
      })
  
      // Format response
      const result: FormattedPositionsResponse = {
        category,
        symbol,
        baseCoin,
        settleCoin,
        limit: parseInt(limit, 10),
        data: response.list,
        timestamp: new Date().toISOString(),
        meta: {
          requestId: crypto.randomUUID()
        }
      }
  
      this.logInfo(`Successfully retrieved positions data${symbol ? ` for ${symbol}` : ''}`)
      return this.formatResponse(result)
    } catch (error) {
      this.logInfo(`Error in get_positions: ${error instanceof Error ? error.message : String(error)}`)
      return this.handleError(error)
    }
  }

• src/tools/GetPositions.ts:39-70 (schema)

  The `toolDefinition` property defines the input schema, description, and metadata for the 'get_positions' tool, used for MCP tool listing and validation.

  toolDefinition: Tool = {
    name: this.name,
    description: "Get positions information for the authenticated user",
    inputSchema: {
      type: "object",
      properties: {
        category: {
          type: "string",
          description: "Product type",
          enum: ["linear", "inverse"],
        },
        symbol: {
          type: "string",
          description: "Trading symbol, e.g., BTCUSDT",
        },
        baseCoin: {
          type: "string",
          description: "Base coin. Used to get all symbols with this base coin",
        },
        settleCoin: {
          type: "string",
          description: "Settle coin. Used to get all symbols with this settle coin",
        },
        limit: {
          type: "string",
          description: "Maximum number of results (default: 200)",
          enum: ["1", "10", "50", "100", "200"],
        },
      },
      required: ["category"],
    },
  }

• src/utils/toolLoader.ts:23-81 (registration)

  The `loadTools` function dynamically scans the src/tools directory, imports and instantiates tool classes like GetPositions, validating they extend BaseToolImplementation, and returns the list of loaded tools for registration.

  export async function loadTools(): Promise<BaseToolImplementation[]> {
    try {
      const toolsPath = await findToolsPath()
      const files = await fs.readdir(toolsPath)
      const tools: BaseToolImplementation[] = []
  
      for (const file of files) {
        if (!isToolFile(file)) {
          continue
        }
  
        try {
          const modulePath = `file://${join(toolsPath, file)}`
          const { default: ToolClass } = await import(modulePath)
  
          if (!ToolClass || typeof ToolClass !== 'function') {
            console.warn(JSON.stringify({
              type: "warning",
              message: `Invalid tool class in ${file}`
            }))
            continue
          }
  
          const tool = new ToolClass()
  
          if (
            tool instanceof BaseToolImplementation &&
            tool.name &&
            tool.toolDefinition &&
            typeof tool.toolCall === "function"
          ) {
            tools.push(tool)
            console.info(JSON.stringify({
              type: "info",
              message: `Loaded tool: ${tool.name}`
            }))
          } else {
            console.warn(JSON.stringify({
              type: "warning",
              message: `Invalid tool implementation in ${file}`
            }))
          }
        } catch (error) {
          console.error(JSON.stringify({
            type: "error",
            message: `Error loading tool from ${file}: ${error instanceof Error ? error.message : String(error)}`
          }))
        }
      }
  
      return tools
    } catch (error) {
      console.error(JSON.stringify({
        type: "error",
        message: `Failed to load tools: ${error instanceof Error ? error.message : String(error)}`
      }))
      return []
    }
  }

• src/tools/GetPositions.ts:72-77 (helper)

  Private helper method `getPositionsData` that calls the Bybit API's `getPositionInfo` endpoint to retrieve raw position data.

  private async getPositionsData(
    params: PositionInfoParamsV5
  ): Promise<APIResponseV3WithTime<{ list: PositionV5[] }>> {
    this.logInfo(`Fetching positions with params: ${JSON.stringify(params)}`)
    return await this.client.getPositionInfo(params)
  }

• src/index.ts:134-135 (registration)

  In the main function, `loadTools()` is called to load tools including 'get_positions', and `createToolsMap` populates the toolsMap used by MCP request handlers for tool listing and execution.

  const tools = await loadTools()
  toolsMap = createToolsMap(tools)