YOURLS-MCP

YOURLS-MCP

Сервер протокола управления моделью (MCP) для интеграции сокращения URL-адресов YOURLS с Claude Desktop.

Автор: Мартин Кесслер

Обзор

YOURLS-MCP создает мост между Claude Desktop и вашим экземпляром YOURLS URL shortener, размещенным на вашем собственном сервере. После настройки он позволяет Claude автоматически сокращать URL-адреса, используя вашу персональную установку YOURLS.

Функции

• Сократите URL-адреса, используя ваш экземпляр YOURLS
• Создавайте собственные короткие URL-адреса с определенными ключевыми словами
• Обработка дубликатов URL-адресов: создание нескольких коротких URL-адресов для одного и того же целевого URL-адреса (уникально для YOURLS-MCP)
• Расширенная информация и статистика URL
• Статистика базы данных
• Интеллектуальные резервные варианты для плагинов
• Комплексная документация и инструменты тестирования

Быстрый старт

Установка

Конфигурация

Создайте файл конфигурации Claude Desktop, который указывает на вашу установку YOURLS-MCP:

Сохраните этот файл в каталоге конфигурации Claude Desktop, который обычно находится по адресу:

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

Функции

• Полная интеграция с Claude Desktop через MCP
• Сокращайте URL-адреса напрямую через Клода
• Разверните сокращенные URL-адреса, чтобы увидеть их назначение
• Получите статистику кликов по вашим ссылкам
• Поддержка пользовательских ключевых слов
• Безопасная аутентификация на основе подписи
• Конфигурация переменных среды

Параметры конфигурации

В конфигурации Claude Desktop можно задать следующие переменные среды:

Доступные инструменты MCP

YOURLS-MCP предоставляет Клоду следующие инструменты:

Основные инструменты

1. shorten_url

Сокращает длинный URL-адрес, используя ваш экземпляр YOURLS.

Параметры:

• url (обязательно): Длинный URL-адрес для сокращения.
• keyword (необязательно): пользовательское ключевое слово для короткого URL-адреса
• title (необязательно): заголовок URL-адреса.

2. expand_url

Расширяет короткий URL-адрес, чтобы получить исходный длинный URL-адрес.

Параметры:

• shorturl (обязательно): короткий URL или ключевое слово для раскрытия

3. url_stats

Получает статистику для сокращенного URL.

Параметры:

• shorturl (обязательно): короткий URL или ключевое слово для получения статистики

4. db_stats

Получает глобальную статистику для вашего экземпляра YOURLS.

Параметры: Нет

5. создать_пользовательский_url

Создает пользовательский короткий URL-адрес с определенным ключевым словом, даже для URL-адресов, которые уже существуют в базе данных.

Параметры:

• url (обязательно): Целевой URL для сокращения.
• keyword (обязательно): пользовательское ключевое слово для короткого URL (например, «web» для bysha.pe/web)
• title (необязательно): заголовок URL-адреса.
• bypass_shortshort (необязательно): следует ли обходить плагин ShortShort, который предотвращает сокращение уже сокращенных URL-адресов (по умолчанию: false)
• force_url_modification (необязательно): принудительно использовать подход модификации URL для создания нескольких коротких URL-адресов для одного и того же пункта назначения (по умолчанию: false)

6. сократить_с_аналитикой

Сокращает длинный URL-адрес с помощью параметров UTM Google Analytics.

Параметры:

• url (обязательно): URL-адрес для сокращения.
• source (обязательно): параметр источника UTM — определяет источник трафика (например, «google», «newsletter», «twitter»).
• medium (обязательно): параметр UTM medium — определяет маркетинговый канал (например, «cpc», «social», «email»).
• campaign (обязательно): параметр кампании UTM — идентифицирует конкретную кампанию (например, «summer_sale», «product_launch»).
• term (необязательно): параметр термина UTM — определяет платные поисковые термины
• content (необязательно): параметр контента UTM — различает объявления или ссылки, указывающие на один и тот же URL-адрес
• keyword (необязательно): пользовательское ключевое слово для короткого URL-адреса
• title (необязательно): заголовок URL-адреса.

Инструменты на основе плагинов

7. url_analytics

Получает подробную аналитику кликов для короткого URL в диапазоне дат. Требует установки плагина API ShortURL Analytics.

Параметры:

• shorturl (обязательно): короткий URL или ключевое слово для получения аналитики
• date (обязательно): дата начала аналитики в формате ГГГГ-ММ-ДД
• date_end (необязательно): дата окончания аналитики в формате ГГГГ-ММ-ДД (по умолчанию используется дата начала, если не указано иное)

8. URL-адрес_контракта

Проверьте, был ли URL уже сокращен, не создавая новый короткий URL. Требуется установить плагин API Contract.

Параметры:

• url (обязательно): URL-адрес для проверки на предмет сокращения.

9. обновить_url

Обновите существующий короткий URL, чтобы он указывал на другой целевой URL. Требуется установить плагин API Edit URL.

Параметры:

• shorturl (обязательно): короткий URL-адрес или ключевое слово для обновления
• url (обязательно): новый целевой URL
• title (необязательно): Необязательный новый заголовок («keep» для сохранения существующего, «auto» для извлечения из URL)

10. изменить_ключевое_слово

Изменить ключевое слово существующего короткого URL. Требуется установить плагин API Edit URL.

Параметры:

• oldshorturl (обязательно): существующий короткий URL или ключевое слово
• newshorturl (обязательно): новое ключевое слово для использования
• url (необязательно): Необязательный URL (если не указан, будет использован URL из oldshorturl)
• title (необязательно): Необязательный новый заголовок («keep» для сохранения существующего, «auto» для извлечения из URL)

11. получить_url_ключевое_слово

Получить ключевые слова для длинного URL. Требуется установить плагин API Edit URL.

Параметры:

• url (обязательно): Длинный URL для поиска
• exactly_one (необязательно): если false, возвращает все ключевые слова для этого URL (по умолчанию: true)

12. удалить_url

Удалить короткий URL. Требуется установить плагин API Delete.

Параметры:

• shorturl (обязательно): короткий URL-адрес или ключевое слово для удаления.

13. список_urls

Получить список URL-адресов с сортировкой, разбиением на страницы и параметрами фильтрации. Требуется установить плагин API List Extended.

Параметры:

• sortby (необязательно): поле для сортировки (ключевое слово, URL, заголовок, IP, временная метка, клики) (по умолчанию: временная метка)
• sortorder (необязательно): порядок сортировки (по возрастанию или убыванию) (по умолчанию: по убыванию)
• offset (необязательно): смещение пагинации (по умолчанию: 0)
• perpage (необязательно): Количество результатов на страницу (по умолчанию: 50)
• query (необязательно): Необязательный поисковый запрос для фильтрации по ключевому слову
• fields (необязательно): возвращаемые поля (ключевое слово, URL, заголовок, временная метка, IP, клики) (по умолчанию: все поля)

14. сгенерировать_qr_код

Сгенерировать QR-код для сокращенного URL. Требуется установить плагин YOURLS-IQRCodes.

Параметры:

• shorturl (обязательно): короткий URL или ключевое слово для генерации QR-кода
• size (необязательно): размер QR-кода в пикселях
• border (необязательно): Ширина границы вокруг QR-кода.
• ecc (необязательно): Уровень исправления ошибок: L (низкий), M (средний), Q (квартиль) или H (высокий)
• format (необязательно): Формат изображения (png, jpg, svg и т. д.)

Примеры использования

После настройки Клод сможет использовать инструменты YOURLS с такими подсказками:

Примеры основных функций

• "Сократите этот URL для меня: https://example.com/very-long-url-that-needs-shortening "
• "Создайте короткий URL с ключевым словом 'docs' для https://example.com/documentation "
• «Создайте пользовательский URL bysha.pe/web, указывающий на shapescale.com»
• «Создайте собственный короткий URL-адрес для нашей документации, используя ключевое слово „docs“»
• «Создайте несколько ключевых слов (docs, docs2, docs3) для одного и того же URL-адреса документации»
• «Создайте короткий URL-адрес для нашей кампании с параметрами отслеживания UTM»
• «Сократите этот маркетинговый URL с помощью отслеживания Google Analytics: источник=newsletter, канал=email, кампания=summer_launch»
• "Расширьте этот короткий URL: https://yourdomain.com/abc "
• «Сколько кликов у моего короткого URL https://yourdomain.com/abc ?»
• «Покажи мне статистику для моего экземпляра YOURLS»

Примеры функций на основе плагинов

• «Дайте мне подробную аналитику для shorturl 'abc' за январь 2025 года»
• «Покажите мне статистику кликов для bysha.pe/abc с 01.01.2025 по 31.01.2025»
• «Каков был ежедневный трафик моего shortURL 'web' в прошлом месяце?»
• «Проверьте, был ли этот URL-адрес уже сокращен: https://example.com/page »
• «Кто-нибудь уже создал короткий URL для https://example.com/page ?»
• "Обновите назначение короткого URL-адреса 'docs', чтобы он указывал на https://example.com/new-documentation "
• «Измените, куда указывает ключевое слово 'docs'»
• «Переименуйте короткий URL-адрес «docs» в «documentation»»
• «Измените ключевое слово моего короткого URL с «docs» на «documentation»»
• «Какое ключевое слово для этого длинного URL: https://example.com/page ?»
• "Перечислите все короткие URL-адреса для https://example.com/page "
• «Удалить короткий URL 'docs'»
• «Удалить ключевое слово 'docs' из моего экземпляра YOURLS»
• «Покажите мне последние 10 коротких URL-адресов в моей базе данных YOURLS»
• «Список всех коротких URL-адресов, отсортированных по количеству кликов»
• «Поиск коротких URL-адресов, содержащих «продукт»»
• «Сгенерировать QR-код для моего короткого URL-адреса 'docs'»
• «Создать QR-код для bysha.pe/web»
• «Дайте мне QR-код для страницы моего продукта с высоким уровнем коррекции ошибок»
• «Мне нужен QR-код большего размера для короткой ссылки «landing», сделайте его размером 300 пикселей»
• «Сгенерируйте SVG QR-код для ссылки на нашу документацию»

Разработка

Как это работает

YOURLS-MCP действует как мост между Claude Desktop и вашим экземпляром YOURLS:

1. Claude Desktop запускает сервер YOURLS-MCP при необходимости
2. Сервер считывает конфигурацию из переменных среды
3. Когда Клод вызывает инструмент, сервер выполняет соответствующие вызовы API к вашему экземпляру YOURLS.
4. Результаты возвращаются Клоду в структурированном формате.

Для связи с Claude Desktop сервер использует стандарт Model Context Protocol (MCP), что обеспечивает бесперебойную интеграцию и взаимодействие на естественном языке с вашим сокращателем URL-адресов.

Обработка дубликатов URL-адресов

YOURLS-MCP предлагает уникальную возможность создания нескольких коротких URL для одного и того же целевого URL, которая изначально не поддерживается в YOURLS. Подробную информацию об этой функции см. в разделе Duplicate URL Handling Documentation .

Поддерживаются два подхода:

1. Подход с использованием плагина (рекомендуется): использует включенный плагин Force Allow Duplicates для создания настоящих дубликатов URL-адресов.
2. Метод изменения URL-адресов (резервный вариант): добавляет параметры временной метки, чтобы сделать каждый URL-адрес технически уникальным, сохраняя при этом функциональность.

Система автоматически выбирает подходящий подход на основе ваших настроек YOURLS.

Совместимость с плагинами YOURLS

YOURLS-MCP предназначен для работы как со стандартными установками YOURLS, так и с различными плагинами, со встроенными резервными вариантами на случай, если плагины недоступны:

Поддерживаемые плагины с резервными версиями

YOURLS-MCP включает интеллектуальные резервные варианты для расширенной функциональности, когда плагины не установлены:

• API ShortURL Analytics : для подробной статистики кликов с диапазонами дат
  • Резервное поведение : предоставляет базовую статистику кликов через основной API YOURLS, когда плагин недоступен.
• API-контракт : проверка существования URL-адресов без их создания
  • Резервное поведение : использует основной API статистики YOURLS для поиска существующих URL-адресов с фильтрацией.
• API Edit URL : для обновления коротких URL-адресов и изменения ключевых слов.
  • Резервное поведение :
    • Для обновления URL-адресов: попытки заново создать URL-адрес с тем же ключевым словом.
    • Для изменения ключевых слов: создает новый короткий URL с новым ключевым словом (старый остается, так как для удаления требуется плагин API Delete)
    • Для получения ключевых слов URL: использует основной API статистики YOURLS с фильтрацией
• API Delete : для удаления коротких URL-адресов.
  • Резервное поведение : Ограничено — предоставляет информацию о том, что для удаления требуется плагин, так как основной API YOURLS не поддерживает удаление.
• Расширенный список API : для расширенного списка URL с сортировкой и фильтрацией
  • Резервное поведение : использует основной API статистики YOURLS с сортировкой и разбиением на страницы на стороне клиента.
• YOURLS-IQRCodes : для генерации QR-кодов из коротких URL-адресов
  • Резервное поведение : Нет — требуется установка плагина
• ShortShort : правильно обрабатывает ошибку при попытке сократить уже сокращенный URL-адрес.
  • Совместимость : Обработка ошибок работает независимо от того, установлен ли плагин.
• Разрешить существующие URL-адреса : изменяет способ обработки YOURLS дублирующихся URL-адресов.
  • URL плагина : https://github.com/elder-oss/yourls-allow-existing-urls
  • Примечание : этот плагин изменяет ответы об ошибках на ответы об успешном выполнении, но на самом деле не создает новые короткие URL-адреса для существующих целевых URL-адресов.
  • Наше решение : YOURLS-MCP реализует подход к изменению URL-адресов, который добавляет параметр временной метки, чтобы сделать URL-адреса уникальными в базе данных, сохраняя при этом удобство использования.
  • Установка : Необязательно — наш подход к изменению URL-адресов работает как с установленным плагином, так и без него.
• Принудительно разрешать дубликаты : действительно позволяет создавать несколько коротких URL-адресов для одного и того же целевого URL-адреса.
  • Репозиторий плагинов : https://github.com/kesslerio/yourls-force-allow-duplicates (скоро)
  • Описание : Пользовательский плагин, который обходит ограничение уникальности URL YOURLS
  • Использование : добавьте force=1 к вашим запросам API или используйте force_url_modification=false с инструментом create_custom_url
  • Установка :
    1. Загрузить из репозитория плагинов
    2. Скопируйте папку force-allow-duplicates в ваш каталог YOURLS/user/plugins/
    3. Активируйте плагин в интерфейсе администратора YOURLS.

Механизм отката

Когда используется функция, зависящая от плагина, но плагин не установлен, YOURLS-MCP:

1. Автоматически обнаруживает отсутствующие плагины
2. Предоставляет соответствующую резервную функциональность, где это возможно
3. Включает атрибут fallback_used: true в ответах при активации резервных вариантов
4. Добавляет информацию fallback_limitations , когда у резервного варианта ограниченная функциональность.
5. Для полностью неподдерживаемых операций возвращает информативные сообщения об ошибках.

Такой подход гарантирует, что YOURLS-MCP будет работать с максимально возможным количеством установок YOURLS, при этом предоставляя четкую информацию о расширенных функциональных возможностях, доступных с помощью плагинов.

Разработка и тестирование

Тестовые скрипты

Проект включает в себя различные тестовые скрипты в каталоге tests/integration/ :

• Тесты сокращения URL-адресов :
  • test-custom-url.js : Тесты создания пользовательских URL-адресов с определенными ключевыми словами
  • test-url-modification.js : Тестирует подход к модификации URL для обработки дубликатов URL
  • test-plugin-behavior.js : Тестирует поведение плагина Allow Existing URLs
• Тесты плагинов :
  • test-duplicate-urls.js : Тесты создания дубликатов URL-адресов с разными ключевыми словами
  • test-plugin-approach.js : Тестирует прямой подход плагина для обработки дубликатов
• Проведение тестов :
  # Run a specific test node tests/integration/test-custom-url.js

Скрипты утилит

Каталог scripts/ содержит служебные скрипты для общих операций:

• create-random.js : создает случайный короткий URL для указанного места назначения
• Другие скрипты для конкретных задач создания URL

Лицензия

Массачусетский технологический институт

О

YOURLS-MCP был создан Мартином Кесслером для интеграции YOURLS с Claude Desktop и другими предложениями Claude через протокол контекста модели (MCP).

Плагин Force Allow Duplicates был разработан для решения проблемы создания нескольких коротких URL-адресов для одного и того же места назначения, которая изначально не поддерживается в YOURLS.

Для поддержки, решения проблем или запросов функций:

• YOURLS-MCP: https://github.com/kesslerio/yourls-mcp/issues
• Плагин Force Allow Duplicates: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (после создания репозитория)