Pinboard MCP サーバー

Model Context Protocol (MCP) を介して、LLM に Pinboard.in のブックマークへの読み取り専用アクセスを提供します。

概要

このサーバーは、推論時に Pinboard.in からブックマークのメタデータを検索、フィルタリング、取得する機能を LLM に提供します。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

• LRU キャッシュと posts/update エンドポイントを使用した自動無効化によるスマートキャッシュ

• API 呼び出し間の 3 秒間隔という Pinboard のガイドラインを遵守するレート制限

• 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, 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 (必須): username:token 形式の Pinboard API トークン

レート制限

サーバーは、Pinboard のガイドラインを遵守するため、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

モック 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 Schema を使用したデータ検証とシリアライズ

• 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 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 が接続できない

• 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 ファイルを参照してください。