raindrop-mcp GEMINI.md

Raindrop MCP Server - Project Context

Project Overview

This project is a Model Context Protocol (MCP) server for Raindrop.io, a bookmark management service. It allows AI assistants (like Claude or Gemini) to interact with a user's Raindrop bookmarks, collections, tags, and highlights using natural language.

The server supports both STDIO (standard input/output) and HTTP/SSE (Server-Sent Events) transports, making it compatible with various MCP clients including Claude Desktop and custom integrations.

Core Technologies

• Runtime: Bun (primary) / Node.js
• Language: TypeScript
• Frameworks:
  • @modelcontextprotocol/sdk: For MCP protocol implementation.
  • zod: For input/output schema validation.
  • express / node:http: For the HTTP/SSE transport layer.
  • axios / openapi-fetch: For Raindrop.io API communication.
• Testing: bun test (Vitest compatible)

Architecture

The project follows a modular service-oriented architecture:

• Entry Points:
  • src/index.ts: Main entry point for the STDIO transport server.
  • src/server.ts: Entry point for the HTTP/SSE server with session management and OAuth support.
• Core Service (src/services/raindropmcp.service.ts):
  • Manages the McpServer instance.
  • Registers tools, resources, and prompts.
  • Handles dynamic resource resolution.
• API Service (src/services/raindrop.service.ts):
  • Encapsulates direct communication with the Raindrop.io API.
  • Handles authentication (Access Token or OAuth).
• Tools (src/tools/):
  • Modular tool definitions using defineTool.
  • Categories: bookmarks, collections, tags, highlights, diagnostics, bulk.
• Resources:
  • Dynamic resources for individual bookmarks (mcp://raindrop/{id}) and collections (mcp://collection/{id}).
  • Static resources for user profile and server diagnostics.
• Prompts:
  • Built-in prompts for complex workflows like "organize_by_topic" or "find_duplicates".