YOURLS-MCP

Instructions

Implementation Reference

• src/tools/changeKeyword.js:39-74 (handler)

  The execute function implementing the change_keyword tool logic: validates input implicitly via schema, calls yourlsClient.changeKeyword with fallback, processes response, handles errors.
  execute: async ({ oldshorturl, newshorturl, url, title }) => { try { // Use the changeKeyword method with fallback enabled const result = await yourlsClient.changeKeyword(oldshorturl, newshorturl, url, title, true); if (result.status === 'success' || result.message === 'success: updated' || result.statusCode === 200) { const responseData = { message: result.message || result.simple || `Keyword changed from '${oldshorturl}' to '${newshorturl}'`, oldshorturl: oldshorturl, newshorturl: newshorturl, shorturl: result.shorturl }; // Add fallback information if applicable if (result.fallback_used) { responseData.fallback_used = true; if (result.fallback_limited) { responseData.fallback_limited = 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, oldshorturl: oldshorturl, newshorturl: newshorturl }); } }
• src/tools/changeKeyword.js:17-38 (schema)

  Input schema defining parameters for the change_keyword tool.
  inputSchema: { type: 'object', properties: { oldshorturl: { type: 'string', description: 'The existing short URL or keyword' }, newshorturl: { type: 'string', description: 'The new keyword to use' }, url: { type: 'string', description: 'Optional URL (if not provided, will use the URL from oldshorturl)' }, title: { type: 'string', description: 'Optional new title ("keep" to keep existing, "auto" to fetch from URL)' } }, required: ['oldshorturl', 'newshorturl'] },
• src/index.js:199-208 (registration)

  MCP server registration of the change_keyword tool, providing Zod schema and execute handler.
  server.tool( changeKeywordTool.name, changeKeywordTool.description, { oldshorturl: z.string().describe('The existing short URL or keyword'), newshorturl: z.string().describe('The new keyword to use'), title: z.string().optional().describe('Optional new title') }, changeKeywordTool.execute );
• src/api.js:624-666 (helper)

  YourlsClient.changeKeyword helper method: checks for API Edit URL plugin availability, makes 'change_keyword' API request, or falls back to _changeKeywordFallback.
  async changeKeyword(oldshorturl, newshorturl, url = null, title = null, useNativeFallback = true) { const params = { oldshorturl, newshorturl }; if (url) { params.url = url; } if (title) { params.title = title; } try { // First check if the plugin is available const isAvailable = await isPluginAvailable(this, 'edit_url', 'change_keyword', { oldshorturl: 'test', newshorturl: 'test2' }); if (isAvailable) { return this.request('change_keyword', params); } else if (useNativeFallback) { // Use our fallback implementation return this._changeKeywordFallback(oldshorturl, newshorturl, url, title); } else { throw new Error('The change_keyword 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._changeKeywordFallback(oldshorturl, newshorturl, url, title); } else { throw new Error('The change_keyword action is not available. Please install the API Edit URL plugin.'); } } }
• src/api.js:678-734 (helper)

  Fallback implementation when API Edit URL plugin unavailable: expands oldshorturl, creates new shorturl with new keyword (keeping URL/title), notes limitation (old keyword remains).
  async _changeKeywordFallback(oldshorturl, newshorturl, url = null, title = null) { try { // First, get the current details for the oldshorturl const currentDetails = await this.expand(oldshorturl); if (!currentDetails || !currentDetails.longurl) { throw new Error(`Short URL '${oldshorturl}' not found.`); } // Use the provided URL or the one from the current short URL const targetUrl = url || currentDetails.longurl; // Safety check for URL format validateUrl(targetUrl); // Determine the title let targetTitle = ''; if (title === 'keep') { targetTitle = currentDetails.title || ''; } else if (title === 'auto') { targetTitle = ''; // Let YOURLS fetch it from the URL } else if (title) { targetTitle = title; } else { targetTitle = currentDetails.title || ''; } // Create the new shorturl const shortenResult = await this.request('shorturl', { url: targetUrl, keyword: newshorturl, title: targetTitle }); if (shortenResult.status === 'fail') { throw new Error(`Failed to create new keyword: ${shortenResult.message || 'Unknown error'}`); } // Limitation: We can't delete the old shorturl without the Delete plugin const limitations = 'Creates new keyword but cannot delete old one (requires API Delete plugin)'; return { status: 'success', statusCode: 200, message: `Keyword changed (Note: The old keyword '${oldshorturl}' still exists)`, oldshorturl: oldshorturl, newshorturl: newshorturl, shorturl: shortenResult.shorturl, url: targetUrl, title: targetTitle, ...createFallbackInfo(limitations, true, 'API Edit URL and API Delete') }; } catch (error) { console.error('Change keyword fallback error:', error.message); throw error; } }