Pinboard MCP Server

Доступ только для чтения к закладкам Pinboard.in для LLM через протокол Model Context Protocol (MCP).

Обзор

Этот сервер предоставляет LLM возможность искать, фильтровать и извлекать метаданные закладок из Pinboard.in во время вывода. Построенный на FastMCP 2.0, он предлагает четыре основных инструмента для взаимодействия с закладками, соблюдая ограничения скорости Pinboard и реализуя интеллектуальное кэширование.

Related MCP server: Raindrop.io MCP Server

Функции

• Доступ только для чтения к закладкам Pinboard

• Пять инструментов MCP: search_bookmarks, search_bookmarks_extended, list_recent_bookmarks, list_bookmarks_by_tags, list_tags

• Умное кэширование с использованием LRU-кэша и автоматической инвалидацией через эндпоинт posts/update

• Ограничение скорости (Rate limiting): соблюдает рекомендацию Pinboard о 3-секундной задержке между вызовами API

• Сопоставление полей: преобразует устаревшие имена полей 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. Получите ваш API-токен Pinboard на странице https://pinboard.in/settings/password

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, optional): Максимальное количество результатов (по умолчанию: 20, макс: 100)

Пример:

Search for "python testing" bookmarks

2. search_bookmarks_extended

Расширенный поиск для получения полных исторических результатов по заголовкам, заметкам и тегам.

Параметры:

• query (string): Поисковый запрос

• days_back (int, optional): За сколько дней искать (по умолчанию: 365, макс: 730)

• limit (int, optional): Максимальное количество результатов (по умолчанию: 100, макс: 200)

Пример:

Search the last 2 years for "kubernetes" bookmarks

3. list_recent_bookmarks

Список закладок, сохраненных за последние N дней.

Параметры:

• days (int, optional): Количество дней для поиска (по умолчанию: 7, макс: 30)

• limit (int, optional): Максимальное количество результатов (по умолчанию: 20, макс: 100)

Пример:

Show me bookmarks from the last 3 days

4. list_bookmarks_by_tags

Список ВСЕХ закладок, отфильтрованных по тегам, с опциональным диапазоном дат. Наиболее эффективно для исторического доступа.

Параметры:

• tags (array): Список тегов для фильтрации (1-3 тега)

• from_date (string, optional): Дата начала в формате ISO (YYYY-MM-DD)

• to_date (string, optional): Дата окончания в формате ISO (YYYY-MM-DD)

• limit (int, optional): Максимальное количество результатов (по умолчанию: 100, макс: 200)

Пример:

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

5. list_tags

Список всех тегов с количеством их использования.

Пример:

What are my most used tags?

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

Переменные окружения

• PINBOARD_TOKEN (обязательно): Ваш API-токен Pinboard в формате username:token

Ограничение скорости

Сервер автоматически обеспечивает 3-секундную задержку между вызовами API Pinboard, чтобы соблюдать их рекомендации. Кэшированные ответы возвращаются немедленно.

Стратегия кэширования

• Кэш запросов: LRU-кэш на 1000 записей для результатов поиска

• Кэш закладок: Полный список закладок кэшируется на 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

Тестирование с мок-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: Каркас MCP с абстракцией инструментов и асинхронным сервером FastAPI

• pinboard.py: Обертка клиента API Pinboard с обработкой ошибок

• Pydantic: Валидация данных и сериализация с использованием JSON Schema

• ThreadPoolExecutor: Связывает асинхронный MCP с синхронной библиотекой pinboard.py

• LRU Cache: Кэширование в памяти с интеллектуальной инвалидацией

Ключевые файлы

• src/pinboard_mcp_server/main.py - Точка входа сервера MCP и реализация инструментов

• src/pinboard_mcp_server/client.py - Клиент API Pinboard с кэшированием

• src/pinboard_mcp_server/models.py - Модели данных Pydantic

• tests/ - Комплексный набор тестов

• tests/debug_bookmarks.py - Утилита отладки для тестирования функциональности поиска

• docs/TEST_HARNESS.md - Документация для тестовых наборов

Производительность

• Время отклика P50: <250 мс (кэшированные ответы)

• Время отклика P95: <600 мс (холодный кэш)

• Ограничение скорости: 3-секундные интервалы между вызовами API

• Коэффициент попадания в кэш: >90% для типичных шаблонов использования

Безопасность

• API-токены никогда не логируются и не отображаются в сообщениях об ошибках

• Доступ к данным Pinboard только для чтения

• Валидация входных данных для всех параметров инструментов

• Безопасная обработка переменных окружения

Устранение неполадок

Распространенные проблемы

"PINBOARD_TOKEN environment variable is required"

• Убедитесь, что вы установили токен: export PINBOARD_TOKEN="username:token"

• Получите токен на странице https://pinboard.in/settings/password

• Формат токена должен быть: username:1234567890ABCDEF

"Command not found: pinboard-mcp-server"

• Убедитесь, что вы установили пакет: pip install pinboard-bookmarks-mcp-server

• Проверьте, активировано ли ваше окружение Python

• Попробуйте переустановить: pip uninstall pinboard-bookmarks-mcp-server && pip install pinboard-bookmarks-mcp-server

Сервер запускается, но Claude Desktop не может подключиться

• Проверьте конфигурацию MCP в настройках Claude Desktop

• Убедитесь, что путь command правильный: pinboard-mcp-server

• Убедитесь, что PINBOARD_TOKEN установлен в разделе env

Ошибки "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. Отправьте pull request

Лицензия

Лицензия MIT - подробности см. в файле LICENSE.