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 SSErun-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 MCPexamples/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:
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)