pinboard-bookmarks-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Pinboard MCP Server built on FastMCP 2.0 that provides read-only access to Pinboard.in bookmarks for LLMs. The server exposes bookmark data via MCP tools, enabling LLMs to search, filter, and retrieve bookmark metadata during inference.

Architecture & Design

Based on the PRD (docs/pinboard_mcp_server_prd.md), the system follows this design:

• FastMCP 2.0 provides the MCP scaffolding with Tool abstraction, async FastAPI server, and JSON-Schema validation
• pinboard.py wrapper simplifies Pinboard API calls and error handling
• Read-only design with four main tools: searchBookmarks, listRecentBookmarks, listBookmarksByTags, listTags
• In-memory caching using LRU cache (1000 query results) with posts/update polling for cache invalidation
• Rate limiting respects Pinboard's 3-second guideline between requests

Key Implementation Details

• Field mapping: Pinboard's description → title, extended → notes in MCP responses
• Authentication: Uses PINBOARD_TOKEN environment variable (format: username:hex)
• Performance targets: P50 < 250ms cached, P95 < 600ms cold
• Cache strategy: Seeds from posts/all API call, invalidates using posts/update timestamp checks

Tech Stack (Planned)

• FastMCP 2.0, FastAPI, Uvicorn/Gunicorn
• pinboard.py ≥ 2.0.0
• Poetry for dependency management
• pytest, pytest-asyncio, responses, vcr.py for testing
• ruff, mypy for linting and type checking
• Optional: redis-lite for cache backend, OpenTelemetry for observability

Development Notes

• Target ≥90% test coverage with mocked pinboard.Pinboard using pytest-monkeypatch
• Integration tests use vcr.py cassettes for API replay
• Load testing with k6 targeting 30 RPS
• Never log Pinboard API tokens for security
• All dates returned in ISO-8601 Zulu format
• When introducing or upgrading dependencies, update the pyproject.toml file with the new version and run poetry update to update the lock file. Do a search online for appropriate version numbers rather than relying on your memory.
• Test Coverage Requirements: The CI pipeline requires 75% test coverage to pass. Current coverage exceeds requirements with comprehensive testing of search methods, error handling, and edge cases.