$ show ergut/mcp-logseq
mcp-logseq is a Model Context Protocol (MCP) server that bridges AI agents (like Claude) to Logseq knowledge bases. It exposes Logseq's local HTTP API through 15+ tools for reading, creating, updating, and deleting pages and blocks, along with search, DSL queries, and optional semantic vector search via LanceDB. The server supports both stdio and HTTP/SSE transports with security features including namespace/tag-based access control, read-only mode, TLS, and bearer token authentication. The vector database is managed by a separate sync process (logseq-sync) to enforce a single-writer pattern. The codebase is well-architected with clean separation of concerns: a declarative access control system, a pure namespace matching utility, a stateful markdown parser, and an embedder abstraction with Ollama/OpenAI adapters. Configuration is lazy-cached from environment variables and a JSON config file, with no import-time side effects. The test suite is comprehensive with over 50 unit tests and integration tests for HTTP serving. While the project is still in beta, it demonstrates strong engineering practices and provides several reusable components for other MCP server implementations or Logseq integration tools.
The LLM identified 5 files worth highlighting for reuse:
Pure functions for segment-based, case-insensitive namespace matching. `namespace_matches()` and `is_namespace_blocked()` are dependency-free and can be extracted into any project needing hierarchical namespace filtering. Demonstrates careful handling of prefixes, empty strings, and exact vs. recursive matches.
Stateful MarkdownParser that converts markdown (headings, lists, checkboxes, code blocks, tables, math, blockquotes, YAML frontmatter) into Logseq's hierarchical block tree format. The parser is self-contained, handles nested structures correctly, and can be reused as a standalone library for converting markdown to Logseq block batches.
Clean embedder abstraction with `create_embedder()` factory that returns an adapter with `embed()`, `key()`, and `dimensions` methods. Supports Ollama, OpenAI, and OpenAI-compatible providers. The interface is minimal and generic, making it reusable in any project needing pluggable embedding generation.
Pure ASGI (not BaseHTTPMiddleware) bearer token authentication middleware. Avoids buffering SSE streams by directly wrapping the ASGI `send` callable. This pattern is reusable for any ASGI application that needs streaming-safe authentication without modifying the response body.
`ToolHandler` base class that defines a declarative `access_policy` property (list of `AccessPolicy` objects) and enforces them in `run_tool()` before delegating to `_run()`. This pattern allows clean separation of access control from tool logic and can be reused as a base class for any MCP server requiring per-tool authorization.