nb-api 0.2.1

Typed Rust interface to the nb note-taking CLI (subprocess wrapper: escaping, validation, output parsing)
Documentation

nb-api

Typed Rust interface to the nb note-taking CLI.

Purpose

nb-api provides a programmatic Rust client for nb, the command-line note-taking tool. It wraps nb as a subprocess, handling argument escaping, notebook qualification, output parsing, and error recovery.

This crate is designed for use by:

  • nb-mcp-server — the MCP server that exposes nb to LLM assistants
  • nbspec — notebook-first OpenSpec orchestration
  • Any Rust application that needs to drive nb programmatically

nb-api is intentionally free of MCP-specific dependencies (rmcp, schemars). The schemars feature is available as an optional add-on for consumers that need JSON Schema generation (e.g., MCP tool parameters).

Quick Start

Prerequisites

Install nb by following the official instructions: nb installation guide.

Usage

Add to your Cargo.toml:

[dependencies]
nb-api = "0.1"

With optional JSON Schema support:

[dependencies]
nb-api = { version = "0.1", features = ["schemars"] }

Example

use nb_api::{Config, NbClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config {
        notebook: Some("myproject".to_string()),
        ..Default::default()
    };
    let client = NbClient::new(&config)?;

    // Create a note
    let result = client.add_note(
        Some("My Note"),
        "Note content with `backticks` works fine.",
        &["design".to_string(), "api".to_string()],
        Some("docs"),
        None,
    ).await?;
    println!("{}", result);

    // Search notes
    let results = client.search_notes(
        &["API".to_string()],
        nb_api::SearchMode::Any,
        &[],
        None,
        None,
    ).await?;
    println!("{}", results);

    Ok(())
}

API Surface

All operations return Result<String, NbError> with raw ANSI-stripped CLI output. Typed accessor methods may be added in future versions.

Notes

Method Description
add_note Create a note (title, content, tags, folder)
show_note Read a note's content
edit_note Update a note (mode selects Overwrite (destructive: replaces every byte), Append, or Prepend)
delete_note Delete a note
move_note Move or rename a note
list_notes List notes with optional filtering
search_notes Full-text search with OR/AND semantics

Todos

Method Description
add_todo Create a todo item with optional checklist
mark_task_done Mark a todo (or specific task) as complete
unmark_task_done Reopen a completed todo (or specific task)
list_tasks List checklist items within todos, with optional status filter

Organization

Method Description
add_bookmark Save a URL as a bookmark
import_note Import a file or URL
list_folders List folders in a notebook
add_folder Create a folder
list_notebooks List available notebooks
show_notebook_status Show notebook status
show_notebook_path Get the filesystem path for a notebook

Types

Type Description
NbClient Async client for invoking nb commands
NbError Error type for all operations
Config Configuration for constructing NbClient
EditMode Content update mode for edit_note (Overwrite is destructive: replaces every byte of the note body). Canonical serialization is overwrite; the legacy string replace is accepted as a serde alias for backward compatibility but is not advertised in the derived JSON Schema.
SearchMode Query matching mode (any, all)
TaskStatus Todo status filter (open, closed)

Configuration

Config contains only nb-relevant fields:

Field Type Default Description
notebook Option<String> None Default notebook name (overrides Git-derived fallback)
create_notebook bool true Automatically create missing notebooks
allow_top_level_notes bool false Allow notes at notebook root without a folder
disable_git_signing bool false Disable Git commit/tag signing for nb subprocesses

Notebook Resolution

Priority order:

  1. Per-command notebook argument (highest)
  2. Config.notebook field
  3. Git-derived default from the master worktree path

The NB_MCP_NOTEBOOK environment variable is not read by nb-api. That is an MCP-server-specific convention resolved by nb-mcp-server before constructing Config.

Features

Feature Default Description
schemars disabled Adds JsonSchema derive to EditMode, SearchMode, TaskStatus
testing disabled Exposes the nb_api::testing module with NbTestEnv and friends; pulls in tempfile as a dependency. Use for integration tests of consumers.
testing-tokio disabled Within nb_api::testing, reveals the async helpers NbTestEnv::configure_tokio and NbTestEnv::nb_command_async. The crate's own tokio usage (in NbClient) is unconditional and does not depend on this flag. Pair with testing to reach the async helpers.

License

Apache 2.0

Repository History

This crate was extracted from emcd/nb-mcp-server, where it lived as a workspace member at nb-api/. The nb-api 0.1.0 release was published from that repository.

Starting with 0.1.1, nb-api is developed and published from this repository (emcd/nb-api). The split is governed by the split-nb-api-repository OpenSpec proposal.

Git history begins fresh in this repository. Pre-split history (the work extracted from nb-mcp-server/nb-api/) is preserved at emcd/nb-mcp-server on the master branch. Archaeologists tracing the lineage of a particular change should look there first.