Pinboard MCP-Server

Schreibgeschützter Zugriff auf Pinboard.in-Lesezeichen für LLMs über das Model Context Protocol (MCP).

Übersicht

Dieser Server bietet LLMs die Möglichkeit, Lesezeichen-Metadaten von Pinboard.in zur Inferenzzeit zu suchen, zu filtern und abzurufen. Er basiert auf FastMCP 2.0 und bietet vier Kern-Tools für die Interaktion mit Lesezeichen, während er die Ratenbegrenzungen von Pinboard respektiert und intelligentes Caching implementiert.

Related MCP server: Raindrop.io MCP Server

Funktionen

• Schreibgeschützter Zugriff auf Pinboard-Lesezeichen

• Fünf MCP-Tools: search_bookmarks, search_bookmarks_extended, list_recent_bookmarks, list_bookmarks_by_tags, list_tags

• Intelligentes Caching mit LRU-Cache und automatischer Invalidierung über den posts/update-Endpunkt

• Ratenbegrenzung respektiert die 3-Sekunden-Richtlinie von Pinboard zwischen API-Aufrufen

• Feldzuordnung konvertiert die Legacy-Feldnamen von Pinboard in intuitive Namen (description→title, extended→notes)

• Umfassende Tests mit Integrationstest-Harnesses und CI-Validierung

Installation

Via pip (empfohlen)

pip install pinboard-bookmarks-mcp-server

Aus dem Quellcode

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

Schnellstart

1. Holen Sie sich Ihren Pinboard-API-Token von https://pinboard.in/settings/password

2. Umgebungsvariable setzen:

   export PINBOARD_TOKEN="username:1234567890ABCDEF"

3. Server starten:

   pinboard-mcp-server

4. Überprüfen, ob es funktioniert:

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

Verwendung mit Claude Desktop

Fügen Sie diese Konfiguration zu Ihren Claude Desktop-Einstellungen hinzu:

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

Verfügbare Tools

1. search_bookmarks

Suchen Sie Lesezeichen nach Suchbegriffen in Titeln, Notizen und Tags. Fokus auf aktuelle Einträge mit automatischer Erweiterung.

Parameter:

• query (string): Suchbegriff

• limit (int, optional): Maximale Anzahl der Ergebnisse (Standard: 20, Maximum: 100)

Beispiel:

Search for "python testing" bookmarks

2. search_bookmarks_extended

Erweiterte Suche für umfassende historische Ergebnisse in Titeln, Notizen und Tags.

Parameter:

• query (string): Suchbegriff

• days_back (int, optional): Wie viele Tage zurück gesucht werden soll (Standard: 365, Maximum: 730)

• limit (int, optional): Maximale Anzahl der Ergebnisse (Standard: 100, Maximum: 200)

Beispiel:

Search the last 2 years for "kubernetes" bookmarks

3. list_recent_bookmarks

Lesezeichen auflisten, die in den letzten N Tagen gespeichert wurden.

Parameter:

• days (int, optional): Tage, die zurückgeblickt werden sollen (Standard: 7, Maximum: 30)

• limit (int, optional): Maximale Anzahl der Ergebnisse (Standard: 20, Maximum: 100)

Beispiel:

Show me bookmarks from the last 3 days

4. list_bookmarks_by_tags

ALLE Lesezeichen auflisten, gefiltert nach Tags mit optionalem Datumsbereich. Am effizientesten für den historischen Zugriff.

Parameter:

• tags (array): Liste der Tags zum Filtern (1-3 Tags)

• from_date (string, optional): Startdatum im ISO-Format (YYYY-MM-DD)

• to_date (string, optional): Enddatum im ISO-Format (YYYY-MM-DD)

• limit (int, optional): Maximale Anzahl der Ergebnisse (Standard: 100, Maximum: 200)

Beispiel:

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

5. list_tags

Alle Tags mit ihren Nutzungshäufigkeiten auflisten.

Beispiel:

What are my most used tags?

Konfiguration

Umgebungsvariablen

• PINBOARD_TOKEN (erforderlich): Ihr Pinboard-API-Token im Format username:token

Ratenbegrenzung

Der Server erzwingt automatisch eine 3-sekündige Verzögerung zwischen Pinboard-API-Aufrufen, um deren Richtlinien zu respektieren. Zwischengespeicherte Antworten werden sofort zurückgegeben.

Caching-Strategie

• Abfrage-Cache: LRU-Cache mit 1000 Einträgen für Suchergebnisse

• Lesezeichen-Cache: Vollständige Lesezeichenliste für 1 Stunde zwischengespeichert

• Cache-Invalidierung: Verwendet den posts/update-Endpunkt, um Änderungen zu erkennen

• Tag-Cache: Tag-Liste wird zwischengespeichert, bis sie manuell aktualisiert wird

Testen

Das Projekt enthält eine umfassende Testabdeckung mit mehreren Teststrategien:

Alle Tests ausführen

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

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

Echte API-Tests

# 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-Tests

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

Entwicklung

Einrichtung

# 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

Code-Qualität

# 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

Architektur

• FastMCP 2.0: MCP-Grundgerüst mit Tool-Abstraktion und async FastAPI-Server

• pinboard.py: Pinboard-API-Client-Wrapper mit Fehlerbehandlung

• Pydantic: Datenvalidierung und Serialisierung mit JSON-Schema

• ThreadPoolExecutor: Überbrückt async MCP mit der sync pinboard.py-Bibliothek

• LRU-Cache: In-Memory-Caching mit intelligenter Invalidierung

Wichtige Dateien

• src/pinboard_mcp_server/main.py - MCP-Server-Einstiegspunkt und Tool-Implementierungen

• src/pinboard_mcp_server/client.py - Pinboard-API-Client mit Caching

• src/pinboard_mcp_server/models.py - Pydantic-Datenmodelle

• tests/ - Umfassende Test-Suite

• tests/debug_bookmarks.py - Debug-Dienstprogramm zum Testen der Suchfunktionalität

• docs/TEST_HARNESS.md - Dokumentation für Test-Harnesses

Leistung

• P50-Antwortzeit: <250ms (zwischengespeicherte Antworten)

• P95-Antwortzeit: <600ms (kalter Cache)

• Ratenbegrenzung: 3-Sekunden-Intervalle zwischen API-Aufrufen

• Cache-Trefferquote: >90% bei typischen Nutzungsmustern

Sicherheit

• API-Token werden niemals protokolliert oder in Fehlermeldungen angezeigt

• Schreibgeschützter Zugriff auf Pinboard-Daten

• Eingabevalidierung für alle Tool-Parameter

• Sichere Handhabung von Umgebungsvariablen

Fehlerbehebung

Häufige Probleme

"PINBOARD_TOKEN environment variable is required"

• Stellen Sie sicher, dass Sie Ihren Token gesetzt haben: export PINBOARD_TOKEN="username:token"

• Holen Sie sich Ihren Token von https://pinboard.in/settings/password

• Das Token-Format sollte sein: username:1234567890ABCDEF

"Command not found: pinboard-mcp-server"

• Stellen Sie sicher, dass Sie das Paket installiert haben: pip install pinboard-bookmarks-mcp-server

• Überprüfen Sie, ob Ihre Python-Umgebung aktiviert ist

• Versuchen Sie eine Neuinstallation: pip uninstall pinboard-bookmarks-mcp-server && pip install pinboard-bookmarks-mcp-server

Server startet, aber Claude Desktop kann keine Verbindung herstellen

• Überprüfen Sie die MCP-Konfiguration in den Claude Desktop-Einstellungen

• Überprüfen Sie, ob der command-Pfad korrekt ist: pinboard-mcp-server

• Stellen Sie sicher, dass PINBOARD_TOKEN im env-Abschnitt gesetzt ist

"Permission denied" oder "Access denied"-Fehler

• Überprüfen Sie, ob Ihr Pinboard-Token gültig und aktiv ist

• Überprüfen Sie Ihre Internetverbindung, um pinboard.in zu erreichen

• Testen Sie Ihren Token manuell unter https://pinboard.in/api/v1/posts/recent

Mitwirken

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Führen Sie Ihre Änderungen mit Tests durch

4. Stellen Sie sicher, dass alle Tests bestehen und der Code formatiert ist

5. Senden Sie einen Pull Request

Lizenz

MIT-Lizenz - siehe LICENSE-Datei für Details.