YOURLS-MCP

Instructions

Implementation Reference

• src/tools/getUrlKeyword.js:31-76 (handler)

  The execute handler function that implements the core logic of the 'get_url_keyword' tool, processing input, calling the YOURLS client, and formatting the response.
  execute: async ({ url, exactly_one = true }) => { try { // Normalize boolean parameter if it's passed as a string if (typeof exactly_one === 'string') { exactly_one = exactly_one.toLowerCase() === 'true'; } // Use the getUrlKeyword method with fallback enabled const result = await yourlsClient.getUrlKeyword(url, exactly_one, true); if (result.status === 'success' || result.message === 'success: found') { const responseData = { url: url }; // Add keyword information based on response format if (exactly_one && result.keyword) { responseData.keyword = result.keyword; if (result.shorturl) responseData.shorturl = result.shorturl; if (result.title) responseData.title = result.title; } else if (!exactly_one && result.keywords) { responseData.keywords = result.keywords; } // Add message if available if (result.simple) responseData.message = result.simple; // Add fallback information if applicable if (result.fallback_used) { responseData.fallback_used = true; if (result.fallback_limitations) { responseData.fallback_limitations = result.fallback_limitations; } } return createMcpResponse(true, responseData); } else { throw new Error(result.message || 'Unknown error'); } } catch (error) { return createMcpResponse(false, { message: error.message, url: url }); } }
• src/tools/getUrlKeyword.js:17-30 (schema)

  Input schema definition for the 'get_url_keyword' tool parameters.
  inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'The long URL to look up' }, exactly_one: { type: 'boolean', description: 'If false, returns all keywords for this URL (default: true)' } }, required: ['url'] },
• src/index.js:211-217 (registration)

  Registration of the 'get_url_keyword' tool with the MCP server, including Zod schema conversion and binding the execute handler.
  getUrlKeywordTool.name, getUrlKeywordTool.description, { url: z.string().describe('The URL to find keywords for'), exactly_one: z.boolean().optional().describe('Whether to return only one result (default: false)') }, getUrlKeywordTool.execute
• src/api.js:744-775 (helper)

  The YourlsClient.getUrlKeyword method called by the tool handler, with plugin detection and fallback logic.
  async getUrlKeyword(url, exactlyOne = true, useNativeFallback = true) { const params = { url }; if (!exactlyOne) { params.exactly_one = 'false'; } try { // First check if the plugin is available const isAvailable = await isPluginAvailable(this, 'edit_url', 'geturl', { url: 'https://example.com' }); if (isAvailable) { return this.request('geturl', params); } else if (useNativeFallback) { // Use our fallback implementation return this._getUrlKeywordFallback(url, exactlyOne); } else { throw new Error('The geturl action is not available. Please install the API Edit URL plugin.'); } } catch (error) { // If the error is not about a missing plugin, re-throw it if (!isPluginMissingError(error)) { throw error; } // If we're here, the plugin is missing and we need to use the fallback if (useNativeFallback) { return this._getUrlKeywordFallback(url, exactlyOne); } else { throw new Error('The geturl action is not available. Please install the API Edit URL plugin.'); } }
• src/api.js:786-866 (helper)

  Fallback implementation _getUrlKeywordFallback used when the API Edit URL plugin is unavailable, searches via stats API.
  async _getUrlKeywordFallback(url, exactlyOne) { try { // Safety limit to prevent performance issues const MAX_RESULTS = 1000; // We can try to use the stats action with a filter const listResult = await this.request('stats', { limit: MAX_RESULTS, filter: 'url', search: encodeURIComponent(url) }); // Process the results to match the geturl plugin's output format const keywords = []; let urlExists = false; if (listResult.links) { // Iterate through the results and find exact URL matches for (const [keyword, data] of Object.entries(listResult.links)) { if (data.url === url) { urlExists = true; keywords.push({ keyword: keyword, shorturl: `${this.api_url.replace('yourls-api.php', '')}${keyword}`, title: data.title, url: data.url, date: data.timestamp, ip: data.ip, clicks: data.clicks }); // If we only want one result and we found it, break if (exactlyOne) { break; } } } } // Format the response similarly to what the geturl plugin would return if (urlExists) { if (exactlyOne && keywords.length > 0) { // Return just the first match return { status: 'success', keyword: keywords[0].keyword, url: keywords[0].url, title: keywords[0].title, shorturl: keywords[0].shorturl, message: 'success', ...createFallbackInfo('Search limited to latest URLs', false, 'API Edit URL') }; } else { // Return all matches return { status: 'success', keywords: keywords, url: url, message: 'success', ...createFallbackInfo('Search limited to latest URLs', false, 'API Edit URL') }; } } else { // No matches found return { status: 'fail', message: 'URL not found', ...createFallbackInfo('Search limited to latest URLs', false, 'API Edit URL') }; } } catch (error) { console.error('Get URL keyword fallback error:', error.message); // In case of fallback failure, return a safe default return { status: 'fail', message: 'Error looking up URL: ' + error.message, ...createFallbackInfo('Error during fallback search', true, 'API Edit URL') }; } }