YOURLS-MCP

Instructions

Implementation Reference

• src/tools/urlStats.js:26-48 (handler)

  The execute function that implements the core logic of the 'url_stats' MCP tool. It calls yourlsClient.urlStats(shorturl), processes the result, and returns a standardized MCP response using createMcpResponse.

  execute: async ({ shorturl }) => {
    try {
      const result = await yourlsClient.urlStats(shorturl);
      
      if (result.link) {
        return createMcpResponse(true, {
          shorturl: result.shorturl || shorturl,
          clicks: result.link.clicks || 0,
          title: result.link.title || '',
          longurl: result.link.url || ''
        });
      } else {
        return createMcpResponse(false, {
          message: result.message || 'Unknown error',
          code: result.code || 'unknown'
        });
      }
    } catch (error) {
      return createMcpResponse(false, {
        message: error.message
      });
    }
  }

• src/tools/urlStats.js:16-25 (schema)

  JSON Schema definition for the input parameters of the 'url_stats' tool, specifying that 'shorturl' is a required string.

  inputSchema: {
    type: 'object',
    properties: {
      shorturl: {
        type: 'string',
        description: 'The short URL or keyword to get stats for'
      }
    },
    required: ['shorturl']
  },

• src/index.js:153-159 (registration)

  Registers the 'url_stats' tool with the MCP server using server.tool(), providing the name, description, Zod input schema validation, and the execute handler reference.

    urlStatsTool.name,
    urlStatsTool.description,
    {
      shorturl: z.string().describe('The short URL or keyword to get stats for')
    },
    urlStatsTool.execute
  );

• src/api.js:377-379 (helper)

  The YourlsClient.urlStats method, a supporting utility that makes the underlying 'url-stats' API request to the YOURLS server, used by the tool handler.

  async urlStats(shorturl) {
    return this.request('url-stats', { shorturl });
  }

• src/tools/index.js:104-113 (registration)

  Alternative registration of the 'url_stats' tool in the tools index module (potentially unused), dynamically generating Zod schema from inputSchema.

  server.tool(
    urlStatsTool.name,
    urlStatsTool.description,
    {
      shorturl: urlStatsTool.inputSchema.properties.shorturl.description ? 
               z.string().describe(urlStatsTool.inputSchema.properties.shorturl.description) : 
               z.string()
    },
    urlStatsTool.execute
  );