url_analytics
Analyze click statistics for shortened URLs within specific timeframes, providing insights into performance and usage trends.
Instructions
Get detailed click analytics for a shortened URL within a date range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | The time period for analytics (e.g., "day", "week", "month") | |
| shorturl | Yes | The short URL to get analytics for |
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 );