YOURLS-MCP

유얼스-MCP

YOURLS URL 단축 기능을 Claude Desktop과 통합하기 위한 MCP(모델 제어 프로토콜) 서버입니다.

저자: 마틴 케슬러

개요

YOURLS-MCP는 Claude Desktop 과 자체 호스팅 YOURLS URL 단축기 인스턴스 사이에 브리지를 생성합니다. 이 기능을 구성하면 Claude가 사용자의 개인 YOURLS 설치를 사용하여 URL을 자동으로 단축할 수 있습니다.

특징

• YOURLS 인스턴스를 사용하여 URL을 단축하세요
• 특정 키워드로 사용자 정의 단축 URL을 만듭니다.
• 중복 URL 처리: 동일한 대상 URL에 대해 여러 개의 짧은 URL을 생성합니다(YOURLS-MCP에만 해당)
• 확장된 URL 정보 및 통계
• 데이터베이스 통계
• 플러그인을 위한 지능형 대체
• 포괄적인 문서 및 테스트 도구

빠른 시작

설치

지엑스피1

구성

YOURLS-MCP 설치를 가리키는 Claude Desktop 구성 파일을 만듭니다.

이 파일을 Claude Desktop 구성 디렉토리에 저장합니다. 일반적으로 디렉토리는 다음과 같습니다.

• macOS: ~/Library/Application Support/Claude/config.json
• 윈도우: %APPDATA%\Claude\config.json
• 리눅스: ~/.config/Claude/config.json

특징

• MCP를 통한 Claude Desktop과의 원활한 통합
• Claude를 통해 URL을 직접 단축하세요
• 단축 URL을 확장하여 목적지를 확인하세요.
• 링크에 대한 클릭 통계를 검색하세요
• 사용자 정의 키워드 지원
• 보안 서명 기반 인증
• 환경 변수 구성

구성 옵션

다음 환경 변수는 Claude Desktop 구성에서 설정할 수 있습니다.

사용 가능한 MCP 도구

YOURLS-MCP는 Claude에게 다음과 같은 도구를 제공합니다.

핵심 도구

1. URL을 단축하다

YOURLS 인스턴스를 사용하여 긴 URL을 줄입니다.

매개변수:

• url (필수): 단축할 긴 URL
• keyword (선택 사항): 짧은 URL에 대한 사용자 정의 키워드
• title (선택 사항): URL의 제목

2. 확장_URL

짧은 URL을 확장하여 원래의 긴 URL을 얻습니다.

매개변수:

• shorturl (필수): 확장할 짧은 URL 또는 키워드

3. URL 통계

단축된 URL에 대한 통계를 가져옵니다.

매개변수:

• shorturl (필수): 통계를 얻기 위한 짧은 URL 또는 키워드

4. DB_통계

YOURLS 인스턴스에 대한 글로벌 통계를 가져옵니다.

매개변수: 없음

5. 사용자 정의 URL 생성

데이터베이스에 이미 존재하는 URL에 대해서도 특정 키워드를 사용해 사용자 정의 단축 URL을 생성합니다.

매개변수:

• url (필수): 단축할 대상 URL
• keyword (필수): 짧은 URL에 대한 사용자 정의 키워드(예: bysha.pe/web의 경우 "웹")
• title (선택 사항): URL의 제목
• bypass_shortshort (선택 사항): 이미 단축된 URL을 단축하는 것을 방지하는 ShortShort 플러그인을 우회할지 여부(기본값: false)
• force_url_modification (선택 사항): 동일한 대상에 대해 여러 개의 짧은 URL을 생성하기 위해 URL 수정 방식을 강제로 사용할지 여부(기본값: false)

6. 분석으로 단축

Google Analytics UTM 매개변수를 사용하여 긴 URL을 줄입니다.

매개변수:

• url (필수): 단축할 URL
• source (필수): UTM 소스 매개변수 - 트래픽 소스를 식별합니다(예: "google", "newsletter", "twitter")
• medium (필수): UTM 매체 매개변수 - 마케팅 매체를 식별합니다(예: "cpc", "소셜", "이메일")
• campaign (필수): UTM 캠페인 매개변수 - 특정 캠페인을 식별합니다(예: "summer_sale", "product_launch")
• term (선택 사항): UTM term 매개변수 - 유료 검색어를 식별합니다.
• content (선택 사항): UTM 콘텐츠 매개변수 - 동일한 URL을 가리키는 광고 또는 링크를 구분합니다.
• keyword (선택 사항): 짧은 URL에 대한 사용자 정의 키워드
• title (선택 사항): URL의 제목

플러그인 기반 도구

7. URL 분석

특정 기간 내 단축 URL에 대한 자세한 클릭 분석을 가져옵니다. API ShortURL Analytics 플러그인을 설치해야 합니다.

매개변수:

• shorturl (필수): 분석을 위한 짧은 URL 또는 키워드
• date (필수): YYYY-MM-DD 형식의 분석 시작 날짜
• date_end (선택 사항): YYYY-MM-DD 형식의 분석 종료 날짜(제공되지 않으면 기본적으로 시작 날짜가 사용됨)

8. 계약_URL

새로운 단축 URL을 생성하지 않고 URL이 이미 단축되었는지 확인하세요. API Contract 플러그인을 설치해야 합니다.

매개변수:

• url (필수): 단축되었는지 확인할 URL

9. 업데이트_URL

기존의 짧은 URL을 다른 도착 URL로 업데이트합니다. API URL 편집 플러그인을 설치해야 합니다.

매개변수:

• shorturl (필수): 업데이트할 짧은 URL 또는 키워드
• url (필수): 새로운 목적지 URL
• title (선택 사항): 선택 사항인 새 제목("keep"은 기존 제목 유지, "auto"는 URL에서 가져오기)

10. 키워드 변경

기존 단축 URL의 키워드를 변경합니다. API URL 편집 플러그인을 설치해야 합니다.

매개변수:

• oldshorturl (필수): 기존 단축 URL 또는 키워드
• newshorturl (필수): 사용할 새 키워드
• url (선택 사항): 선택 사항 URL(제공되지 않으면 oldshorturl의 URL을 사용함)
• title (선택 사항): 선택 사항인 새 제목("keep"은 기존 제목 유지, "auto"는 URL에서 가져오기)

11. get_url_keyword

긴 URL에 대한 키워드를 가져옵니다. API URL 편집 플러그인을 설치해야 합니다.

매개변수:

• url (필수): 조회할 긴 URL
• exactly_one (선택 사항): false인 경우 이 URL에 대한 모든 키워드를 반환합니다(기본값: true)

12. URL 삭제

짧은 URL을 삭제합니다. API Delete 플러그인이 설치되어 있어야 합니다.

매개변수:

• shorturl (필수): 삭제할 짧은 URL 또는 키워드

13. 목록_URL

정렬, 페이지 매기기, 필터링 옵션이 포함된 URL 목록을 가져옵니다. API List Extended 플러그인 설치가 필요합니다.

매개변수:

• sortby (선택 사항): 정렬 기준 필드(키워드, URL, 제목, IP, 타임스탬프, 클릭)(기본값: 타임스탬프)
• sortorder (선택 사항): 정렬 순서(ASC 또는 DESC)(기본값: DESC)
• offset (선택 사항): 페이지 번호 오프셋(기본값: 0)
• perpage (선택 사항): 페이지당 결과 수(기본값: 50)
• query (선택 사항): 키워드로 필터링하기 위한 선택적인 검색 쿼리
• fields (선택 사항): 반환할 필드(키워드, URL, 제목, 타임스탬프, IP, 클릭)(기본값: 모든 필드)

14. QR코드 생성

단축 URL의 QR 코드를 생성합니다. YOURLS-IQRCodes 플러그인 설치가 필요합니다.

매개변수:

• shorturl (필수): QR 코드를 생성할 짧은 URL 또는 키워드
• size (선택 사항): 픽셀 단위의 QR 코드 크기
• border (선택 사항): QR 코드 주변의 테두리 너비
• ecc (선택 사항): 오류 수정 수준: L(낮음), M(중간), Q(사분위수), H(높음)
• format (선택 사항): 이미지 형식(png, jpg, svg 등)

사용 예

구성이 완료되면 Claude는 다음과 같은 프롬프트를 통해 YOURLS 도구를 사용할 수 있습니다.

핵심 기능 예시

• "이 URL을 줄여주세요: https://example.com/very-long-url-that-needs-shortening "
• " https://example.com/documentation 에 대해 'docs'라는 키워드를 사용하여 짧은 URL을 만드세요."
• "shapescale.com을 가리키는 bysha.pe/web이라는 사용자 지정 URL을 설정하세요."
• "키워드 'docs'를 사용하여 문서에 대한 사용자 지정 단축 URL을 만듭니다."
• "동일한 문서 URL에 대해 여러 키워드(docs, docs2, docs3)를 만듭니다."
• "UTM 추적 매개변수를 사용하여 캠페인에 대한 짧은 URL을 만드세요"
• "Google 애널리틱스 추적을 사용하여 이 마케팅 URL을 단축하세요: source=newsletter, medium=email, campaign=summer_launch"
• "이 짧은 URL을 확장하세요: https://yourdomain.com/abc "
• "내 짧은 URL https://yourdomain.com/abc는 몇 번이나 클릭되었나요?"
• "내 YOURLS 인스턴스에 대한 통계를 보여주세요"

플러그인 기반 기능 예제

• "2025년 1월의 단축 URL 'abc'에 대한 자세한 분석을 제공해 주세요."
• "2025-01-01부터 2025-01-31까지 bysha.pe/abc에 대한 클릭 통계를 보여주세요"
• "지난달 내 짧은 URL '웹'의 일일 트래픽은 어땠나요?"
• "이 URL이 이미 단축되었는지 확인하세요: https://example.com/page "
• "누군가 https://example.com/page 에 대한 짧은 URL을 이미 만들었나요?"
• "짧은 URL 'docs'의 목적지를 https://example.com/new-documentation 을 가리키도록 업데이트하세요."
• "키워드 'docs'가 가리키는 위치를 변경하세요"
• "짧은 URL 'docs'를 'documentation'으로 이름을 바꾸세요"
• "내 짧은 URL의 키워드를 'docs'에서 'documentation'으로 변경하세요."
• "이 긴 URL인 https://example.com/page 의 키워드는 무엇입니까?"
• " https://example.com/page 에 대한 모든 짧은 URL을 나열하세요"
• "짧은 URL 'docs'를 삭제하세요"
• "내 YOURLS 인스턴스에서 'docs' 키워드를 제거하세요"
• "내 YOURLS 데이터베이스에서 가장 최근의 10개 짧은 URL을 보여주세요"
• "클릭 수 순으로 정렬된 모든 짧은 URL을 나열하세요"
• "'product'를 포함하는 짧은 URL을 검색하세요"
• "내 짧은 URL '문서'에 대한 QR 코드를 생성하세요"
• "bysha.pe/web에 대한 QR 코드를 만드세요"
• "오류 수정률이 높은 제품 페이지의 QR 코드를 보내주세요"
• "랜딩 URL에 더 큰 QR 코드를 넣어주세요. 300픽셀로 만들어주세요."
• "문서 링크에 대한 SVG QR 코드를 생성하세요"

개발

작동 원리

YOURLS-MCP는 Claude Desktop과 YOURLS 인스턴스 간의 브리지 역할을 합니다.

1. Claude Desktop은 필요할 때 YOURLS-MCP 서버를 시작합니다.
2. 서버는 환경 변수에서 구성을 읽습니다.
3. Claude가 도구를 호출하면 서버는 YOURLS 인스턴스에 적절한 API 호출을 수행합니다.
4. 결과는 구조화된 형식으로 Claude에게 반환됩니다.

서버는 Claude Desktop과 통신하기 위해 MCP(Model Context Protocol) 표준을 사용하여 URL 단축기와 원활한 통합과 자연어 상호 작용을 허용합니다.

중복 URL 처리

YOURLS-MCP는 동일한 도착 URL에 대해 여러 개의 단축 URL을 생성할 수 있는 고유한 기능을 제공하지만, YOURLS에서는 기본적으로 지원되지 않습니다. 이 기능에 대한 자세한 내용은 중복 URL 처리 설명서를 참조하세요.

두 가지 접근 방식이 지원됩니다.

1. 플러그인 접근 방식 (권장): 포함된 Force Allow Duplicates 플러그인을 사용하여 실제 중복 URL을 생성합니다.
2. URL 수정 접근 방식 (대체): 기능을 유지하면서 각 URL을 기술적으로 고유하게 만들기 위해 타임스탬프 매개변수를 추가합니다.

시스템은 YOURLS 설정에 따라 자동으로 적절한 접근 방식을 선택합니다.

YOURLS 플러그인과의 호환성

YOURLS-MCP는 표준 YOURLS 설치와 다양한 플러그인 모두에서 작동하도록 설계되었으며, 플러그인을 사용할 수 없는 경우를 대비한 기본 제공 대체 기능이 포함되어 있습니다.

폴백이 있는 지원 플러그인

YOURLS-MCP에는 플러그인이 설치되지 않은 경우 확장된 기능을 위한 지능형 대체 기능이 포함되어 있습니다.

• API ShortURL 분석 : 날짜 범위에 따른 자세한 클릭 통계
  • 대체 동작 : 플러그인을 사용할 수 없을 때 핵심 YOURLS API를 통해 기본 클릭 통계를 제공합니다.
• API 계약 : URL을 생성하지 않고도 URL이 존재하는지 확인하는 방법
  • 대체 동작 : 필터링을 통해 기존 URL을 검색하기 위해 핵심 YOURLS 통계 API를 사용합니다.
• API URL 편집 : 짧은 URL 업데이트 및 키워드 변경
  • 폴백 동작 :
    • URL 업데이트의 경우: 동일한 키워드로 URL을 다시 생성하려고 시도합니다.
    • 키워드 변경: 새 키워드로 새 단축 URL을 생성합니다(삭제에는 API Delete 플러그인이 필요하므로 기존 URL은 그대로 유지됩니다).
    • URL 키워드를 얻으려면: 필터링을 사용하여 핵심 YOURLS 통계 API를 사용합니다.
• API 삭제 : 짧은 URL을 제거하기 위한 API
  • 대체 동작 : 제한됨 - 핵심 YOURLS API가 삭제를 지원하지 않으므로 삭제에는 플러그인이 필요하다는 정보를 제공합니다.
• API 목록 확장 : 정렬 및 필터링을 통한 향상된 URL 목록 제공
  • 대체 동작 : 클라이언트 측 정렬 및 페이지 매김을 통해 핵심 YOURLS 통계 API를 사용합니다.
• YOURLS-IQRCodes : 짧은 URL에서 QR 코드를 생성합니다.
  • 대체 동작 : 없음 - 플러그인을 설치해야 함
• 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 (곧 제공)
  • 설명 : YOURLS의 고유 URL 제약을 우회하는 사용자 정의 플러그인
  • 사용법 : API 요청에 force=1 추가하거나 create_custom_url 도구와 함께 force_url_modification=false 사용하세요.
  • 설치 :
    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 생성 작업을 위한 기타 스크립트

특허

MIT

에 대한

YOURLS-MCP는 Martin Kessler가 Model Context Protocol(MCP)을 통해 YOURLS를 Claude Desktop 및 기타 Claude 제품과 통합하기 위해 만들었습니다.

강제 중복 허용 플러그인은 YOURLS에서 기본적으로 지원되지 않는 동일한 대상에 대해 여러 개의 짧은 URL을 생성하는 과제를 해결하기 위해 개발되었습니다.

지원, 문제 또는 기능 요청:

• YOURLS-MCP: https://github.com/kesslerio/yourls-mcp/issues
• 강제로 중복 허용 플러그인: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (저장소가 생성된 후)