YOURLS-MCP

Instructions

Implementation Reference

• src/tools/deleteUrl.js:13-93 (handler)

  The createDeleteUrlTool factory function that returns the MCP tool object for 'delete_url', including the execute handler that performs the deletion using yourlsClient.deleteUrl with fallback handling and response formatting.

  export default function createDeleteUrlTool(yourlsClient) {
    return {
      name: 'delete_url',
      description: 'Delete a short URL',
      inputSchema: {
        type: 'object',
        properties: {
          shorturl: {
            type: 'string',
            description: 'The short URL or keyword to delete'
          }
        },
        required: ['shorturl']
      },
      execute: async ({ shorturl }) => {
        try {
          // Use the deleteUrl method with fallback enabled
          const result = await yourlsClient.deleteUrl(shorturl, true);
          
          if (result.status === 'success' || result.message === 'success: deleted') {
            const responseData = {
              shorturl: shorturl,
              message: result.message || result.simple || 'Short URL deleted successfully'
            };
            
            // Add fallback information if applicable
            if (result.fallback_used) {
              responseData.fallback_used = true;
              if (result.fallback_limited) {
                responseData.fallback_limited = true;
                
                // Special handling for the limited delete fallback
                if (result.status === 'info') {
                  return {
                    content: [
                      {
                        type: 'text',
                        text: JSON.stringify({
                          status: 'info',
                          shorturl: shorturl,
                          message: result.message,
                          code: result.code || 'not_supported',
                          fallback_used: true,
                          fallback_limited: true
                        })
                      }
                    ]
                  };
                }
              }
            }
            
            return createMcpResponse(true, responseData);
          } else if (result.status === 'info') {
            // Special handling for the info status (fallback limitation)
            return {
              content: [
                {
                  type: 'text',
                  text: JSON.stringify({
                    status: 'info',
                    shorturl: shorturl,
                    message: result.message,
                    fallback_used: result.fallback_used,
                    fallback_limited: result.fallback_limited
                  })
                }
              ]
            };
          } else {
            throw new Error(result.message || 'Unknown error');
          }
        } catch (error) {
          return createMcpResponse(false, {
            message: error.message,
            shorturl: shorturl
          });
        }
      }
    };
  }

• src/index.js:220-227 (registration)

  Registration of the delete_url tool on the MCP server using server.tool(), providing name, description, input schema (zod), and execute function reference.

  server.tool(
    deleteUrlTool.name,
    deleteUrlTool.description,
    {
      shorturl: z.string().describe('The short URL or keyword to delete')
    },
    deleteUrlTool.execute
  );

• src/tools/deleteUrl.js:17-26 (schema)

  JSON schema definition for the delete_url tool input parameters within the tool factory.

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

• src/api.js:875-901 (helper)

  The YourlsClient.deleteUrl method, called by the tool handler, which checks for the API Delete plugin availability and provides fallback response explaining limitations.

  async deleteUrl(shorturl, useNativeFallback = true) {
    try {
      // First check if the plugin is available
      const isAvailable = await isPluginAvailable(this, 'delete', 'delete', { shorturl: 'test' });
      
      if (isAvailable) {
        return this.request('delete', { shorturl });
      } else if (useNativeFallback) {
        // Use our fallback implementation with admin interface emulation
        return this._deleteUrlFallback(shorturl);
      } else {
        throw new Error('The delete action is not available. Please install the API Delete 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._deleteUrlFallback(shorturl);
      } else {
        throw new Error('The delete action is not available. Please install the API Delete plugin.');
      }
    }
  }