nb-mcp-server

nb-mcp

LLM が使いやすいノート作成のために、nb CLI をラップする MCP サーバーです。

動機

シェル経由で nb を直接使う場合、LLM アシスタントには次の 2 つの問題があります。

1. バッククォートのエスケープ：バッククォートを含む Markdown コンテンツはシェルのコマンド置換を引き起こし、ノートが破損します。

2. ノートブックのコンテキスト：nb はデフォルトのノートブックを前提としているため、プロジェクトごとの利用が扱いにくくなります。

この MCP サーバーは、次の方法で両方の問題を解決します。

• コンテンツを JSON パラメーターとして受け取る（シェルのエスケープが不要）
• すべてのコマンドに明示的なノートブックを指定する

クイックスタート

前提条件

公式の手順に従って nb をインストールしてください。 nb のインストールガイド。

インストール

crates.io から：

cargo install nb-mcp-server

リリース履歴とアップグレードに関する注意事項については、変更履歴をご覧ください。

または、GitHub Releases からビルド済みバイナリをダウンロードしてください。

ソースからビルド

cargo build --release

実行

環境変数で指定されたデフォルトのノートブックを使用する場合：

NB_MCP_NOTEBOOK=myproject ./target/release/nb-mcp

または、CLI 引数で指定する場合（こちらが優先されます）：

./target/release/nb-mcp --notebook myproject

ノートブックリポジトリでのコミットおよびタグの署名を無効にします。

./target/release/nb-mcp --notebook myproject --no-commit-signing

フォルダーを必須とせず、ノートブックのルートに新しいノートを作成できるようにします。

./target/release/nb-mcp --notebook myproject --allow-top-level-notes

インストールされているバージョンを表示します。

./target/release/nb-mcp --version

解決されたノートブックのパスと状態ディレクトリを表示します。

./target/release/nb-mcp --show-paths

MCP の設定

MCP クライアントの設定（例：.mcp.json）に追加します。

{
  "mcpServers": {
    "nb": {
      "command": "/path/to/nb-mcp",
      "args": ["--notebook", "myproject"]
    }
  }
}

コマンド

標準的なアクセス方法は、command パラメーターを指定する多重化された nb ツールです。MCP サーバーのトークン使用量を削減できます。 args フィールドは JSON オブジェクトである必要があります。文字列化された JSON ペイロードは拒否されます。 不明な args フィールドは無視されずに拒否されます。コマンドのスキーマで定義されているフィールド、または文書化された別名を正確に使用してください。 coordination/mcp/1 や myproject:coordination/mcp/1 など、返される識別子は nb セレクターであり、現在のリポジトリ内のファイルシステムパスではありません。ノートブックの保存先は nb の設定によって管理されます。 notebook 引数にはノートブック名のみを指定してください。フォルダーパスには folder を、ノートのセレクターには id / selector を使用してください。既存のアイテムを対象とするコマンドでは、myproject:coordination/mcp/1 のようにコピーしたセレクターを使用できますが、別の notebook 引数との競合は拒否されます。

独立したツール

すべてのコマンドは、型付きスキーマを持つ独立したツールとしても利用できます：add、show、delete、move、list、search、todo、do、undo、tasks、bookmark、folders、mkdir、import、status、notebooks のほか、本文を扱うツール replace_note_body、edit_note_substring、edit_note_lines、retitle_note、edit_note_tags、行を扱うツール show_note_lines、search_note_lines があります。これらは多重化されたコマンドのディスパッチを介さずに実行されます。多重化された nb ツールは、互換性維持のために残されたコマンドの簡潔な互換インターフェースとして引き続き利用できます。

ノート

コマンド	説明	主な引数
nb.add	ノートを作成します	title、content、tags[]、デフォルトで folder は必須
nb.show	ノートを読み込みます（構造化されたエンベロープ）	id（別名：selector）
nb.delete	ノートを削除します	id（別名：selector）
nb.move	ノートを移動または名前変更します	id（別名：selector）、destination
nb.list	ノートを一覧表示します	folder、tags[]、limit（[ ] / [x] は ToDo の状態を示し、先頭の記号はアイテムのマーカーです）
nb.search	全文検索を行います	queries[]（必須）、mode（デフォルトは any、all も指定可能）、tags[]

ToDo

コマンド	説明	主な引数
nb.todo	ToDo を作成します	デフォルトで folder は必須、title、任意の description（別名：content）、任意の tasks[]、tags[]
nb.do	完了としてマークします	id（別名：selector）、任意の task_number
nb.undo	未完了に戻します	id（別名：selector）、任意の task_number
nb.tasks	ToDo を一覧表示します	任意の status（open または closed）、任意の recursive（デフォルトは true）

組織

コマンド	説明	主な引数
nb.bookmark	URL を保存	url、デフォルトで必須の folder、title、tags[]、comment
nb.import	ファイル／URL をインポート	source、デフォルトで必須の folder、filename、convert
nb.folders	フォルダーを一覧表示	parent
nb.mkdir	フォルダーを作成	path
nb.notebooks	ノートブックのみを一覧表示	（なし）
nb.status	ノートブック情報	（なし）

例

コードを含むノートを作成：

{
  "command": "nb.add",
  "args": {
    "title": "API Design Notes",
    "content": "# API Design\n\nUse `GET /items` for listing.\n\n```python\nresponse = client.get('/items')\n```",
    "tags": ["design", "api"],
    "folder": "docs"
  }
}

ノートを検索：

{
  "command": "nb.search",
  "args": {
    "queries": ["API", "design"],
    "mode": "any",
    "tags": ["design"]
  }
}

タグ付けの提案

複数の LLM を使用するプロジェクトでは、一貫したタグの接頭辞を使用することを検討してください（任意）。 カテゴリと接頭辞の例：

カテゴリ	パターン	例
共同作業者	llm-<name>	llm-claude、llm-gpt
コンポーネント	component-<name>	component-api、component-ui
タスクの種類	task-<type>	task-bug、task-feature
ステータス	status-<state>	status-review、status-blocked

本文を考慮した編集

レガシーの nb.edit ツール（およびその overwrite／append／prepend モード）は、 nb-api 0.3 への移行時に削除されました。本文を考慮した置換ツールは 直接呼び出し専用（多重化された nb.* エイリアスはありません）であり、旧 インターフェースで可能だった、ノート全体を上書きしてしまう破壊的な失敗を 防ぐように設計されています。

• replace_note_body — ノート本文全体をプレーンな UTF-8 の new_body で置き換えます。直前の show で取得した本文の fingerprint が必要です。古い fingerprint は再読み込みを促す案内とともに拒否されるため、 直前に読み取っていないノートを上書きすることはできません。
• edit_note_substring — プレーンテキストの pattern に一致する箇所を 1 つ以上、replacement で置き換えます。 expected_count は実際の一致数と一致する必要があります。任意の fingerprint で古い編集を防止できます。
• edit_note_lines — 1 つの元スナップショットの行アンカーに照らして検証された、 重複しない挿入／削除／置換 edits のバッチを適用します。 content は終端バイトを含まないプレーンテキストです（ライブラリがドキュメントの EOL を追加するため、1 行の置換で次の行と結合されることはありません）。
• retitle_note — パスを変更せずにタイトルを変更します。
• edit_note_tags — 1 回のアトミックな操作でタグを追加および／または削除します。

これらのツールは、show／delete／move と同様に、フラットな id（エイリアスは selector）文字列でノートを指定します。ノートブック相対のファイル名は公開されず、 show／show_note_lines／ search_note_lines が返す修飾付き selector は、そのまま id として使用できます。nb-api 0.4 以降は 数値の .index ID も公開されます。読み取り結果と変更結果には selector と numeric_id が含まれ、<folder>/<id> および <id> を id として受け付けます（ID はフォルダー内でのみ有効な位置ベースの値で、再利用されることはありません。パスは正規の形式のままです）。本文の内容（pattern、replacement、title、 new_body、行編集の content）と行／検索の text／title は、 すべてネイティブの UTF-8 文字列で、通信上のどこにも base64 は使用されません。行単位の読み取りには show_note_lines（行ごとの終端ではなく、ドキュメント単位の eol 宣言（lf／crlf と has_final_eol）を含む、範囲が制限されたアンカー付きウィンドウ）と、 search_note_lines（設計上 EOL フィールドを含まない、アンカー付きの一致箇所）が使用できます。これらにより、ノート全体を読み取らずに 検索から編集まで行えます。新しいノートのファイル名は、タイトルから nb に準拠した形式で生成されます（Hello World Title → hello_world_title.md）。

add はノートの作成専用です。チェックボックス行や、フェンス付きコードブロックの外にある Tasks 見出しなど、todo 形式の内容は拒否され、代わりに todo ツールを使うよう案内されます。

多重化された nb.edit の呼び出しは、置き換えツールを示す復旧ガイダンスとともに拒否されます。本文対応ツールと行ツールは直接呼び出し専用です。 これらを多重化された nb ツール経由で呼び出すと拒否されます。

構造化された結果

• show はテキスト優先の簡潔な構造化エンベロープを返します。含まれるのは、selector、path、 kind、todo_state、title（正規化された Option<String>）、tags、body （UTF-8 の全文）、body_contiguous、fingerprint、numeric_id です。 base64 フィールドは公開されません。ソースが有効な UTF-8 でない場合、show は MIME のヒントに加え、MCP の外部にある未加工データ取得手段（nb CLI）を案内するガイダンスを含む、型付きの NonUtf8 エラーを返します。テキスト以外の対象の場合は UnsupportedShowTarget が返されます。 どちらの場合も、base64 バイト列は返されません。
• 変更を行うツール（add、todo、bookmark、mkdir、delete、move、 do、undo、および本文対応ツール）は、構造化された CommitOutcome を返します。含まれるのは、commit_created、revision_id、pre_revision、および操作ごとの path／selector／numeric_id／noop／fingerprint です。冪等な変更が何も行われなかった場合は、 commit_created: false が報告されます。

型付きエラーの発生箇所

nb-api 0.4 では型付きエラーが導入され、MCP レイヤーは、多重化された nb.* インターフェイスと 第一級のツールインターフェイスの両方で、対処方法が明確な診断メッセージに変換します。NonUtf8 と IndexLockTimeout（.index ロックが使用中の場合。後で再試行してください。変更は行われていません）が、既存のエラー群に加わります。

• テキスト以外のセレクター（フォルダー、アーカイブ、画像など）に対する show：エラーにはセレクターと実際の非テキスト型が示され、show はテキストノートのみを読み取ることが明記されます。また、呼び出し元には folders／list が案内されます。サーバーが show を別のコマンドに暗黙的に切り替えることはありません。
• title と content の両方を指定し、content の最初の空白以外の行がタイトルと重複する H1 の場合の add：エラーには タイトルと検出された見出しが示され、重複する H1 を削除するか、個別の title を省略するよう呼び出し元に伝えます。
• 編集時の古さを検出するガード：FingerprintMismatch、AnchorMismatch、OccurrenceMismatch は、ノートを再読み込みし、新しいフィンガープリント／アンカー／件数を使って再試行するよう呼び出し元に伝えます。
• FragmentedBody：複数の本文フラグメントがある場合（複数の本文フラグメントを持つブックマークなど）、行／部分文字列／本文置換の操作は拒否されます。メタデータ操作（retitle_note、edit_note_tags）は引き続き適用できます。
• DirtyBaseline：ノートブックのワークツリー／インデックスがダーティな場合、変更操作は拒否されます。診断メッセージでは、まずコミットするかクリーンにするよう伝えます。
• IndeterminateCommit／RecoveryRequired：コミットが完了したか不明な場合、または復旧が必要な場合に発生します。診断メッセージでは、自動再試行を行わず、操作する前に HEAD／ステータスを確認するよう指示します。
• GateTimeout：ノートブックが使用中です。後で再試行してください。
• PathCollision／PathIgnored／UnsupportedStructure／ PlanValidation：それぞれのパス／プランに関する具体的なガイダンスが示されます。

設定

ノートブックの解決

優先順位：

1. コマンドごとの notebook 引数（最優先）
2. CLI の --notebook フラグ
3. NB_MCP_NOTEBOOK 環境変数
4. master ワークツリーのパスから導出される Git のデフォルト

ノートブックを解決できない場合、コマンドは設定エラーで失敗します。 サーバーが nb のデフォルトノートブックにフォールバックすることはありません。

解決されたノートブックが存在しない場合、サーバーが自動的に作成します。 自動作成を無効にするには、--no-create-notebook を使用します。

ロギング

ログは ~/.local/state/nb-mcp/{project}--{worktree}.log に書き込まれます（XDG 準拠）。

Git ワークツリーの場合、複数の MCP サーバーインスタンス間での衝突を避けるため、ログ名には master プロジェクトと ワークツリーのベース名の両方が使われます。

解決されたノートブックのパスと状態ディレクトリを表示するには、--show-paths を使用します。

フォルダーの必須要件

エージェントがプロジェクトのノートブックルートに誤ってノートを散乱させないよう、デフォルトではノートを作成するコマンドに folder 引数が必要です。これは nb.add、nb.todo、 nb.bookmark、nb.import に適用されます。新しいフォルダーの作成には nb.mkdir を、既存のフォルダーの一覧表示には nb.folders を使用します。

ルート階層へのノート作成を許可するには、NB_MCP_ALLOW_TOP_LEVEL_NOTES=true を設定するか、--allow-top-level-notes を渡します。

ノートブックのオーバーライド

変更コマンドは、notebook 引数でプロジェクトのデフォルト以外のノートブックを指定して正常に書き込みが完了すると、警告を表示します。チーム間のコラボレーションのため、ノートブックをまたいだ書き込みは引き続き可能ですが、この警告によってノートブックとフォルダーの取り違えを防ぎやすくなります。

notebook 引数に指定できるのはノートブック名のみで、セレクター構文は使用できません。たとえば、notebook: "other-team:todos/mcp" ではなく、folder: "todos/mcp" とともに notebook: "other-team" を使用してください。

RUST_LOG でログレベルを制御します。

RUST_LOG=debug nb-mcp --notebook myproject

コミット署名

--no-commit-signing を使用すると、ノートブックリポジトリでのコミットとタグの署名を無効にできます。サーバーはノートブックリポジトリのローカル Git 設定を更新し、署名の確認プロンプトによって MCP ツールの呼び出しがブロックされないようにします。

関連プロジェクト

• nb-api — nb CLI 用の型付き Rust インターフェースです。crates.io で公開されています。この MCP サーバーは、すべてのノート作成プリミティブを nb-api に依存しています。本文を考慮した編集機能、型付きエラー、構造化された結果、サニタイズされた空の一覧は、すべて nb-api 0.4 によって提供されます。

貢献

貢献ガイドと行動規範をご覧ください。

• 貢献ガイド
• 行動規範

ライセンス

Apache 2.0