Servidor MCP de Readwise

Un servidor de Protocolo de Contexto de Modelo (MCP) para acceder e interactuar con su biblioteca Readwise.

Características

Accede a lo más destacado de tu biblioteca Readwise
Busque lo más destacado mediante consultas en lenguaje natural
Consigue libros y documentos de tu biblioteca
Integración perfecta con Claude y otros asistentes compatibles con MCP
Capacidades de solicitud mejoradas para el análisis destacado
Sistema de registro que tiene en cuenta el transporte
Manejo y validación de errores robustos
Cumplimiento del protocolo MCP con el manejo adecuado de request_id
Punto final de verificación de estado para monitoreo
Asistente de configuración mejorado con validación de clave API

Estructura del proyecto

Este repositorio está organizado en los siguientes directorios clave:

src/ : Código fuente principal del servidor MCP de Readwise
test-scripts/ : Scripts de prueba y utilidades para validar la funcionalidad del servidor MCP
- smart-mcp-test.sh : script de prueba principal para los transportes stdio y SSE
- run-simple-server.sh : Script para ejecutar un servidor MCP simple
- Consulte test-scripts/README.md para obtener la documentación completa
ejemplos/ : Implementaciones de ejemplo y muestras de código
- examples/mcp-implementations/ : Implementaciones básicas del servidor MCP
- examples/test-clients/ : Scripts de prueba del lado del cliente
- Consulte examples/README.md para obtener la documentación completa
dist/ : Salida de JavaScript compilada (generada)
scripts/ : Scripts de utilidad para desarrollo y pruebas

Instalación

# Install from npm
npm install -g readwise-mcp

# Or clone the repository and install dependencies
git clone https://github.com/your-username/readwise-mcp.git
cd readwise-mcp
npm install
npm run build

Configuración

Antes de utilizar el servidor, debe configurar su clave API de Readwise:

# Run the setup wizard
npm run setup

# Or start with the API key directly
readwise-mcp --api-key YOUR_API_KEY

Puede obtener su clave API en https://readwise.io/access_token .

Uso

CLI

# Start with stdio transport (default, for Claude Desktop)
readwise-mcp

# Start with SSE transport (for web-based integrations)
readwise-mcp --transport sse --port 3000

# Enable debug logging
readwise-mcp --debug

API

import { ReadwiseMCPServer } from 'readwise-mcp';

const server = new ReadwiseMCPServer(
  'YOUR_API_KEY',
  3000, // port
  logger,
  'sse' // transport
);

await server.start();

Pruebas con MCP Inspector

El proyecto incluye compatibilidad integrada para realizar pruebas con el inspector MCP. Puede usar el script de TypeScript o el script de shell para ejecutar el inspector.

Pruebas automatizadas

Ejecute el conjunto de pruebas automatizadas que verifica todas las herramientas y solicitudes:

# Run automated inspector tests
npm run test-inspector

# Run in CI mode (exits with status code)
npm run test-inspector:ci

El conjunto de pruebas verifica:

Inicio y conexión del servidor
Disponibilidad de herramientas y respuestas
Funcionalidad rápida
Manejo de errores
Cumplimiento del formato de respuesta

Cada prueba proporciona resultados detallados y un resumen de los casos aprobados y fallidos.

Pruebas manuales

Usando el script de Shell

# Test with stdio transport (default)
./scripts/inspector.sh

# Test with SSE transport
./scripts/inspector.sh -t sse -p 3001

# Enable debug mode
./scripts/inspector.sh -d

# Full options
./scripts/inspector.sh --transport sse --port 3001 --debug

Uso del script TypeScript

# Test with stdio transport (default)
npm run inspector

# Test with SSE transport
npm run inspector -- -t sse -p 3001

# Enable debug mode
npm run inspector -- -d

# Full options
npm run inspector -- --transport sse --port 3001 --debug

Opciones disponibles

-t, --transport <type> : Tipo de transporte (stdio o sse), predeterminado: stdio
-p, --port <number> : Número de puerto para el transporte SSE, predeterminado: 3001
-d, --debug : Habilitar el modo de depuración

Comandos de inspector de ejemplo

Pruebe una herramienta específica:

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

Pruebe un mensaje:

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

Enumere las herramientas y sugerencias disponibles:

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

Pruebas sin una clave API de Readwise

Si no tiene una clave API de Readwise o no desea utilizar su clave API real para realizar pruebas, puede utilizar la funcionalidad de prueba simulada:

npm run test-mock

Esto ejecuta un script de prueba que:

Crea una implementación simulada de la API Readwise
Configura el servidor MCP con esta API simulada
Prueba varios puntos finales con datos de muestra
Verifica la funcionalidad del servidor sin requerir una clave API real

La implementación simulada incluye:

Libros de muestra, destacados y documentos
Retrasos de red simulados para pruebas realistas
Pruebas de manejo de errores

Herramientas disponibles

get_highlights : Obtenga los aspectos destacados de su biblioteca Readwise
get_books : Obtenga libros de su biblioteca Readwise
get_documents : Obtenga documentos de su biblioteca Readwise
search_highlights : Busca destacados en tu biblioteca Readwise

Indicaciones disponibles

readwise_highlight : Aspectos destacados del proceso de Readwise
- Admite resúmenes, análisis, búsqueda de conexiones y generación de preguntas.
- Incluye manejo robusto de errores y validación de parámetros.
- Formatos destacados de una manera fácil de leer
readwise_search : Aspectos destacados de búsqueda y procesamiento de Readwise
- Proporciona resultados de búsqueda formateados con información de origen.
- Maneja errores de API con elegancia y mensajes fáciles de usar.
- Incluye validación de los parámetros requeridos

Mejoras recientes

Cumplimiento mejorado del protocolo MCP

Manejo adecuado de request_id en todas las respuestas
Validación de solicitudes entrantes según las especificaciones del protocolo MCP
Formato de respuesta de error consistente siguiendo las pautas de MCP

Experiencia de configuración mejorada

Asistente de configuración interactivo con validación de clave API
Almacenamiento seguro de la configuración
Mensajes de error detallados para la solución de problemas

Manejo robusto de errores

Mensajes de error específicos para diferentes condiciones de error de API
Formato de error consistente en todas las herramientas y avisos
Registro que tiene en cuenta el transporte y que no interfiere con el protocolo

Desarrollo

# Build the project
npm run build

# Run tests
npm test

# Start in development mode with auto-reload
npm run dev:watch

# Lint code
npm run lint

Licencia

Instituto Tecnológico de Massachusetts (MIT)