Servidor MCP de Pinboard

Acceso de solo lectura a los marcadores de Pinboard.in para LLM a través del Protocolo de Contexto de Modelo (MCP).

Descripción general

Este servidor proporciona a los LLM la capacidad de buscar, filtrar y recuperar metadatos de marcadores de Pinboard.in en tiempo de inferencia. Construido sobre FastMCP 2.0, ofrece cuatro herramientas principales para la interacción con marcadores, respetando los límites de velocidad de Pinboard e implementando un almacenamiento en caché inteligente.

Related MCP server: Raindrop.io MCP Server

Características

• Acceso de solo lectura a los marcadores de Pinboard

• Cinco herramientas MCP: search_bookmarks, search_bookmarks_extended, list_recent_bookmarks, list_bookmarks_by_tags, list_tags

• Almacenamiento en caché inteligente con caché LRU y anulación automática mediante el endpoint posts/update

• Limitación de velocidad que respeta la directriz de 3 segundos de Pinboard entre llamadas a la API

• Mapeo de campos que convierte los nombres de campos heredados de Pinboard a otros intuitivos (description→title, extended→notes)

• Pruebas exhaustivas con bancos de pruebas de integración y validación de CI

Instalación

Vía pip (recomendado)

pip install pinboard-bookmarks-mcp-server

Desde el código fuente

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

Inicio rápido

1. Obtén tu token de API de Pinboard en https://pinboard.in/settings/password

2. Establece la variable de entorno:

   export PINBOARD_TOKEN="username:1234567890ABCDEF"

3. Inicia el servidor:

   pinboard-mcp-server

4. Verifica que funciona:

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

Uso con Claude Desktop

Añade esta configuración a tus ajustes de Claude Desktop:

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

Herramientas disponibles

1. search_bookmarks

Busca marcadores mediante una cadena de consulta en títulos, notas y etiquetas. Enfocado en resultados recientes con expansión automática.

Parámetros:

• query (string): Consulta de búsqueda

• limit (int, opcional): Resultados máximos (predeterminado: 20, máx: 100)

Ejemplo:

Search for "python testing" bookmarks

2. search_bookmarks_extended

Búsqueda extendida para obtener resultados históricos completos en títulos, notas y etiquetas.

Parámetros:

• query (string): Consulta de búsqueda

• days_back (int, opcional): Cuántos días atrás buscar (predeterminado: 365, máx: 730)

• limit (int, opcional): Resultados máximos (predeterminado: 100, máx: 200)

Ejemplo:

Search the last 2 years for "kubernetes" bookmarks

3. list_recent_bookmarks

Lista los marcadores guardados en los últimos N días.

Parámetros:

• days (int, opcional): Días hacia atrás (predeterminado: 7, máx: 30)

• limit (int, opcional): Resultados máximos (predeterminado: 20, máx: 100)

Ejemplo:

Show me bookmarks from the last 3 days

4. list_bookmarks_by_tags

Lista TODOS los marcadores filtrados por etiquetas con un rango de fechas opcional. Es la forma más eficiente para el acceso histórico.

Parámetros:

• tags (array): Lista de etiquetas para filtrar (1-3 etiquetas)

• from_date (string, opcional): Fecha de inicio en formato ISO (YYYY-MM-DD)

• to_date (string, opcional): Fecha de fin en formato ISO (YYYY-MM-DD)

• limit (int, opcional): Resultados máximos (predeterminado: 100, máx: 200)

Ejemplo:

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

5. list_tags

Lista todas las etiquetas con sus recuentos de uso.

Ejemplo:

What are my most used tags?

Configuración

Variables de entorno

• PINBOARD_TOKEN (obligatorio): Tu token de API de Pinboard en formato username:token

Limitación de velocidad

El servidor aplica automáticamente un retraso de 3 segundos entre llamadas a la API de Pinboard para respetar sus directrices. Las respuestas cacheadas se devuelven inmediatamente.

Estrategia de caché

• Caché de consultas: Caché LRU con 1000 entradas para resultados de búsqueda

• Caché de marcadores: Lista completa de marcadores cacheada durante 1 hora

• Anulación de caché: Utiliza el endpoint posts/update para detectar cambios

• Caché de etiquetas: Lista de etiquetas cacheada hasta que se actualice manualmente

Pruebas

El proyecto incluye una cobertura de pruebas exhaustiva con múltiples estrategias:

Ejecutar todas las pruebas

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

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

Pruebas de API real

# 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

Pruebas de API simulada (Mock)

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

Desarrollo

Configuración

# 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

Calidad del código

# 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

Arquitectura

• FastMCP 2.0: Estructura MCP con abstracción de herramientas y servidor FastAPI asíncrono

• pinboard.py: Envoltorio del cliente de la API de Pinboard con gestión de errores

• Pydantic: Validación de datos y serialización con JSON Schema

• ThreadPoolExecutor: Conecta el MCP asíncrono con la biblioteca síncrona pinboard.py

• Caché LRU: Almacenamiento en memoria con anulación inteligente

Archivos clave

• src/pinboard_mcp_server/main.py - Punto de entrada del servidor MCP e implementaciones de herramientas

• src/pinboard_mcp_server/client.py - Cliente de la API de Pinboard con caché

• src/pinboard_mcp_server/models.py - Modelos de datos Pydantic

• tests/ - Suite de pruebas completa

• tests/debug_bookmarks.py - Utilidad de depuración para probar la funcionalidad de búsqueda

• docs/TEST_HARNESS.md - Documentación para los bancos de pruebas

Rendimiento

• Tiempo de respuesta P50: <250ms (respuestas cacheadas)

• Tiempo de respuesta P95: <600ms (caché fría)

• Limitación de velocidad: intervalos de 3 segundos entre llamadas a la API

• Ratio de aciertos de caché: >90% para patrones de uso típicos

Seguridad

• Los tokens de API nunca se registran ni se exponen en mensajes de error

• Acceso de solo lectura a los datos de Pinboard

• Validación de entrada en todos los parámetros de las herramientas

• Manejo seguro de variables de entorno

Solución de problemas

Problemas comunes

"PINBOARD_TOKEN environment variable is required"

• Asegúrate de haber configurado tu token: export PINBOARD_TOKEN="username:token"

• Obtén tu token en https://pinboard.in/settings/password

• El formato del token debe ser: username:1234567890ABCDEF

"Command not found: pinboard-mcp-server"

• Asegúrate de haber instalado el paquete: pip install pinboard-bookmarks-mcp-server

• Comprueba que tu entorno de Python esté activado

• Intenta reinstalar: pip uninstall pinboard-bookmarks-mcp-server && pip install pinboard-bookmarks-mcp-server

El servidor inicia pero Claude Desktop no puede conectar

• Verifica la configuración de MCP en los ajustes de Claude Desktop

• Comprueba que la ruta del command sea correcta: pinboard-mcp-server

• Asegúrate de que PINBOARD_TOKEN esté configurado en la sección env

Errores de "Permission denied" o "Access denied"

• Verifica que tu token de Pinboard sea válido y esté activo

• Comprueba que tienes conexión a internet para llegar a pinboard.in

• Prueba tu token manualmente en https://pinboard.in/api/v1/posts/recent

Contribución

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)

3. Realiza tus cambios con pruebas

4. Asegúrate de que todas las pruebas pasen y el código esté formateado

5. Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.