Pinboard MCP 서버

Model Context Protocol(MCP)을 통해 LLM에 Pinboard.in 북마크에 대한 읽기 전용 액세스를 제공합니다.

개요

이 서버는 LLM이 추론 시점에 Pinboard.in에서 북마크 메타데이터를 검색, 필터링 및 가져올 수 있는 기능을 제공합니다. FastMCP 2.0을 기반으로 구축되었으며, Pinboard의 속도 제한을 준수하고 지능형 캐싱을 구현하면서 북마크 상호작용을 위한 4가지 핵심 도구를 제공합니다.

Related MCP server: Raindrop.io MCP Server

기능

• Pinboard 북마크에 대한 읽기 전용 액세스

• 5가지 MCP 도구: search_bookmarks, search_bookmarks_extended, list_recent_bookmarks, list_bookmarks_by_tags, list_tags

• posts/update 엔드포인트를 사용한 LRU 캐시 및 자동 무효화 기능을 갖춘 스마트 캐싱

• API 호출 간 Pinboard의 3초 가이드라인을 준수하는 속도 제한

• Pinboard의 레거시 필드 이름을 직관적인 이름으로 변환하는 필드 매핑 (description→title, extended→notes)

• 통합 테스트 하네스 및 CI 검증을 통한 포괄적인 테스트

설치

pip 사용 (권장)

pip install pinboard-bookmarks-mcp-server

소스에서 설치

git clone https://github.com/rossshannon/pinboard-bookmarks-mcp-server.git
cd pinboard-bookmarks-mcp-server
pip install -e .

빠른 시작

1. https://pinboard.in/settings/password 에서 Pinboard API 토큰을 가져옵니다.

2. 환경 변수를 설정합니다:

   export PINBOARD_TOKEN="username:1234567890ABCDEF"

3. 서버를 시작합니다:

   pinboard-mcp-server

4. 작동 여부를 확인합니다:

   # Test help command (works without token)
   pinboard-mcp-server --help
   
   # Server should show "Starting MCP server" when run with token

Claude Desktop과 함께 사용

Claude Desktop 설정에 다음 구성을 추가하세요:

{
  "mcpServers": {
    "pinboard": {
      "command": "pinboard-mcp-server",
      "env": {
        "PINBOARD_TOKEN": "your-username:your-token-here"
      }
    }
  }
}

사용 가능한 도구

1. search_bookmarks

제목, 메모 및 태그 전체에서 쿼리 문자열로 북마크를 검색합니다. 자동 확장을 통해 최근 항목에 집중합니다.

매개변수:

• query (string): 검색 쿼리

• limit (int, 선택 사항): 최대 결과 수 (기본값: 20, 최대: 100)

예시:

Search for "python testing" bookmarks

2. search_bookmarks_extended

제목, 메모 및 태그 전체에서 포괄적인 과거 결과를 검색하기 위한 확장 검색입니다.

매개변수:

• query (string): 검색 쿼리

• days_back (int, 선택 사항): 검색할 과거 일수 (기본값: 365, 최대: 730)

• limit (int, 선택 사항): 최대 결과 수 (기본값: 100, 최대: 200)

예시:

Search the last 2 years for "kubernetes" bookmarks

3. list_recent_bookmarks

최근 N일 동안 저장된 북마크를 나열합니다.

매개변수:

• days (int, 선택 사항): 과거 조회 일수 (기본값: 7, 최대: 30)

• limit (int, 선택 사항): 최대 결과 수 (기본값: 20, 최대: 100)

예시:

Show me bookmarks from the last 3 days

4. list_bookmarks_by_tags

선택적 날짜 범위를 사용하여 태그별로 필터링된 모든 북마크를 나열합니다. 과거 데이터 액세스에 가장 효율적입니다.

매개변수:

• tags (array): 필터링할 태그 목록 (1-3개 태그)

• from_date (string, 선택 사항): ISO 형식의 시작 날짜 (YYYY-MM-DD)

• to_date (string, 선택 사항): ISO 형식의 종료 날짜 (YYYY-MM-DD)

• limit (int, 선택 사항): 최대 결과 수 (기본값: 100, 최대: 200)

예시:

Find bookmarks tagged with "python" and "api" from January 2024

5. list_tags

사용 횟수와 함께 모든 태그를 나열합니다.

예시:

What are my most used tags?

구성

환경 변수

• PINBOARD_TOKEN (필수): username:token 형식의 Pinboard API 토큰

속도 제한

서버는 Pinboard의 가이드라인을 준수하기 위해 API 호출 간 3초 지연을 자동으로 적용합니다. 캐시된 응답은 즉시 반환됩니다.

캐싱 전략

• 쿼리 캐시: 검색 결과를 위한 1000개 항목의 LRU 캐시

• 북마크 캐시: 1시간 동안 캐시되는 전체 북마크 목록

• 캐시 무효화: posts/update 엔드포인트를 사용하여 변경 사항 감지

• 태그 캐시: 수동으로 새로 고칠 때까지 캐시되는 태그 목록

테스트

이 프로젝트는 여러 테스트 전략을 포함한 포괄적인 테스트 커버리지를 제공합니다:

모든 테스트 실행

# Activate virtual environment first
source ~/.venvs/pinboard-bookmarks-mcp-server/bin/activate

# Run all tests with coverage
pytest --cov=src --cov-report=term-missing

실제 API 테스트

# Set your Pinboard token
export PINBOARD_TOKEN="username:token"

# Run debug utility to test search functionality (development only)
PINBOARD_TOKEN="username:token" python tests/debug_bookmarks.py

모의(Mock) API 테스트

# Run comprehensive test suite (development only)
python -m pytest tests/ -v

개발

설정

# Clone and setup
git clone https://github.com/rossshannon/pinboard-bookmarks-mcp-server.git
cd pinboard-bookmarks-mcp-server

# Quick development setup
./scripts/dev-setup.sh

코드 품질

# Activate environment
source ~/.venvs/pinboard-bookmarks-mcp-server/bin/activate

# Linting and formatting
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/

# Run tests
pytest -v

# Build package
./scripts/build.sh

아키텍처

• FastMCP 2.0: 도구 추상화 및 비동기 FastAPI 서버를 갖춘 MCP 스캐폴딩

• pinboard.py: 오류 처리가 포함된 Pinboard API 클라이언트 래퍼

• Pydantic: JSON 스키마를 사용한 데이터 검증 및 직렬화

• ThreadPoolExecutor: 비동기 MCP와 동기식 pinboard.py 라이브러리를 연결

• LRU Cache: 지능형 무효화 기능을 갖춘 메모리 내 캐싱

주요 파일

• src/pinboard_mcp_server/main.py - MCP 서버 진입점 및 도구 구현

• src/pinboard_mcp_server/client.py - 캐싱 기능이 포함된 Pinboard API 클라이언트

• src/pinboard_mcp_server/models.py - Pydantic 데이터 모델

• tests/ - 포괄적인 테스트 제품군

• tests/debug_bookmarks.py - 검색 기능 테스트를 위한 디버그 유틸리티

• docs/TEST_HARNESS.md - 테스트 하네스 문서

성능

• P50 응답 시간: <250ms (캐시된 응답)

• P95 응답 시간: <600ms (콜드 캐시)

• 속도 제한: API 호출 간 3초 간격

• 캐시 적중률: 일반적인 사용 패턴에서 >90%

보안

• API 토큰은 로그에 기록되거나 오류 메시지에 노출되지 않음

• Pinboard 데이터에 대한 읽기 전용 액세스

• 모든 도구 매개변수에 대한 입력 검증

• 안전한 환경 변수 처리

문제 해결

일반적인 문제

"PINBOARD_TOKEN 환경 변수가 필요합니다"

• 토큰을 설정했는지 확인하세요: export PINBOARD_TOKEN="username:token"

• https://pinboard.in/settings/password 에서 토큰을 가져오세요

• 토큰 형식은 username:1234567890ABCDEF여야 합니다

"명령어를 찾을 수 없음: pinboard-mcp-server"

• 패키지를 설치했는지 확인하세요: pip install pinboard-bookmarks-mcp-server

• Python 환경이 활성화되어 있는지 확인하세요

• 재설치를 시도하세요: pip uninstall pinboard-bookmarks-mcp-server && pip install pinboard-bookmarks-mcp-server

서버는 시작되지만 Claude Desktop이 연결할 수 없음

• Claude Desktop 설정에서 MCP 구성을 확인하세요

• command 경로가 올바른지 확인하세요: pinboard-mcp-server

• env 섹션에 PINBOARD_TOKEN이 설정되어 있는지 확인하세요

"권한 거부(Permission denied)" 또는 "액세스 거부(Access denied)" 오류

• Pinboard 토큰이 유효하고 활성 상태인지 확인하세요

• pinboard.in에 도달할 수 있는 인터넷 연결 상태를 확인하세요

• https://pinboard.in/api/v1/posts/recent 에서 토큰을 수동으로 테스트하세요

기여

1. 저장소를 포크하세요

2. 기능 브랜치를 생성하세요 (git checkout -b feature/amazing-feature)

3. 테스트와 함께 변경 사항을 적용하세요

4. 모든 테스트가 통과하고 코드가 포맷되었는지 확인하세요

5. 풀 리퀘스트를 제출하세요

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.