Readwise MCP サーバー

Readwise ライブラリにアクセスして対話するための Model Context Protocol (MCP) サーバー。

特徴

• Readwise ライブラリのハイライトにアクセス

• 自然言語クエリを使用してハイライトを検索する

• 図書館から本や文書を入手する

• Claude やその他の MCP 対応アシスタントとのシームレスな統合

• ハイライト分析のための強化されたプロンプト機能

• トランスポートを考慮したログ記録システム

• 堅牢なエラー処理と検証

• 適切な request_id 処理による MCP プロトコル準拠

• 監視用のヘルスチェックエンドポイント

• APIキー検証を備えたセットアップウィザードの改善

Related MCP server: Readwise Reader MCP Server

プロジェクト構造

このリポジトリは、次の主要なディレクトリに編成されています。

• src/ : Readwise MCP サーバーのメインソースコード

• test-scripts/ : MCP サーバーの機能を検証するためのテスト スクリプトとユーティリティ

  • smart-mcp-test.sh : stdio と SSE トランスポートの両方のメインテストスクリプト

  • run-simple-server.sh : シンプルな MCP サーバーを実行するスクリプト

  • 完全なドキュメントについてはtest-scripts/README.mdを参照してください。

• examples/ : 実装例とコードサンプル

  • examples/mcp-implementations/ : 基本的なMCPサーバーの実装

  • examples/test-clients/ : クライアント側テストスクリプト

  • 完全なドキュメントについてはexamples/README.mdを参照してください。

• dist/ : コンパイルされたJavaScript出力（生成済み）

• scripts/ : 開発とテストのためのユーティリティスクリプト

インストール

# 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

設定

サーバーを使用する前に、Readwise API キーを設定する必要があります。

# Run the setup wizard
npm run setup

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

API キーはhttps://readwise.io/access_tokenから取得できます。

使用法

コマンドライン

# 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();

MCP Inspectorによるテスト

このプロジェクトには、MCPインスペクターを使ったテストのための組み込みサポートが含まれています。インスペクターの実行には、TypeScriptスクリプトまたはシェルスクリプトを使用できます。

自動テスト

すべてのツールとプロンプトを検証する自動テスト スイートを実行します。

# Run automated inspector tests
npm run test-inspector

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

テスト スイートでは次の点を検証します。

• サーバーの起動と接続

• ツールの可用性と応答

• プロンプト機能

• エラー処理

• 応答形式の準拠

各テストでは、詳細な出力と合格/不合格のケースの概要が提供されます。

手動テスト

シェルスクリプトの使用

# 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

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

利用可能なオプション

• -t, --transport <type> : トランスポートタイプ (stdio または sse)、デフォルト: stdio

• -p, --port <number> : SSEトランスポートのポート番号、デフォルト: 3001

• -d, --debug : デバッグモードを有効にする

インスペクターコマンドの例

特定のツールをテストします。

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

プロンプトをテストします。

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

利用可能なツールとプロンプトを一覧表示します。

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

Readwise APIキーなしでのテスト

Readwise API キーをお持ちでない場合、またはテストに実際の API キーを使用したくない場合は、模擬テスト機能を使用できます。

npm run test-mock

これは次のテスト スクリプトを実行します:

1. Readwise APIのモック実装を作成します

2. このモックAPIを使用してMCPサーバーをセットアップします

3. サンプルデータを使用してさまざまなエンドポイントをテストします

4. 実際のAPIキーを必要とせずにサーバーの機能を検証します

モック実装には以下が含まれます。

• サンプルブック、ハイライト、ドキュメント

• 現実的なテストのためのネットワーク遅延のシミュレーション

• エラー処理テスト

利用可能なツール

• get_highlights : Readwise ライブラリからハイライトを取得します

• get_books : Readwise ライブラリから本を取得する

• get_documents : Readwise ライブラリからドキュメントを取得する

• search_highlights : Readwise ライブラリ内のハイライトを検索

利用可能なプロンプト

• readwise_highlight : Readwise からのプロセスのハイライト

  • 要約、分析、関連性の発見、質問の生成をサポートします

  • 堅牢なエラー処理とパラメータ検証が含まれています

  • 読みやすい形式でハイライトをフォーマットします

• readwise_search : Readwise からのハイライトを検索して処理します

  • ソース情報を含むフォーマットされた検索結果を提供します

  • ユーザーフレンドリーなメッセージでAPIエラーを適切に処理します

  • 必須パラメータの検証を含む

最近の改善点

強化されたMCPプロトコルコンプライアンス

• すべてのレスポンスにおける request_id の適切な処理

• MCPプロトコル仕様に対する受信リクエストの検証

• MCPガイドラインに従った一貫したエラー応答形式

セットアップエクスペリエンスの改善

• API キー検証を備えた対話型セットアップ ウィザード

• 構成の安全な保管

• トラブルシューティングのための詳細なエラーメッセージ

堅牢なエラー処理

• さまざまな API エラー条件に対する特定のエラー メッセージ

• すべてのツールとプロンプトで一貫したエラー形式

• プロトコルに干渉しないトランスポート対応のログ記録

発達

# 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

ライセンス

マサチューセッツ工科大学