What's Changed

• feat: resolve UUID page references in DB mode (#32)
• fix: Windows compatibility — replace fcntl with portalocker (#38)
• feat: add get_block tool (#31)
• fix: search broken in DB mode (#33)
• chore: add MIT license and fix newlines in markdown tables (#36)

Vector Search — Semantic search for your Logseq notes

This is the biggest feature release since v1.0. Your Logseq notes are now searchable by meaning, not just keywords — powered entirely by local models. No data ever leaves your machine.

Ask things like "What did I write about shadow work?" and find your Jung-related notes, even if they never mention those exact words.

Note: This release supersedes v1.6.0, which was missing the read-only MCP server refactor and several bug fixes. Install 1.6.1 from PyPI.

How it works

1. Ollama generates embeddings locally (e.g. qwen3-embedding:4b)
2. LanceDB stores vectors in an embedded database (~3,000 chunks for a 654-page graph)
3. Hybrid search combines vector similarity + full-text matching with Reciprocal Rank Fusion
4. Results include relevance labels (high / medium / weak match) so the AI client can judge what's worth presenting

New MCP Tools

New CLI: logseq-sync

logseq-sync --once      # One-shot incremental sync
logseq-sync --watch     # Continuous sync on file changes
logseq-sync --rebuild   # Drop and re-index from scratch
logseq-sync --status    # Show current DB state

Architecture: Single-Writer, Multi-Reader

The MCP server is a read-only consumer of the vector DB. All writes go through logseq-sync. This makes it safe to run multiple MCP server instances against the same DB (e.g. in containerized setups).

logseq-sync --watch          (single writer)
  └── writes → ~/.logseq-vector/db/

MCP servers (any number)     (read-only)
  └── reads  → ~/.logseq-vector/db/

An inter-process file lock (fcntl.flock) prevents concurrent syncs. State keys use relative paths for cross-mount portability.

Bug fixes over v1.6.0

• Read-only MCP server — all DB writes delegated to logseq-sync (single-writer principle)
• Graph-path guard prevents data wipe when vault is inaccessible (container safety)
• State migration from absolute to relative path keys
• Inter-process file lock for concurrent sync protection
• LanceDB version mismatch detection in open_readonly()

Getting Started

Vector search is fully opt-in — existing users are unaffected.

pip install "mcp-logseq[vector]"

See VECTOR_SEARCH.md for prerequisites, configuration, and first sync walkthrough.

Technical Details

• Embedding model: any Ollama-compatible model (tested with qwen3-embedding:4b, 2560 dims)
• Chunking: page-level with configurable minimum length
• Incremental sync: only changed files are re-embedded (content hash comparison)
• FTS indexes: separate full-text indexes on text and page fields
• 69 new unit tests across 7 test files

Vector Search — Semantic search for your Logseq notes

This is the biggest feature release since v1.0. Your Logseq notes are now searchable by meaning, not just keywords — powered entirely by local models. No data ever leaves your machine.

Ask things like "What did I write about shadow work?" and find your Jung-related notes, even if they never mention those exact words.

How it works

1. Ollama generates embeddings locally (e.g. qwen3-embedding:4b)
2. LanceDB stores vectors in an embedded database (~3,000 chunks for a 654-page graph)
3. Hybrid search combines vector similarity + full-text matching with Reciprocal Rank Fusion
4. Results include relevance labels (high / medium / weak match) so the AI client can judge what's worth presenting

New MCP Tools

New CLI: logseq-sync

logseq-sync --once      # One-shot incremental sync
logseq-sync --watch     # Continuous sync on file changes
logseq-sync --rebuild   # Drop and re-index from scratch
logseq-sync --status    # Show current DB state

Architecture: Single-Writer, Multi-Reader

The MCP server is a read-only consumer of the vector DB. All writes go through logseq-sync. This makes it safe to run multiple MCP server instances against the same DB (e.g. in containerized setups).

logseq-sync --watch          (single writer)
  └── writes → ~/.logseq-vector/db/

MCP servers (any number)     (read-only)
  └── reads  → ~/.logseq-vector/db/

An inter-process file lock (fcntl.flock) prevents concurrent syncs. State keys use relative paths for cross-mount portability.

Getting Started

Vector search is fully opt-in — existing users are unaffected.

pip install "mcp-logseq[vector]"

See VECTOR_SEARCH.md for prerequisites, configuration, and first sync walkthrough.

Technical Details

• Embedding model: any Ollama-compatible model (tested with qwen3-embedding:4b, 2560 dims)
• Chunking: page-level with configurable minimum length
• Incremental sync: only changed files are re-embedded (content hash comparison)
• FTS indexes: separate full-text indexes on text and page fields
• 69 new unit tests across 7 test files

New Features

DB-mode property support (opt-in)

Logseq's DB-mode stores class/tag properties as Datascript entities rather than inline key:: value pairs — meaning get_page_content previously returned no properties for DB-mode graphs. This release adds full read and write support.

Set LOGSEQ_DB_MODE=true to enable:

• get_page_content now queries Datascript for :user.property/* attributes on each block and renders them as key:: value lines alongside regular content
• New set_block_properties tool: set properties by display name (e.g. Content status), automatically resolves to internal :user.property/* idents and calls upsertBlockProperty
• Batched Datascript queries minimize API round-trips (from ~200 to ~N+2 per page)

Markdown/file-based graph users: no changes. All DB-mode code is strictly gated behind the LOGSEQ_DB_MODE=true env var.

Configuration

# Claude Code
claude mcp add mcp-logseq \
  --env LOGSEQ_API_TOKEN=your_token \
  --env LOGSEQ_DB_MODE=true \
  -- uv run --with mcp-logseq mcp-logseq

Notes

• Logseq DB-mode is still in beta — this feature is provided for early adopters
• Thanks to @arndjan for this contribution!

Bug Fixes

• Inline properties rendered as separate blocks: Consecutive key:: value lines (e.g. type:: video, source:: ..., channel:: ...) were each becoming their own block (separate bullet). They are now grouped into a single block with lines joined by \n , matching Logseq's native inline property format where all properties appear as indented lines under one bullet.

Bug Fixes

• Inline properties collapsed onto one line: create_page now correctly renders each key:: value property as its own block. Previously, consecutive property lines (e.g. type:: video, source:: ..., channel:: ...) were joined into a single space-separated block. Each property is now an independent block, matching native Logseq behavior.

Bug Fixes

• Page-level properties: create_page and update_page now store properties at the page entity level (createPage 2nd arg / setPageProperties) instead of on the first content block. Properties now appear in the Logseq page info panel and match (page-property ...) queries.
• Double-wrap fix: get_page_content no longer double-wraps block content that already starts with a list marker (-, *, +).

🧱 Block CRUD is Now Complete

v1.4.0 adds update_block, the final piece of block-level CRUD. You can now read, create, update, and delete any block by UUID.

🛠️ New Tool

update_block — Edit the content of an existing block by UUID.

block_uuid  (required) — UUID of the block to edit
content     (required) — New text to replace the block's current content

Returns ✅ Successfully updated block '<uuid>' on success, ❌-prefixed message on error.

📦 Installation / Update

# uvx (no install needed, always latest)
uvx mcp-logseq

# or pin to this version
pip install mcp-logseq==1.4.0

🧪 Tests

203 tests passing. Closes #17.

🚀 What's New

v1.3.0 brings a major expansion: 14 tools (up from 6), two critical bug fixes, and a batch of reliability improvements based on thorough code review.

🛠️ New Tools

🐛 Bug Fixes

• LOGSEQ_API_URL not respected — all handlers were hardcoded to 127.0.0.1:12315; the env var is now properly parsed and passed to every API client
• Nested block hierarchy silently lost — _append_block_recursive was ignoring parent_uuid and flattening all blocks to root level; now uses insert_block_as_child for proper nesting
• Search snippet filtering broken — pages-content results were controlled by include_blocks instead of include_pages; snippets were also missing from the total results count
• JSON format returned Python repr — get_page_content with format=json returned str(result) instead of valid JSON
• DSL injection via property names — find_pages_by_property escaped values but not property names; property names are now validated against [a-zA-Z0-9_-]
• Duplicated HTTP call — remove_block and delete_block were identical; remove_block now delegates to delete_block

✨ Improvements

• LOGSEQ_VERIFY_SSL env var — control TLS verification explicitly; auto-enables for https:// URLs, disabled by default for http://
• Namespace tools now return friendly errors — previously bubbled raw exceptions; now return ❌-prefixed messages like other tools

📦 Installation

# With uvx (recommended, no install needed)
claude mcp add-json mcp-logseq '{
  "command": "uvx",
  "args": ["mcp-logseq"],
  "env": {
    "LOGSEQ_API_TOKEN": "your_token",
    "LOGSEQ_API_URL": "http://localhost:12315"
  }
}'

# Or with pip
pip install mcp-logseq==1.3.0

🧪 Tests

195 tests passing. New coverage added for:

• InsertNestedBlockToolHandler (5 tests)
• insert_block_as_child (3 tests)
• _append_block_recursive root/nested/children paths (3 tests)
• Integration test now verifies all 14 handlers are registered

🔧 Critical Fixes & Major UX Improvements

🐛 Bug Fixes

• Fix server crash due to file logging permission errors on read-only filesystems
• Improve logging reliability with user cache directory (~/.cache/mcp-logseq/) and fallback handling

🚀 Major UX Improvements

• Zero installation required! Now uses uv --with for automatic dependency management
• Simplified setup - no more pip install step needed
• Enhanced documentation with comprehensive troubleshooting for PATH issues in Claude Desktop

📚 Documentation Updates

• Complete installation guide rewrite using uv best practices
• Added troubleshooting section for spawn uv ENOENT errors
• Updated DEVELOPMENT.md with proper entry points
• Provided full path solutions for different uv installation methods

🔄 Breaking Change (Installation Only)

The recommended installation method has changed from pip install to uv --with. The old method still works, but the new method is more reliable and requires no pre-installation.

New recommended setup:

claude mcp add mcp-logseq \
  --env LOGSEQ_API_TOKEN=your_token \
  -- uv run --with mcp-logseq mcp-logseq

📦 What's Included

• Fixed file logging permissions (server.py:18-35)
• Zero-dependency installation workflow
• Comprehensive PATH troubleshooting guide