Istefox-dt-mcp 0.1.0 — open-source MCP connector for DEVONthink 4 (MIT, local-only)

DEVONthink Artificial Intelligence
1

Hi all,

I’ve just released the first public version of istefox-dt-mcp, an open-source MCP (Model Context Protocol) connector that exposes DEVONthink 4
to LLM clients like Claude Desktop, Cursor, and Cline. Everything runs locally on the Mac — no data leaves the machine.

Repo: GitHub - istefox/istefox-dt-mcp: MCP server for DEVONthink 4 - best-in-class connector with RAG-augmented search · GitHub
License: MIT (clean-room implementation)
Version: 0.1.0

Why another DT connector?

There’s already an excellent prior project by @dvcrn for DT3, which I deliberately did not look at while building this — istefox-dt-mcp is a
clean-room MIT codebase, and the design targets DT4 specifically. Different priorities:

  • DT4-first: the JXA bridge uses Application("DEVONthink") (DT4) with feature gating for DT3 best-effort. No assumptions inherited from the
    3.x dictionary.
  • Local-only by default: append-only SQLite audit log of every operation, optional RAG embeddings via sentence-transformers running locally.
  • Safety on writes: every write tool (file_document, bulk_apply) is dry_run=true by default. Apply requires a short-TTL confirm_token;
    each operation stores its before-state and is reversible via audit_id.

The six tools

  • list_databases — open DBs with 5-min cache
  • search — BM25 across records (vector hybrid is opt-in)
  • find_related — wraps DT’s native See Also / Compare
  • ask_database — BM25 + answer synthesis
  • file_document — move/tag a single record (dry-run preview → confirm → apply)
  • bulk_apply — batch operations with per-record selective apply

JXA scripts are wrapped defensively — DT4 raises -1700 (errAECoercionFail) on a number of special record types, and a few API quirks made
reference_url unreliable as a primary key, so I fall back to UUIDs.

Install

Drag-and-drop .mcpb bundle in Claude Desktop (Settings → Extensions). The bundle handles uv detection (Homebrew, mise, asdf, custom path via
ISTEFOX_UV_BIN), so no Python env to manage on the user side. For other MCP clients, uv run istefox-dt-mcp from the cloned repo works.

A short demo GIF of the dry-run → confirm flow is in the README. The doctor subcommand surfaces TCC permission issues (the -1743 “Apple Events
not allowed” trap) early and tells you exactly which terminal/app needs the entitlement.

Roadmap (0.2.0)

  • Cross-corpus RAG benchmark (≥3 corpora, ≥2 early adopter) to flip the default embedding model — see
    ADR-008
  • 3-state drift detection on undo (no drift / partially undone / hostile drift)
  • HTTP transport + OAuth multi-device
  • Smart-rule installer for sync sidecar (currently planned, not in 0.1.0)

Feedback I’d specifically appreciate from this community

  1. Edge cases on JXA — record types or DT layouts where the safe wrapper still trips
  2. Smart-rule integration patterns — the long-term plan is a smart rule → sidecar JSON pipeline (with hash-based reconciliation), but I want to
    validate the pattern with people who’ve shipped real smart rules
  3. Mixed-language databases — the connector targets IT/EN/FR/DE for retrieval; reports from German/French heavy users especially welcome
  4. Backward compat with DT3 — feature-gated and best-effort today, would be useful to know what fails for those who can’t or don’t want to upgrade

Not affiliated with or endorsed by DEVONtechnologies — this is a personal project. Bug reports and feature requests on GitHub. Cheers!
Stege

2 Likes