YOURLS-MCP

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

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

Обзор

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

Related MCP server: MCP Tools

Функции

• Сократите 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 (после создания репозитория)