Readwise MCP Server Interface

An implementation of the Model Context Protocol (MCP) designed to expose your Readwise collection for external processing.

Core Functionality

• Provision access to all saved annotations/highlights.
• Facilitate querying of annotations using expressive, natural language directives.
• Retrieve indexed books and digital documents.
• Native, friction-free connection with Claude and other MCP-adherent assistants.
• Advanced capabilities for prompt engineering based on retrieved content.
• Integrated transport-aware logging mechanism.
• Comprehensive validation and error mitigation routines.
• Strict adherence to the MCP specification, including correct request_id lifecycle management.
• A dedicated health endpoint for operational status monitoring.
• Streamlined initialization process featuring automated API credential verification.

Repository Layout

This codebase is structured into the following primary components:

• src/: Contains the core server logic implementation.
• test-scripts/: Utilities and scripts dedicated to validating the MCP server's performance.
• smart-mcp-test.sh: Primary execution script for validating both standard I/O and Server-Sent Events (SSE) transports.
• run-simple-server.sh: Utility to boot up a minimal MCP server instance.
• Consult test-scripts/README.md for comprehensive testing documentation.
• examples/: Demonstrations and sample code snippets.
• examples/mcp-implementations/: Basic scaffolding for MCP server deployment.
• examples/test-clients/: Client-side testing harness code.
• Refer to examples/README.md for detailed usage instructions.
• dist/: Output directory for compiled assets (e.g., JavaScript).
• scripts/: Auxiliary scripts supporting development and building processes.

Deployment Instructions

# Installation via Node Package Manager (NPM)
npm install -g readwise-mcp

# Alternatively, obtain the source and install dependencies locally
git clone https://github.com/your-username/readwise-mcp.git
cd readwise-mcp
npm install
npm run build

Configuration

Configuration mandates supplying your unique Readwise authentication token prior to operation:

# Execute the guided setup utility
npm run setup

# Initiate service startup directly with the key argument
readwise-mcp --api-key YOUR_API_KEY

Obtain your required API token from: https://readwise.io/access_token.

Operational Modes

Command Line Interface (CLI)

# Start using standard I/O transport (default, optimized for desktop clients)
readwise-mcp

# Start using SSE transport (suitable for web-based connections), binding to port 3000
readwise-mcp --transport sse --port 3000

# Activate verbose diagnostic logging
readwise-mcp --debug

Programmatic API Invocation

import { ReadwiseMCPServer } from 'readwise-mcp';

const server = new ReadwiseMCPServer(
  'YOUR_API_KEY', // API Token
  3000,           // Network Port
  logger,         // Logging Utility
  'sse'           // Selected Transport Method
);

await server.start();

Verification Using MCP Inspector

This utility suite includes native scaffolding for comprehensive testing via the MCP Inspector utility, callable through either the shell script or the TypeScript execution command.

Automated Verification Routines

Execute the automated test suite which systematically validates all exposed tools and prompt functionalities:

# Initiate automated inspector validation
npm run test-inspector

# Run tests suitable for Continuous Integration environments (status code exit)
npm run test-inspector:ci

The verification process confirms: - Successful server initialization and channel establishment. - Correct responses from exposed tool endpoints. - Functionality and output validation for all prompts. - Integrity of error response handling. - Conformance to mandated response formats.

Each test execution provides granular output tracing and a final summary tally.

Manual Debugging Interface

Shell Script Execution Method

# Test using the default I/O transport
./scripts/inspector.sh

# Test using SSE transport on port 3001
./scripts/inspector.sh -t sse -p 3001

# Enable verbose logging during testing
./scripts/inspector.sh -d

# Invoking with all parameters explicitly defined
./scripts/inspector.sh --transport sse --port 3001 --debug

TypeScript Script Execution Method

# Test using the default I/O transport
npm run inspector

# Test using SSE transport on port 3001
npm run inspector -- -t sse -p 3001

# Enable verbose logging during testing
npm run inspector -- -d

# Invoking with all parameters explicitly defined
npm run inspector -- --transport sse --port 3001 --debug

Available Inspector Arguments

• -t, --transport <type>: Specifies the communication channel (options: stdio or sse), defaults to stdio.
• -p, --port <number>: Required port number when using sse, defaults to 3001.
• -d, --debug: Flag to activate diagnostic output levels.

Example Inspector Interactions

Execute a query against a specific tool:

./scripts/inspector.sh
> tool get-highlights --parameters '{"page": 1, "page_size": 10}'

Invoke a processing prompt:

./scripts/inspector.sh
> prompt search-highlights --parameters '{"query": "python"}'

Obtain a roster of accessible functions:

./scripts/inspector.sh
> list tools
> list prompts

Testing Without Live Credentials

For environments where a live Readwise API token is unavailable or undesirable for testing, leverage the built-in mocking capability:

npm run test-mock

This command executes a sequence that:

1. Instantiates a simulated implementation of the Readwise API layer.
2. Configures the MCP server to utilize this mock API backend.
3. Runs various functional tests against simulated data fixtures.
4. Confirms server responsiveness independent of actual external API calls.

The mock environment incorporates: - Pre-loaded sample datasets for books, highlights, and documents. - Simulated network latency profiles for realistic performance assessment. - Verification pathways for expected failure scenarios.

Exposed Tools (Functions)

• get_highlights: Retrieves a paginated set of highlights from the user's repository.
• get_books: Fetches metadata for books contained within the library.
• get_documents: Retrieves access to full-text documents stored.
• search_highlights: Executes a targeted search across highlights using specified criteria.

Exposed Prompts (Intelligent Operations)

• readwise_highlight: Applies advanced processing to selected highlights.
• Capabilities include abstract generation, thematic analysis, cross-reference identification, and question formulation.
• Features rigorous validation of input parameters and robust exception management.

• Renders output in a highly legible, reader-centric format.

• readwise_search: Executes a search and subsequently refines/formats the retrieved results.

• Delivers search results structured with clear source attribution.
• Ensures API communication failures are translated into user-friendly messages.
• Validates the presence of all necessary input arguments.

Recent Enhancements

Strengthened MCP Protocol Adherence

• Guaranteed inclusion and correct management of request_id in every outgoing transaction.
• Rigorous input validation against the official MCP specification schema.
• Standardization of error response formats per MCP guidelines.

Optimized Setup Workflow

• Introduction of an interactive wizard that validates the provided API key immediately.
• Implementation of secure configuration persistence.
• Enhanced diagnostics for setup-related troubleshooting.

Resilient Error Management

• Granular error messaging specific to identified Readwise API failure modes.
• Uniform error response structure applied universally across all tools and prompts.
• Non-intrusive, transport-aware logging that respects protocol framing.

Development Workflow

# Compile the project artifacts
npm run build

# Execute test suites
npm test

# Initiate development mode with automatic recompilation on save
npm run dev:watch

# Enforce code style standards
npm run lint

License

MIT

== Introduction == XMLHttpRequest (XHR) represents an API embodied by a JavaScript object, facilitating the transmission of HTTP requests from a web client environment to a remote server. These methods permit browser-based applications to dynamically issue server queries post-page load and subsequently receive data back asynchronously. XHR is a foundational component of the Ajax development paradigm. Preceding Ajax adoption, the primary interaction methods with the server involved conventional page navigation triggered by hyperlink clicks or form submissions, which typically resulted in a full page refresh.

== Genesis == The conceptual foundation for XMLHttpRequest was formulated in the year 2000 by the engineering team behind Microsoft Outlook. This idea was subsequently integrated into Internet Explorer version 5 (released in 1999). It is important to note that the initial implementation did not utilize the literal XMLHttpRequest identifier. Instead, developers relied on invoking COM objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 in 2006, universal support for the standardized XMLHttpRequest identifier was achieved across all major browser platforms, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Process === The World Wide Web Consortium (W3C) released an initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification was published by the W3C on February 25, 2008. Level 2 introduced enhancements such as progress monitoring methods, enablement of cross-origin resource sharing (CORS), and functionality for handling raw byte streams. By the conclusion of 2011, the features defined in Level 2 were incorporated back into the primary specification document. Development oversight was transitioned to the WHATWG group near the end of 2012, where it is maintained presently as a living document utilizing Web IDL definitions.

== Operational Use == The standard procedure for dispatching a request using XMLHttpRequest mandates several distinct programming phases.

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor.
2. Configuration: Invoke the open method to define the request method (GET/POST, etc.), specify the target resource URI, and select between synchronous or asynchronous execution modes.
3. Asynchronous Hookup: For asynchronous operations, register an event listener function designed to process state changes.
4. Transmission: Commence the transfer by calling the send method.
5. Response Handling: Monitor state transitions via the registered listener. Upon successful server response, data is typically stored in the responseText property. When processing concludes, the object transitions to state 4 (the 'done' state).

Beyond these fundamental steps, XMLHttpRequest offers extensive configuration levers for request origination and response consumption. Custom header fields can be appended to dictate server processing instructions, and payload data can be uploaded via the argument passed to the send invocation. Server responses, such as JSON payloads, can be automatically deserialized into native JavaScript objects, or processed incrementally as data arrives, circumventing the need to await full reception. Furthermore, requests can be canceled prematurely or configured with time limits, resulting in automatic failure if the deadline is exceeded.