feat: add DB-mode property support (read & write)

[arndjan]

Summary

Logseq's DB-mode stores class/tag properties as Datascript entities (:user.property/* idents) rather than inline markdown key:: value pairs. This means get_page_content currently returns no properties for DB-mode graphs.

This PR adds:

• Reading: get_page_content now queries Datascript for :user.property/* attributes on each block and renders them as key:: value lines, so DB-mode properties show up alongside markdown-mode properties
• Writing: new set_block_properties tool that accepts human-readable property names (e.g. "Content status"), resolves them to internal idents, and calls upsertBlockProperty

Changes

• logseq.py: Add datascript_query(), get_block_db_properties(), get_blocks_db_properties(), set_block_db_property(), resolve_property_ident() and helper methods
• tools.py: Extend _format_block_tree() to render DB-mode properties; add SetBlockPropertiesToolHandler
• server.py: Register set_block_properties tool handler

How it works

1. Reading: After fetching the block tree, we query each block's entity for attributes starting with :user.property/. For each, we resolve the property's display name (via entity title lookup) and the value's display name (entity reference → title). Results are rendered as key:: value lines in the output.

2. Writing: The set_block_properties tool takes {display_name: value} pairs, scans all :db/ident entries for :user.property/* matches, compares entity titles case-insensitively, then calls upsertBlockProperty with the resolved ident.

Test plan

• Tested with Logseq DB-mode graph containing tagged blocks with class properties
• get_page_content shows properties like Content status:: kiem, Topics:: waarden verandering
• set_block_properties resolves display names and updates values
• Markdown-mode graphs continue to work unchanged (properties already in block content)

🤖 Generated with Claude Code

[ergut]

Code Review

Hi @arndjan — thanks for this PR! The feature itself is genuinely useful and I can see you've tested it against a real DB-mode graph. Before merging, I'd like to request a few changes to make sure existing Markdown-mode users aren't affected.

---

Context: DB mode is still in beta

As of March 2026, Logseq DB mode is still opt-in and in beta — the Logseq team explicitly recommends using DB graphs for testing only, as data loss is possible. The project is on a path toward v2.0.0 (DB-only), but a stable release before Q3 2026 is uncertain. Given that the vast majority of current users of this MCP server are on Markdown/file-based graphs, we need to make sure this PR does not affect them in any way — either in performance or output correctness.

That said, we're not rejecting this because of DB mode's beta status. Logseq has been clear that v2.0.0 is the future — file-based graphs are in maintenance mode with no new features planned. Being early with DB support is valuable, and the API calls this PR uses (logseq.DB.datascriptQuery, upsertBlockProperty) are part of the official API surface. The right approach is an opt-in flag that completely isolates Markdown users while giving DB-mode users working functionality today.

---

Required changes

1. Gate DB-mode queries behind a feature flag (critical)

Right now, get_blocks_db_properties is called unconditionally on every get_page_content invocation. Markdown-mode users will pay the cost of N+1 Datascript API calls even though these queries are irrelevant to them. If the LogSeq API returns an error (e.g. MethodNotExist), the exception is silently swallowed — which is fine, but the latency hit happens before that.

Please add an opt-in mechanism. The simplest approach is an environment variable:

# In logseq.py or tools.py
import os
LOGSEQ_DB_MODE = os.getenv("LOGSEQ_DB_MODE", "false").lower() == "true"

Then in run_tool:

if LOGSEQ_DB_MODE:
    try:
        db_properties = api.get_blocks_db_properties(blocks)
    except Exception as e:
        logger.warning(f"Could not fetch DB-mode properties: {e}")

This means Markdown-mode users see zero change in behavior or performance.

2. Fix potential double-rendering of Markdown-mode properties

The new property rendering loop in _format_block_tree introduces a risk of duplicate key:: value lines for Markdown-mode graphs. The original comment that was removed — "Properties are already included in the content by Logseq" — was intentional. Logseq embeds inline properties directly in the block's content string, so rendering block.get("properties", {}) on top of that will produce duplicates.

If the intent is only to support DB-mode properties (which are not in content), the Markdown-mode properties block should either be removed entirely, or strictly guarded behind the same LOGSEQ_DB_MODE flag:

# Only render db_properties if in DB mode — markdown properties are already in content
if db_properties and block_uuid in db_properties:
    for key, value in db_properties[block_uuid].items():
        lines.append(f"{indent}  {key}:: {value}")

3. Address the N+1 query problem

get_blocks_db_properties calls get_block_db_properties once per block, which in turn fires multiple HTTP requests (one to get attributes, then one per property to resolve names, then one per value to resolve titles). A page with 20 blocks and 3 properties each = 80+ API round-trips per get_page_content call.

Consider batching this with a single Datascript query that fetches all [?block ?attr ?val] triples for all block IDs in one shot. Something like:

[:find ?block ?attr ?val
 :where
 [?block ?attr ?val]
 [(clojure.string/starts-with? (str ?attr) ":user.property/")]]

Even a partial improvement (e.g. resolving all property names in one pass) would significantly reduce the API call count.

4. Add tests

No tests were added for the new logseq.py methods or the SetBlockPropertiesToolHandler. At minimum, please add unit tests with mocked API responses for:

• get_block_db_properties — happy path, empty result, API failure
• resolve_property_ident — found, not found
• _format_block_tree with db_properties populated

---

Minor notes

• set_block_db_property in logseq.py is essentially a duplicate of the existing _upsert_block_property — consider reusing or consolidating these.
• The datascript_query docstring says "Returns: Query results" but doesn't describe the shape (list of tuples). Worth documenting since it's a public method.
• The CLAUDE.md for this project documents the env var pattern for configuration — following that convention for LOGSEQ_DB_MODE would be consistent.

---

Summary

The feature fills a real gap for DB-mode users and the implementation logic is sound. The main blocker is the unconditional Datascript querying that runs for all users regardless of mode. Once there's a flag to opt in, the double-render risk is addressed, and tests are added, I'd be happy to merge this.

Thanks for the detailed PR description — the "how it works" section made review much easier.

[arndjan]

Hey Salih, thanks for the thorough review — really appreciate you taking the time to lay out all the details so clearly.

Decided to put in some extra effort this Friday evening and worked through all your feedback points. Here's what I've done across four commits:

Feature flag (LOGSEQ_DB_MODE) — All DB-mode code is now gated behind a LOGSEQ_DB_MODE=true env var. Markdown-mode users see zero change in behavior or performance. The set_block_properties tool returns a clear error message when the flag isn't set. This follows the existing env var pattern in tools.py.

Double-rendering fix — The block.properties dict rendering and the db_properties lookup are both behind the flag now, so Markdown-mode users won't get duplicate key:: value lines.

Tests — Added 18 unit tests covering get_block_db_properties, resolve_property_ident, _format_block_tree with DB properties, and feature flag integration. Also fixed the integration test handler count (was still at 15, should be 16 with set_block_properties).

N+1 batching — Refactored get_blocks_db_properties to batch the title and ident resolution. Instead of resolving each property name and value individually, it now collects all entity IDs and resolves them in two batch queries. For a page with 20 blocks and 3 properties each, this brings it down from ~200 round-trips to ~22. Both batch methods have fallbacks to individual queries if the batched datascript query doesn't work.

Cleanup — Removed the duplicate set_block_db_property method (was identical to _upsert_block_property), improved the datascript_query docstring with return shape documentation.

Glad to make this small contribution to the project — mcp-logseq has been really useful for my workflow. Let me know if there's anything else you'd like me to adjust!