Raindrop.io Data Interface via MCP

This specialized component establishes a Model Context Protocol (MCP) endpoint tailored to access and manipulate the data managed within the Raindrop.io bookmarking platform. It facilitates secure, structured access for Large Language Models (LLMs) and autonomous agents conforming to the MCP specification.

Core Capabilities

Full Resource Lifecycle Management (CRUD): Comprehensive capabilities for creating, retrieving, modifying, and purging bookmarks and their containing organizational units (collections).
Granular Filtering: Support for intricate search queries against bookmarks using parameters like taxonomy (tags), source domain, content type, creation timestamp, and more.
Taxonomy Administration: Tools for inspecting, renaming, consolidating (merging), and eradicating custom tags.
Annotation Retrieval: Direct access to extracted textual annotations (highlights) linked to specific saved items.
Organizational Structuring: Utilities for manipulating collection hierarchies, adjusting ordering, collapsing/expanding views, combining empty groupings, and removal.
Asset Ingestion: Functionality to upload binary data or files directly into the Raindrop ecosystem.
Temporal Management: Mechanism to schedule or establish time-based triggers (reminders) for particular saved items.
Data Portability: Initiation and status monitoring for bulk import/export operations.
System Cleanup: A utility for permanently clearing items held in the system's designated trash bin.
Protocol Conformity: Implements the full scope of Raindrop.io features as compliant MCP resources and callable tools.
Optimized Toolchain: Features 9 primary operational tools leveraging modern resource_link return patterns for optimized, lazy data fetching.
Agent Accessibility: Designed with explicit naming and exhaustive parameter documentation for seamless integration with AI reasoning engines.
State Streaming: Offers real-time data synchronization via Server-Sent Events (SSE) streams for bookmark state changes.
Implementation Stack: Built robustly with TypeScript, leveraging Axios for API interactions, Zod for rigorous input/output schema validation, and the official @modelcontextprotocol/sdk.

Operational Requirements

Node.js runtime environment (version 18+ highly suggested) or Bun.
An active Raindrop.io subscription.
A valid Raindrop.io API Access Credential (obtainable from the Raindrop.io Integrations panel).

Deployment and Execution

Using NPX (Recommended for Quick Start)

Execute the server directly without local installation:

bash

Securely set the required authorization token via environment variable

export RAINDROP_ACCESS_TOKEN=YOUR_SECRET_API_TOKEN

Start the MCP server

npx @adeze/raindrop-mcp

Local Source Setup

Repository Cloning:

bash git clone https://github.com/adeze/raindrop-mcp.git cd raindrop-mcp
Dependency Installation:

bash bun install
Configuration File Setup: Duplicate the template file to establish local secrets:

bash cp .env.example .env

Populate the .env file with your token:

env RAINDROP_ACCESS_TOKEN=YOUR_SECRET_API_TOKEN
Build and Launch: bash bun run build bun start

Protocol Inspection and Debugging

This service is engineered for seamless inspection using the MCP Inspector CLI. Consult ./github/prompts/inspector.prompt.md for comprehensive debugging protocols.

Inspector CLI Interaction Examples

Tool Enumeration: bash npx -y @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
Protocol Health Check (Ping): bash npx -y @modelcontextprotocol/inspector --cli node build/index.js --method ping
Debugging Session Initiation:
- For STDIN/STDOUT communication mode: bash npx -y @modelcontextprotocol/inspector node build/index.js
- For HTTP listener mode: bash npx -y @modelcontextprotocol/inspector node build/server.js

Launch configurations within VS Code can automate these debugging workflows, as detailed in the primary prompt file.

The default communication pipeline utilizes standard input/output (stdio), where the server actively listens for incoming MCP commands on stdin and transmits resulting data payloads to stdout.

Integration with MCP Clients

Connect your consuming MCP agent (e.g., an LLM framework) to the running server instance via the stdio stream. The server exposes the following URI structures for resource addressing:

Static Resource Pointers:

mcp://user/profile - Retrieves authenticated user account metadata.
diagnostics://server - Accesses internal server operational status and environmental data.

Dynamic Resource Identifiers (DRIs):

mcp://collection/{id} - Direct lookup for any specific Raindrop collection ID (e.g., mcp://collection/123456).
mcp://raindrop/{id} - Direct lookup for any specific Raindrop bookmark ID (e.g., mcp://raindrop/987654).

Exposed Operational Tools (Total: 10 functional units):

diagnostics: Server health and environment reportage.
collection_list: Retrieves all accessible collections (returns resource_link references).
collection_manage: Handles creation, modification, and deletion of collection entities.
bookmark_search: Executes filtered searches on bookmarks (returns resource_link references to results).
bookmark_manage: Manages the lifecycle (create/update/delete) of individual bookmark entries.
tag_manage: Performs administrative actions on the tag taxonomy (renaming, merging, removal).
highlight_manage: Interface for managing associated text highlights.
getRaindrop: Fetches details for a singular bookmark by its unique identifier (legacy access pattern).
listRaindrops: Retrieves the contents of a specified collection (legacy access pattern).
bulk_edit_raindrops: Facilitates atomic modification across multiple bookmarks concerning attributes like favoriting, tag set updates, cover art, and relocation.

Bulk Modification Utility Details

Tool Signature: bulk_edit_raindrops

Applies uniform modifications across a selected batch of stored items.

Payload Schema:

{ "collectionId": 123456, // Primary collection context for the operation "ids": [987654, 876543], // (Optional) Subset of IDs to target; if omitted, scope applies to collection content. "important": true, // (Optional) Toggle favorite/starred status "tags": ["work", "urgent"], // (Optional) Overwrite existing tags with this set (use [] to clear all tags). "media": ["https://img.com/a.png"], // (Optional) Set/overwrite associated media assets. "cover": "", // (Optional) Specify a new cover image reference. "collection": { "$id": 654321 }, // (Optional) Relocate selected items to this destination collection ID. "nested": false // (Optional) Scope search/operation recursively into sub-collections. }

Usage Illustration (Tag and Favorite Update):

{ "collectionId": 123456, "ids": [987654, 876543], "tags": ["project", "review"], "important": true }

Response Format: Returns a confirmation message detailing the success and count of affected records.

{ "content": [ { "type": "text", "text": "Bulk modification succeeded. Items altered: 2" } ] }

The adoption of resource_link responses in modern tools ensures that clients only materialize full data objects when explicitly requested via the associated dynamic resource URIs, leading to superior network efficiency.

MCP Integration Blueprint

To enable an MCP-aware client (such as an LLM orchestration layer) to discover this service, incorporate the following configuration snippet into your client's .mcp.json configuration file:

"raindrop": { "command": "npx", "args": [ "@adeze/raindrop-mcp@latest" ], "env": { "RAINDROP_ACCESS_TOKEN": "YOUR_MANAGED_API_TOKEN_HERE" } }

This mapping registers the service as "raindrop," setting up execution and environment variables required for secure operation within the client environment.

Development Lifecycle

Testing Suite Execution: bun test
Type Integrity Check: bun run type-check
Production Build Artifacts: bun run build
Live Development Server: bun run dev
Protocol Debugging Launch: bun run debug or bun run inspector
HTTP Listener Mode: bun run start:http

Contribution Guidelines

We welcome external contributions. Please report bugs via an issue or submit feature enhancements through a pull request.

Licensing

This software is distributed under the terms of the MIT License (refer to the LICENSE file).

System Architecture Summary

Directory Organization

Source Tree (src/):
index.ts, server.ts: Primary entry points for I/O (STDIO/HTTP) server processes.
connectors/: Modules handling external API communication (e.g., vendor-specific calls).
services/: Core business logic encapsulation (raindrop.service.ts, raindropmcp.service.ts).
types/: TypeScript interfaces, validation schemas (Zod), and protocol definitions.
utils/: Utility functions, including centralized logging mechanisms.
Output Directory (build/):
Transpiled JavaScript artifacts ready for execution and inspection.
Test Suite (tests/):
Complete suite of Vitest files covering service logic, protocol adherence, and integration points.

Foundational Technologies & Paradigms

Type Safety: Reliance on TypeScript for robust, maintainable code.
Validation Engine: Zod is employed universally for schema enforcement on all serialized data.
Runtime & Tooling: Bun for package management, scripting, and execution.
Testing Framework: Vitest, ensuring comprehensive validation of all system components.
Protocol Adherence: Strict implementation of the Model Context Protocol across both transport layers (STDIO/HTTP), mapping Raindrop functions to standard MCP resources and tools.
Debugging Support: Native integration with the Inspector utility for deep protocol analysis.
Defensive Architecture: Emphasis on robust error trapping, explicit typing, and validated data flows.
Declarative Interface: Tools and resources are explicitly defined with machine-readable schemas and rich documentation, adhering to MCP and DXT standards.

Tooling and Resource Abstraction

Resources: Mapped to canonical MCP Uniform Resource Identifiers (URIs) (e.g., data://tags/all, annotations://item/{id}).
Tools: Modularized, context-aware functionalities grouped logically, prioritizing AI consumption.
Service Abstraction: Centralized layer managing API request construction, data transformation, and standardized error response generation.
Connector Layer: Dedicated code for managing external dependencies.

Release Pipeline

Script Automation: All build, test, and release procedures are managed via Bun scripts.
DXT Manifest: Automated packaging and publication of the service descriptor via GitHub CLI.

📋 Recent System Enhancements (v2.0.12 Iteration)

MCP Resource Link Protocol Adoption ✨ NEW

Implementation adheres strictly to the best practices defined in MCP SDK v1.17.2.
Enables lightweight initial responses, postponing full data retrieval until necessitated by the client.
Significantly boosts operational performance through lazy loading.
Achieves full synergy with the established dynamic resource addressing system (mcp://raindrop/{id}).

Dependency Updates

Upgraded dependency on MCP SDK to version v1.17.2, incorporating latest protocol features.
Modernized tool registration utilizing the registerTool() API with enhanced descriptive metadata.
Corrected underlying paths for certain Raindrop.io API interactions.
Refinement of tool implementations; all 9 primary tools now exhibit full functional stability.

Toolchain Streamlining

Responses are optimized to return compact resource_link objects for listings.
Seamless navigation via dynamic resources (mcp://collection/{id}).
Improved client experience; lists can be rendered without immediate bulk data loading.
High compliance score against official SDK examples and specifications.

Service Layer Optimization

Achieved a demonstrable 25-30% reduction in code volume via strategic abstraction of common utility functions.
Uniform error handling protocols implemented across all operations.
Type safety enhanced through the introduction of generic response processing utilities.
Centralized logic for constructing API endpoints ensures consistency.

Developer Quality of Life (DX)

Integration support for advanced debugging environments, including VS Code launch profiles (see related GitHub issue).
Error reports now include clearer, actionable diagnostic suggestions.
Standardized resource referencing patterns for predictable agent interactions.
Implementation of comprehensive internal diagnostic tools for monitoring.

Automated Versioning and Deployment

Bun scripts and the GitHub CLI automate version tagging and manifest publication.

Tagging the Release Commit

Updates the package.json version, commits the tag, and pushes it to the remote repository:

bash

Increment version (e.g., patch release)

bun run bump:patch # Example: Moves from 2.0.10 to 2.0.11

Publish tag to trigger CI or manual steps

bun run tag:version # Creates git tag and pushes it

Publishing the DXT Manifest

Generates a GitHub release artifact accompanied by the necessary raindrop-mcp.dxt descriptor:

bash bun run release:dxt

Prerequisites for Manual Release: - GitHub CLI (gh) must be installed and authorized. - The jq utility must be present for JSON parsing (brew install jq on macOS). - The raindrop-mcp.dxt file must be present in the root directory.

Relevant Package.json Scripts:

"tag:version": "git tag v$(jq -r .version package.json) && git push origin v$(jq -r .version package.json)", "release:dxt": "gh release create v$(jq -r .version package.json) raindrop-mcp.dxt --title \"Release v$(jq -r .version package.json)\" --notes \"DXT manifest for MCP\""

Refer to the official Model Context Protocol documentation and the Raindrop.io Developer Documentation for further technical context.

WIKIPEDIA: Business management tools encompass the entire spectrum of methodologies, applications, control systems, and computational solutions utilized by organizational entities to navigate evolving market conditions, maintain competitive parity, and systematically enhance operational efficacy. These tools are critically important for achieving strategic objectives in a rapidly changing commercial environment.

== Core Management Functions == These systems can be functionally segmented based on the organizational department they serve or the management aspect they address. Common classifications include tools supporting strategic planning, workflow process governance, data record-keeping, human resource oversight, complex decision modeling, performance monitoring, and risk mitigation.

Technological advancements over the preceding decade have profoundly reshaped the landscape of business management software. This rapid evolution often creates a challenge for leadership teams attempting to select the optimal toolset for specific operational contexts. This difficulty stems from constant pressure to reduce operational expenditures, maximize revenue generation, achieve deeper insights into consumer requirements, and ensure product delivery meets those precise demands.

In this dynamic ecosystem, management must adopt a strategic, adaptive posture regarding tooling implementation. Simply adopting the newest available application without customization frequently results in suboptimal integration and instability. Therefore, business management applications must be chosen deliberately and then tailored precisely to the organization's unique requirements, rather than forcing the organization to conform to the tool's inherent structure.

== Leading Indicators of Business Tool Usage (2013 Survey Context) == Data collected by Bain & Company in 2013 provided a snapshot of global business tool utilization, reflecting regional strategic needs against prevailing market situations. The leading methodologies identified included:

Strategic Planning Frameworks
Customer Relationship Management (CRM) Systems
Employee Feedback and Engagement Surveys
Competitive Benchmarking Analysis
Balanced Scorecard Implementation
Core Competency Modeling
Strategic Outsourcing Management
Organizational Change Management Programs
Supply Chain Optimization
Mission/Vision Statement Articulation
Market Segmentation Analysis
Total Quality Management (TQM) Systems

== Enterprise Software Applications == Business software refers to suites of computing programs deployed by personnel to execute diverse enterprise operations. These applications are engineered to augment productivity levels, quantify performance metrics, and execute complex organizational tasks with high fidelity.

The evolution progressed from early Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP) frameworks. Subsequently, dedicated Customer Relationship Management (CRM) solutions were integrated, culminating in the modern paradigm of cloud-native business management platforms.

While a clear correlation exists between Information Technology investment and organizational performance outcomes, two factors are paramount for realizing genuine value addition: the efficiency of the implementation process itself and the judicious selection and subsequent adaptation of the chosen software tools.