v3.0.0

Added

• Search results include matching snippets — each result carries a short excerpt around the matched terms so you can judge relevance without opening every note.
• Plain-language errors for unprocessable search queries — when a query can't be parsed, the response says so in plain language and points at the offending input instead of leaking a raw SQLite error.
• bear-capabilities tool — when Edit Mode is off, surfaces the unlock guidance through tools/list so it reaches the model in clients that don't forward the MCP instructions field (Claude Desktop, OpenCode; partial: Codex CLI). Hidden once Edit Mode is on, since there's nothing left to unlock.

Changed

• Read-only by default; write tools require Edit Mode (breaking) — UI_ENABLE_CONTENT_REPLACEMENT now gates write tools at registration time instead of call time. When unset (default), tools/list advertises the 4 read-only Bear-domain tools (bear-search-notes, bear-open-note, bear-find-untagged-notes, bear-list-tags) plus bear-capabilities — 5 entries total; the 8 write tools (bear-create-note, bear-add-text, bear-replace-text, bear-add-file, bear-add-tag, bear-archive-note, bear-rename-tag, bear-delete-tag) are absent entirely. The previous behavior — registering all 12 tools but failing only bear-replace-text calls at runtime with a "Content replacement is not enabled" error — is gone, along with that error message. The MCP instructions field now tells the LLM how to unlock writes when the gate is closed (the env var name plus the Claude Desktop toggle path), so the read-only mode is discoverable without external docs. Existing installs that did not set the var will see the 8 write tools disappear from tools/list (and bear-capabilities appear in their place) until they enable Edit Mode (Claude Desktop: Settings → Extensions → Configure → toggle Edit Mode; CLI: set UI_ENABLE_CONTENT_REPLACEMENT=true). The OS env var name and the MCPB user-config key (enable_content_replacement) are unchanged so saved settings carry over.
• MCPB user-config label "Content Replacement" renamed to "Edit Mode" — visible in Claude Desktop's Settings → Extensions → Configure (Bear Notes). The underlying user-config key (enable_content_replacement) and env var (UI_ENABLE_CONTENT_REPLACEMENT) are unchanged; existing toggle state is preserved.
• Search ranks results by relevance — bear-search-notes now ranks notes by how well they match your query, prioritizing titles and bodies over OCR-extracted text from attachments. The most relevant notes surface first instead of the most recently edited; multi-word queries like quarterly planning offsite notes rank notes covering more of the query terms higher.
• bear-search-notes returns up to 30 results by default (was 50) — the cap is a default, not a ceiling: callers can pass limit to request more, and the response always includes the un-capped match count plus a hint for retrieving all. The lower default trims long-tail noise from common-word matches and reduces LLM context spent on results an agent rarely uses.
• Tag features keep working through Bear schema updates — tag search and pinned-tag filters now resolve Bear's internal join-table IDs at runtime instead of relying on hardcoded names, so a future Bear schema renumber won't silently break them.
• bear-add-file enforces a stricter input policy (breaking) — rejects symbolic links, non-regular files (directories, devices, FIFOs), empty files, and any file larger than 25 MB. Inputs that previously succeeded under one of these conditions now return an error. Most callers will not notice; agents passing iCloud/Drafts paths that resolve through a symlink will need to resolve to the real path first.
• License changed from MIT to Apache 2.0 — same broadly-permissive posture, plus an explicit patent grant. End users see no functional change; redistributors of derivative works must keep the new NOTICE attribution. See LICENSE.md.

Removed

• bear-add-file no longer accepts base64_content (breaking) — pass file_path instead. Sending base64 through tool input wasted thousands of LLM tokens per attachment for no benefit; the server has read files from disk natively since 2.9.0. Existing callers that built base64 blobs must write them to a file on disk and pass the path.
• Substring matching in bear-search-notes (breaking) — search now matches whole words rather than partial fragments, so a query for engin no longer matches engineering. Use the full word (engineering) instead, or pick a more specific keyword from the same note. Existing search prompts that relied on partial-word matches may return different result sets under v3.0.0.

---

Download bear-notes-mcpb-20260511.mcpb to install the extension.