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 キーを使用したくない場合は、模擬テスト機能を使用できます。

npm run test-mock

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

Readwise APIのモック実装を作成します
このモックAPIを使用してMCPサーバーをセットアップします
サンプルデータを使用してさまざまなエンドポイントをテストします
実際のAPIキーを必要とせずにサーバーの機能を検証します

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

サンプルブック、ハイライト、ドキュメント
現実的なテストのためのネットワーク遅延のシミュレーション
エラー処理テスト

利用可能なツール

get_highlights : Readwise ライブラリからハイライトを取得します
get_books : Readwise ライブラリから本を取得する
get_documents : Readwise ライブラリからドキュメントを取得する
search_highlights : Readwise ライブラリ内のハイライトを検索

利用可能なプロンプト

readwise_highlight : Readwise からのプロセスのハイライト
- 要約、分析、関連性の発見、質問の生成をサポートします
- 堅牢なエラー処理とパラメータ検証が含まれています
- 読みやすい形式でハイライトをフォーマットします
readwise_search : Readwise からのハイライトを検索して処理します
- ソース情報を含むフォーマットされた検索結果を提供します
- ユーザーフレンドリーなメッセージで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

ライセンス

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

Readwise MCP Server