Readwise MCP サーバー
Readwise ライブラリにアクセスして対話するための Model Context Protocol (MCP) サーバー。
特徴
- Readwise ライブラリのハイライトにアクセス
- 自然言語クエリを使用してハイライトを検索する
- 図書館から本や文書を入手する
- Claude やその他の MCP 対応アシスタントとのシームレスな統合
- ハイライト分析のための強化されたプロンプト機能
- トランスポートを考慮したログ記録システム
- 堅牢なエラー処理と検証
- 適切な request_id 処理による MCP プロトコル準拠
- 監視用のヘルスチェックエンドポイント
- APIキー検証を備えたセットアップウィザードの改善
プロジェクト構造
このリポジトリは、次の主要なディレクトリに編成されています。
- 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 キーを使用したくない場合は、模擬テスト機能を使用できます。
これは次のテスト スクリプトを実行します:
- Readwise APIのモック実装を作成します
- このモックAPIを使用してMCPサーバーをセットアップします
- サンプルデータを使用してさまざまなエンドポイントをテストします
- 実際の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
ライセンス
マサチューセッツ工科大学