get_credit_balance

Instructions

Implementation Reference

• src/tools/credits/index.js:105-147 (handler)

  The getCreditBalance async method that executes the credit balance tool logic. It makes an API request to /credits/balance, formats the response with available/total/locked credits and recent transactions, and returns it as formatted MCP text content.

  async getCreditBalance(args) {
    try {
      const { includeTransactions = true, transactionLimit = 10 } = args;
      
      const params = new URLSearchParams();
      if (includeTransactions) {
        params.append('includeTransactions', 'true');
        params.append('transactionLimit', transactionLimit.toString());
      }
  
      const response = await this.baseUtils.makeApiRequest(`/credits/balance?${params}`);
      const data = response.data;
  
      let result = `💰 **Credit Balance Summary**\n\n`;
      result += `**Available Credits:** ${data.balance.availableCredits} credits\n`;
      result += `**Total Earned:** ${data.balance.totalCredits} credits\n`;
      result += `**Locked Credits:** ${data.balance.lockedCredits} credits\n\n`;
  
      if (includeTransactions && data.recentTransactions?.length > 0) {
        result += `📊 **Recent Transactions** (Last ${data.recentTransactions.length})\n\n`;
        
        data.recentTransactions.forEach((tx, index) => {
          const sign = ['BONUS', 'COMMISSION', 'PURCHASE', 'REFUND'].includes(tx.type) ? '+' : '';
          const emoji = this.getTransactionEmoji(tx.type);
          const date = new Date(tx.createdAt).toLocaleDateString();
          
          result += `${index + 1}. ${emoji} **${tx.type}** ${sign}${tx.amount} credits\n`;
          result += `   ${tx.description}\n`;
          result += `   *${date}*\n\n`;
        });
      }
  
      result += `\n**💡 Earning Tips:**\n`;
      result += `• Write detailed, helpful reviews to earn bonus credits\n`;
      result += `• Publish high-quality papers that attract views and citations\n`;
      result += `• Get your papers published externally for significant bonuses\n`;
      result += `• Use \`get_earning_opportunities\` for personalized suggestions`;
  
      return this.baseUtils.formatResponse(result);
    } catch (error) {
      throw new McpError(ErrorCode.InternalError, `Failed to get credit balance: ${error.message}`);
    }
  }

• src/tools/credits/index.js:15-32 (schema)

  Input schema definition for get_credit_balance tool - defines optional parameters includeTransactions (boolean) and transactionLimit (number, max 50).

  return [
    {
      name: "get_credit_balance",
      description: "Get current credit balance and recent transaction history",
      inputSchema: {
        type: "object",
        properties: {
          includeTransactions: {
            type: "boolean",
            description: "Include recent transaction history (default: true)"
          },
          transactionLimit: {
            type: "number",
            description: "Number of recent transactions to include (default: 10, max: 50)"
          }
        }
      }
    },

• src/tools/credits/index.js:96-103 (registration)

  Registration of get_credit_balance handler in the getToolHandlers method, mapping the tool name to the bound getCreditBalance method.

  getToolHandlers() {
    return {
      get_credit_balance: this.getCreditBalance.bind(this),
      pay_with_credits: this.payWithCredits.bind(this), 
      get_earning_opportunities: this.getEarningOpportunities.bind(this),
      verify_external_publication: this.verifyExternalPublication.bind(this)
    };
  }

• src/server-static.js:62-76 (registration)

  Static registration of the CreditsModule in server-static.js - the CreditsTools class is instantiated and its getToolDefinitions/getToolHandlers are called to register all credit tools including get_credit_balance.

    { name: 'marketplace', Class: MarketplaceModule },
    { name: 'users', Class: UsersModule },
    { name: 'auth', Class: AuthModule },
    { name: 'platform', Class: PlatformModule },
    { name: 'credits', Class: CreditsModule }
  ];
  
  for (const { name, Class } of modules) {
    try {
      const instance = new Class();
      const tools = instance.getToolDefinitions();
      const handlers = instance.getToolHandlers();
  
      this.tools.push(...tools);
      Object.assign(this.handlers, handlers);

• src/tools/credits/index.js:95-103 (registration)

  CreditsTools.getToolHandlers() returns a mapping object where 'get_credit_balance' is bound to this.getCreditBalance, making it available for the server to dispatch calls to.

  // Get tool handlers mapping
  getToolHandlers() {
    return {
      get_credit_balance: this.getCreditBalance.bind(this),
      pay_with_credits: this.payWithCredits.bind(this), 
      get_earning_opportunities: this.getEarningOpportunities.bind(this),
      verify_external_publication: this.verifyExternalPublication.bind(this)
    };
  }