YOURLS-MCP

Instructions

Implementation Reference

• src/tools/shortUrlAnalytics.js:35-61 (handler)

  The execute function implementing the core logic of the url_analytics tool. It calls the YOURLS API via yourlsClient.shortUrlAnalytics and formats the response using createMcpResponse.

  execute: async ({ shorturl, date, date_end }) => {
    try {
      const result = await yourlsClient.shortUrlAnalytics(shorturl, date, date_end);
      
      if (result.stats) {
        return createMcpResponse(true, {
          shorturl: shorturl,
          total_clicks: result.stats.total_clicks || 0,
          range_clicks: result.stats.range_clicks || 0,
          daily_clicks: result.stats.daily_clicks || {},
          date_range: {
            start: date,
            end: date_end || date
          }
        });
      } else {
        throw new Error(result.message || 'Unknown error');
      }
    } catch (error) {
      return createMcpResponse(false, {
        message: error.message,
        shorturl: shorturl,
        date: date,
        date_end: date_end || date
      });
    }
  }

• src/tools/shortUrlAnalytics.js:17-34 (schema)

  JSON schema defining the input parameters for the url_analytics tool: shorturl (required), date (required), date_end (optional).

  inputSchema: {
    type: 'object',
    properties: {
      shorturl: {
        type: 'string',
        description: 'The short URL or keyword to get analytics for'
      },
      date: {
        type: 'string',
        description: 'Start date for analytics (YYYY-MM-DD format)'
      },
      date_end: {
        type: 'string',
        description: 'Optional end date for analytics (YYYY-MM-DD format). Defaults to start date if not provided.'
      }
    },
    required: ['shorturl', 'date']
  },

• src/index.js:168-177 (registration)

  Registration of the url_analytics tool on the MCP server in the main entry point, using Zod schema adapted for shorturl and period.

  // Register plugin-based tools
  server.tool(
    shortUrlAnalyticsTool.name,
    shortUrlAnalyticsTool.description,
    {
      shorturl: z.string().describe('The short URL to get analytics for'),
      period: z.string().optional().describe('The time period for analytics (e.g., "day", "week", "month")')
    },
    shortUrlAnalyticsTool.execute
  );

• src/api.js:398-419 (helper)

  Helper method in YourlsClient that performs the actual API request to YOURLS 'shorturl_analytics' endpoint, used by the tool handler.

  async shortUrlAnalytics(shorturl, date, dateEnd = null) {
    const params = { 
      shorturl, 
      date 
    };
    
    if (dateEnd) {
      params.date_end = dateEnd;
    }
    
    try {
      return this.request('shorturl_analytics', params);
    } catch (error) {
      // If the plugin isn't installed, we'll get an error about unknown action
      if (isPluginMissingError(error)) {
        throw new Error('The shorturl_analytics action is not available. Please install the API ShortURL Analytics plugin.');
      }
      
      // Otherwise, re-throw the original error
      throw error;
    }
  }

• src/tools/index.js:123-131 (registration)

  Alternative registration of the url_analytics tool in the tools module (may be unused).

  server.tool(
    shortUrlAnalyticsTool.name,
    shortUrlAnalyticsTool.description,
    {
      shorturl: z.string().describe('The short URL to get analytics for'),
      period: z.string().optional().describe('The time period for analytics (e.g., "day", "week", "month")')
    },
    shortUrlAnalyticsTool.execute
  );