Problem statement
read_note pagination currently uses start_index + max_chars, but paginated reads do not carry a stable note-version guard. If a note changes between page requests, clients can receive mixed-version slices without a deterministic detection path. In addition, large-note pagination can be inefficient because each request can trigger repeated full-text reads.
Proposed solution
Harden read_note pagination consistency and performance while preserving backward compatibility.
- Stable pagination guard:
- Return a stable change token in
read_note responses (for example, mtime_ms and/or sha256).
- Accept an optional expected token on subsequent page requests.
- When token mismatches, return a clear structured error so clients can restart pagination safely.
- Performance follow-ups for large notes:
- Reduce repeated full-file reads across sequential page requests.
- Implement a bounded in-process cache and/or optimized partial-read strategy with clear invalidation semantics.
- Define memory/performance limits so optimization is predictable under load.
- API/contract handling:
- Keep existing fields (
text, truncated, next_start_index) intact for compatibility.
- Document continuation flow and mismatch recovery in MCP tool docs.
- Validation and tests:
- Add tests for unchanged-note pagination, mid-stream note edits (mismatch path), and large-note performance behavior.
- Verify no regression on path traversal and vault-root safety constraints.
Constraints / context (optional)
- Keep
read_note read-only semantics; no write-side behavior.
- Preserve current clients by making new guard fields/options additive.
- Maintain strict vault-relative path handling and existing security checks.
Problem statement
read_notepagination currently usesstart_index+max_chars, but paginated reads do not carry a stable note-version guard. If a note changes between page requests, clients can receive mixed-version slices without a deterministic detection path. In addition, large-note pagination can be inefficient because each request can trigger repeated full-text reads.Proposed solution
Harden
read_notepagination consistency and performance while preserving backward compatibility.read_noteresponses (for example,mtime_msand/orsha256).text,truncated,next_start_index) intact for compatibility.Constraints / context (optional)
read_noteread-only semantics; no write-side behavior.