Mi Note MCP

🚀 mi_note_mcp

mi_note_mcp は、Model Context Protocol (MCP) に基づく小米クラウドノートサーバーの実装です。MCP に対応したアシスタント（Claude、ChatGPT デスクトップ版など）が、直接あなたのクラウドノートを読み取り、検索し、作成し、管理することができます。このプロジェクトはローカルでインターフェースの結果をキャッシュし、Markdown と XML の相互変換機能を提供することで、大規模言語モデルがノート内容をシームレスに処理できるようにします。

✨ 主な機能

• 読み取り、検索、キャッシュ：ノートの一覧表示、検索、詳細表示をサポートし、自動的にローカルキャッシュを維持することで、重複するネットワークリクエストを軽減します。
• 完全なノート編集機能：ノートの作成、更新、削除、移動などの一般的な操作を提供し、リソースの状態を自動的に同期します。
• フォルダ管理：フォルダの一覧表示、作成、名前変更、削除、およびフォルダごとのノート表示をサポートします。
• リッチテキスト変換：Markdown と小米ノートの内部 XML を相互に変換し、タスクリスト、画像、太字などの形式を保持します。
• 画像アップロード：ローカル画像を小米クラウドにアップロードし、minote://image/{fileId} 形式の再利用可能なリンクを返します。
• MCP リソース公開：ノートやフォルダに関連するリソース URI を公開し、コンテキストの補完とナビゲーションを容易にします。

📦 インストール

環境要件

• Bun ≥ 1.1（開発テストでは 1.2.23 を使用）
• https://i.mi.com/note にアクセスできる小米アカウント
• Node.js TypeScript エコシステム（開発/型チェック時のみ必要）

手順

1. 依存関係のインストール

bun install

2. 認証情報の設定

サービスを起動する前に、設定ファイルを準備する必要があります。デフォルトのパスは ~/.mi-note-mcp.json ですが、環境変数 MI_NOTE_MCP_CONFIG を使用して別の場所を指定することもできます。

設定例：

{
  "serviceToken": "YOUR_SERVICE_TOKEN",
  "userId": "YOUR_USER_ID",
  "passToken": "オプション、ログインの安定性を向上させます",
  "slh": "オプション",
  "ph": "オプション",
  "deviceId": "オプション、ウェブページと一致させるため",
  "cUserId": "オプション",
  "uLocale": "zh_CN",
  "syncInterval": 30000,
  "baseUrl": "https://i.mi.com"
}

取得方法は、ブラウザで 小米クラウドノート にログインした後、開発者ツールを使用してリクエストヘッダーの Cookie フィールド（serviceToken、userId、passToken など）をコピーすることをおすすめします。これらのフィールドは長期間有効であることを確認してください。syncInterval はミリ秒単位で、バックグラウンドの増分同期頻度を制御します。

3. MCP サーバーの起動

bun run index.ts

起動に成功すると、ターミナルに mi-note-mcp server started と表示されます。その後、MCP に対応したクライアントで mi_note_mcp をローカルサービスとして登録し、クライアントの指示に従ってコマンドと作業ディレクトリを入力してください。

📚 ドキュメント

MCP ツール

MCP リソース

🔧 技術詳細

キャッシュと同期メカニズム

• 初回起動時に /note/full/page を介して全量データを取得し、メモリにキャッシュします。
• その後、syncInterval（デフォルトで 30 秒）に従って増分同期インターフェースを呼び出し、ノートとフォルダの状態を更新します。
• ツールが書き込み操作を実行した後、キャッシュを自動的に更新し、リソースの更新をトリガーして、MCP クライアント側の UI とコンテキストがすぐに変更を感知できるようにします。
• NotesCache の refresh() メソッドを使用して、コード内でキャッシュを強制的に更新することができます（ほとんどのツールでは自動的に呼び出されます）。

開発とテスト

• 型チェック（コミット前に実行することを推奨）：

bun run tsc --noEmit --skipLibCheck

• 単体テスト：

bun test

開発時には、リポジトリ内の既存のコードスタイルとディレクトリ構造に従い、必要に応じて tests/ 以下のテストケースを参照して、重要なモジュールの動作を理解することをおすすめします。

よくある質問

• 設定ファイルが存在しないと表示される場合：~/.mi-note-mcp.json が正常に作成されていること、または MI_NOTE_MCP_CONFIG が正しく設定されていることを確認してください。
• 401/403 が返される場合：通常は serviceToken、userId などの Cookie が期限切れになっています。ウェブページから再度コピーして設定を更新し、再試行してください。
• 画像アップロードが失敗する場合：ファイルが存在すること、MIME タイプが正しいこと、またはネットワークが i.mi.com にアクセス可能であることを確認してください。

追加のツールやリソースを拡張する場合は、既存のクライアントとキャッシュロジックを再利用し、プロジェクトの KISS/YAGNI 原則に従ってください。