YOURLS-MCP

YOURLS-MCP

Un servidor de Protocolo de Control de Modelos (MCP) para integrar el acortamiento de URL YOURLS con Claude Desktop.

Autor: Martin Kessler

Descripción general

YOURLS-MCP crea un puente entre Claude Desktop y su instancia de acortador de URL YOURLS alojada por usted mismo. Al configurarlo, permite a Claude acortar URL automáticamente usando su instalación personal de YOURLS.

Características

• Acortar URL usando su instancia YOURLS
• Crea URL cortas personalizadas con palabras clave específicas
• Manejo de URL duplicadas: crea múltiples URL cortas para la misma URL de destino (exclusiva de YOURLS-MCP)
• Información y estadísticas de URL ampliadas
• Estadísticas de la base de datos
• Respaldos inteligentes para complementos
• Documentación completa y herramientas de prueba

Inicio rápido

Instalación

Configuración

Cree un archivo de configuración de Claude Desktop que apunte a su instalación de YOURLS-MCP:

Guarde este archivo en el directorio de configuración de Claude Desktop, que normalmente es:

• macOS: ~/Library/Application Support/Claude/config.json
• Ventanas: %APPDATA%\Claude\config.json
• Linux: ~/.config/Claude/config.json

Características

• Integración perfecta con Claude Desktop a través de MCP
• Acortar URL directamente a través de Claude
• Expandir URL acortadas para ver su destino
• Recupere estadísticas de clics para sus enlaces
• Compatibilidad con palabras clave personalizadas
• Autenticación segura basada en firma
• Configuración de variables de entorno

Opciones de configuración

Las siguientes variables de entorno se pueden configurar en la configuración de Claude Desktop:

Herramientas MCP disponibles

YOURLS-MCP proporciona las siguientes herramientas a Claude:

Herramientas principales

1. acortar_url

Acorta una URL larga usando su instancia YOURLS.

Parámetros:

• url (obligatorio): La URL larga para acortar
• keyword (opcional): Palabra clave personalizada para la URL corta
• title (opcional): Título para la URL

2. expandir_url

Expande una URL corta para obtener la URL larga original.

Parámetros:

• shorturl (obligatorio): La URL corta o palabra clave para expandir

3. estadísticas de URL

Obtiene estadísticas para una URL acortada.

Parámetros:

• shorturl (obligatorio): La URL corta o palabra clave para obtener estadísticas

4. estadísticas de base de datos

Obtiene estadísticas globales para su instancia YOURLS.

Parámetros: Ninguno

5. crear_url_personalizada

Crea una URL corta personalizada con una palabra clave específica, incluso para URL que ya existen en la base de datos.

Parámetros:

• url (obligatorio): La URL de destino para acortar
• keyword (obligatoria): La palabra clave personalizada para la URL corta (por ejemplo, "web" para bysha.pe/web)
• title (opcional): Título para la URL
• bypass_shortshort (opcional): si se debe omitir el complemento ShortShort que evita acortar URL ya acortadas (valor predeterminado: falso)
• force_url_modification (opcional): si se debe forzar el uso del enfoque de modificación de URL para crear múltiples URL cortas para el mismo destino (predeterminado: falso)

6. acortar_con_analítica

Acorta una URL larga con parámetros UTM de Google Analytics.

Parámetros:

• url (obligatorio): La URL para acortar
• source (obligatorio): parámetro de fuente UTM: identifica la fuente del tráfico (por ejemplo, "google", "newsletter", "twitter")
• medium (obligatorio): parámetro de medio UTM: identifica el medio de marketing (por ejemplo, "cpc", "social", "correo electrónico")
• campaign (obligatorio): parámetro de campaña UTM: identifica la campaña específica (p. ej., "summer_sale", "product_launch")
• term (opcional): parámetro de término UTM: identifica términos de búsqueda pagados
• content (opcional): parámetro de contenido UTM: diferencia anuncios o enlaces que apuntan a la misma URL
• keyword (opcional): Palabra clave personalizada para la URL corta
• title (opcional): Título para la URL

Herramientas basadas en complementos

7. análisis de URL

Obtiene análisis detallados de clics para una URL corta dentro de un rango de fechas. Requiere la instalación del complemento API ShortURL Analytics.

Parámetros:

• shorturl (obligatorio): La URL corta o palabra clave para obtener análisis
• date (obligatoria): Fecha de inicio del análisis en formato AAAA-MM-DD
• date_end (opcional): fecha de finalización del análisis en formato AAAA-MM-DD (la fecha de inicio es la predeterminada si no se proporciona)

8. URL del contrato

Comprueba si una URL ya se ha acortado sin crear una nueva. Requiere la instalación del complemento API Contract.

Parámetros:

• url (obligatorio): La URL para comprobar si se ha acortado

9. actualización_url

Actualizar una URL corta existente para que apunte a una URL de destino diferente. Requiere la instalación del complemento API Edit URL.

Parámetros:

• shorturl (obligatorio): La URL corta o palabra clave para actualizar
• url (obligatorio): La nueva URL de destino
• title (opcional): nuevo título opcional ("keep" para mantener el existente, "auto" para obtenerlo de la URL)

10. cambiar_palabra_clave

Cambiar la palabra clave de una URL corta existente. Requiere la instalación del complemento API Edit URL.

Parámetros:

• oldshorturl (obligatorio): La URL corta o palabra clave existente
• newshorturl (obligatorio): La nueva palabra clave a utilizar
• url (opcional): URL opcional (si no se proporciona, se utilizará la URL de oldshorturl)
• title (opcional): nuevo título opcional ("keep" para mantener el existente, "auto" para obtenerlo de la URL)

11. obtener_url_palabra_clave

Obtener las palabras clave para una URL larga. Requiere la instalación del complemento API Edit URL.

Parámetros:

• url (obligatorio): La URL larga para buscar
• exactly_one (opcional): si es falso, devuelve todas las palabras clave para esta URL (predeterminado: verdadero)

12. eliminar_url

Eliminar una URL corta. Requiere la instalación del complemento API Delete.

Parámetros:

• shorturl (obligatorio): La URL corta o palabra clave a eliminar

13. lista_urls

Obtén una lista de URL con opciones de ordenación, paginación y filtrado. Requiere la instalación del complemento API List Extended.

Parámetros:

• sortby (opcional): Campo para ordenar por (palabra clave, URL, título, IP, marca de tiempo, clics) (predeterminado: marca de tiempo)
• sortorder (opcional): orden de clasificación (ASC o DESC) (predeterminado: DESC)
• offset (opcional): desplazamiento de paginación (predeterminado: 0)
• perpage (opcional): Número de resultados por página (predeterminado: 50)
• query (opcional): consulta de búsqueda opcional para filtrar por palabra clave
• fields (opcional): Campos a devolver (palabra clave, URL, título, marca de tiempo, IP, clics) (predeterminado: todos los campos)

14. generar_código_qr

Genera un código QR para una URL acortada. Requiere la instalación del complemento YOURLS-IQRCodes.

Parámetros:

• shorturl (obligatorio): La URL corta o palabra clave para generar un código QR
• size (opcional): tamaño del código QR en píxeles
• border (opcional): Ancho del borde alrededor del código QR
• ecc (opcional): Nivel de corrección de errores: L (bajo), M (medio), Q (cuartil) o H (alto)
• format (opcional): Formato de imagen (png, jpg, SVG, etc.)

Ejemplos de uso

Una vez configurado, Claude podrá utilizar las herramientas YOURLS con indicaciones como:

Ejemplos de funciones principales

• Acorta esta URL: https://ejemplo.com/url-muy-larga-que-necesita-acortarse
• "Crea una URL corta con la palabra clave 'docs' para https://example.com/documentation "
• Configurar una URL personalizada en sha.pe/web que apunte a shapescale.com
• Cree una URL corta personalizada para nuestra documentación usando la palabra clave 'docs'.
• "Crear varias palabras clave (docs, docs2, docs3) para la misma URL de documentación"
• Crear una URL corta para nuestra campaña con parámetros de seguimiento UTM
• Acortar esta URL de marketing con el seguimiento de Google Analytics: origen=boletín informativo, medio=correo electrónico, campaña=lanzamiento_de_verano
• Expande esta URL corta: https://tudominio.com/abc
• "¿Cuántos clics tiene mi URL corta https://yourdomain.com/abc ?"
• "Muéstrame las estadísticas de mi instancia YOURLS"

Ejemplos de funciones basadas en complementos

• "Proporcione un análisis detallado de la URL corta 'abc' para enero de 2025"
• Muéstrame las estadísticas de clics en bysha.pe/abc del 01/01/2025 al 31/01/2025
• "¿Cuál fue el tráfico diario de mi web shortURL el mes pasado?"
• "Comprueba si esta URL ya se ha acortado: https://example.com/page "
• "¿Alguien ya ha creado una URL corta para https://example.com/page ?"
• "Actualizar el destino de la URL corta 'docs' para que apunte a https://example.com/new-documentation "
• "Cambiar la dirección de la palabra clave 'docs'"
• "Cambiar el nombre de la URL corta 'docs' a 'documentación'"
• Cambiar la palabra clave de mi URL corta de 'docs' a 'documentación'
• "¿Cuál es la palabra clave para esta URL larga: https://example.com/page ?"
• "Enumere todas las URL cortas para https://example.com/page "
• Eliminar la URL corta 'docs'
• "Eliminar la palabra clave 'docs' de mi instancia YOURLS"
• "Muéstrame las 10 URL cortas más recientes en mi base de datos YOURLS"
• "Enumerar todas las URL cortas ordenadas por número de clics"
• "Buscar URL cortas que contengan 'producto'"
• Generar un código QR para mi URL corta 'docs'
• Crea un código QR para bysha.pe/web
• "Dame un código QR para la página de mi producto con alta corrección de errores"
• Necesito un código QR más grande para la URL corta de la página de destino. Que sea de 300 píxeles.
• Generar un código QR SVG para nuestro enlace de documentación

Desarrollo

Cómo funciona

YOURLS-MCP actúa como un puente entre Claude Desktop y su instancia YOURLS:

1. Claude Desktop inicia el servidor YOURLS-MCP cuando es necesario
2. El servidor lee la configuración de las variables de entorno
3. Cuando Claude invoca una herramienta, el servidor realiza las llamadas API apropiadas a su instancia YOURLS
4. Los resultados se devuelven a Claude en un formato estructurado.

El servidor utiliza el estándar Model Context Protocol (MCP) para comunicarse con Claude Desktop, lo que permite una integración perfecta e interacciones en lenguaje natural con su acortador de URL.

Manejo de URL duplicadas

YOURLS-MCP ofrece una función única para crear múltiples URL cortas para la misma URL de destino, algo que no es compatible de forma nativa con YOURLS. Para obtener información detallada sobre esta función, consulte la documentación sobre el manejo de URL duplicadas .

Se admiten dos enfoques:

1. Enfoque del complemento (recomendado): utiliza el complemento Force Allow Duplicates incluido para crear URL duplicadas verdaderas
2. Enfoque de modificación de URL (alternativa): agrega parámetros de marca de tiempo para que cada URL sea técnicamente única y, al mismo tiempo, preserve la funcionalidad.

El sistema selecciona automáticamente el enfoque apropiado en función de su configuración YOURLS.

Compatibilidad con los complementos YOURLS

YOURLS-MCP está diseñado para funcionar tanto con instalaciones YOURLS estándar como con varios complementos, con alternativas integradas cuando los complementos no están disponibles:

Complementos compatibles con alternativas

YOURLS-MCP incluye alternativas inteligentes para una funcionalidad extendida cuando no se instalan complementos:

• API ShortURL Analytics : para obtener estadísticas de clics detalladas con rangos de fechas
  • Comportamiento de respaldo : proporciona estadísticas de clics básicas a través de la API principal YOURLS cuando el complemento no está disponible
• Contrato API : para comprobar si existen URL sin crearlas
  • Comportamiento alternativo : utiliza la API de estadísticas principal de YOURLS para buscar URL existentes con filtrado
• API Editar URL : para actualizar URL cortas y cambiar palabras clave
  • Comportamiento de respaldo :
    • Para actualizar las URL: intenta recrear la URL con la misma palabra clave
    • Para cambiar palabras clave: crea una nueva URL corta con la nueva palabra clave (la anterior permanece, ya que la eliminación requiere el complemento API Delete)
    • Para obtener palabras clave de URL: utiliza la API de estadísticas principal YOURLS con filtrado
• API Delete : para eliminar URL cortas
  • Comportamiento alternativo : Limitado: proporciona información de que la eliminación requiere el complemento, ya que la API principal de YOURLS no admite la eliminación
• Lista de API extendida : para una lista de URL mejorada con clasificación y filtrado
  • Comportamiento de respaldo : utiliza la API de estadísticas principal YOURLS con ordenamiento y paginación del lado del cliente
• YOURLS-IQRCodes : Para generar códigos QR a partir de URL cortas
  • Comportamiento alternativo : Ninguno (requiere que el complemento esté instalado)
• ShortShort : maneja adecuadamente el error al intentar acortar una URL ya acortada
  • Compatibilidad : el manejo de errores funciona independientemente de si el complemento está instalado
• Permitir URL existentes : modifica la forma en que YOURLS maneja las URL duplicadas
  • URL del complemento : https://github.com/elder-oss/yourls-allow-existing-urls
  • Nota : Este complemento cambia las respuestas de error a respuestas exitosas, pero en realidad no crea nuevas URL cortas para las URL de destino existentes.
  • Nuestra solución : YOURLS-MCP implementa un enfoque de modificación de URL que agrega un parámetro de marca de tiempo para hacer que las URL sean únicas en la base de datos y al mismo tiempo preservar la experiencia del usuario.
  • Instalación : Opcional: nuestro enfoque de modificación de URL funciona con o sin este complemento instalado
• Permitir duplicados : permite crear múltiples URL cortas para la misma URL de destino.
  • Repositorio de complementos : https://github.com/kesslerio/yourls-force-allow-duplicates (próximamente)
  • Descripción : Complemento personalizado que omite la restricción de URL única de YOURLS
  • Uso : Agregue force=1 a sus solicitudes de API o use force_url_modification=false con la herramienta create_custom_url
  • Instalación :
    1. Descargar desde el repositorio de complementos
    2. Copie la force-allow-duplicates a su directorio YOURLS/user/plugins/
    3. Active el complemento en su interfaz de administración de YOURLS

Mecanismo de respaldo

Cuando se utiliza una función dependiente del complemento pero el complemento no está instalado, YOURLS-MCP:

1. Detecta automáticamente los complementos que faltan
2. Proporciona una funcionalidad de respaldo adecuada cuando sea posible
3. Incluye un atributo fallback_used: true en las respuestas cuando se activan los respaldos
4. Agrega información fallback_limitations cuando el respaldo tiene una funcionalidad reducida
5. Para operaciones completamente no admitidas, devuelve mensajes de error informativos

Este enfoque garantiza que YOURLS-MCP funcione con tantas instalaciones de YOURLS como sea posible y, al mismo tiempo, proporciona información clara sobre la funcionalidad mejorada disponible con los complementos.

Desarrollo y pruebas

Scripts de prueba

El proyecto incluye varios scripts de prueba en el directorio tests/integration/ :

• Pruebas de acortamiento de URL :
  • test-custom-url.js : Prueba la creación de URL personalizadas con palabras clave específicas
  • test-url-modification.js : Prueba el enfoque de modificación de URL para manejar URL duplicadas
  • test-plugin-behavior.js : prueba el comportamiento del complemento Permitir URL existentes
• Pruebas de complementos :
  • test-duplicate-urls.js : Prueba la creación de URL duplicadas con diferentes palabras clave
  • test-plugin-approach.js : Prueba el enfoque directo del complemento para manejar duplicados
• Ejecución de pruebas :
  # Run a specific test node tests/integration/test-custom-url.js

Scripts de utilidad

El directorio scripts/ contiene scripts de utilidad para operaciones comunes:

• create-random.js : crea una URL corta aleatoria para un destino específico
• Otros scripts para tareas específicas de creación de URL

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Acerca de

YOURLS-MCP fue creado por Martin Kessler para integrar YOURLS con Claude Desktop y otras ofertas de Claude a través del Protocolo de contexto de modelo (MCP).

El complemento Force Allow Duplicates se desarrolló para resolver el desafío de crear múltiples URL cortas para el mismo destino, algo que no es compatible de forma nativa con YOURLS.

Para soporte, problemas o solicitudes de funciones:

• YOURLS-MCP: https://github.com/kesslerio/yourls-mcp/issues
• Complemento Forzar permiso de duplicados: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (una vez creado el repositorio)