logseq-api-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that gives AI assistants access to Logseq knowledge bases. It ships 21 standard tools (read + write), all discovered and registered automatically.

Key Innovation: Zero-configuration tool management — drop a .py file into src/tools/ and it is auto-discovered, imported, and registered with the MCP server.

Core Architecture

Module Map

src/
├── server.py          # FastMCP entry point; calls setup_logging() + register_all_tools()
├── registry.py        # Iterates tools.__all__ and registers each with the MCP server
├── logging_setup.py   # setup_logging() rotating-file logger; get_logger() child logger
├── client/
│   ├── logseq_client.py   # LogseqClient — async aiohttp wrapper for every Logseq API call
│   ├── config.py          # LogseqConfig frozen dataclass; load_config() reads env vars
│   └── exceptions.py      # LogseqAPIError, LogseqAuthError, LogseqNotFoundError
├── parser/
│   └── markdown.py        # parse_content(text) → ParsedContent(blocks, properties)
├── privacy/
│   └── exclude_tags.py    # filter_pages(), is_page_excluded(), extract_tags()
└── tools/
    ├── __init__.py        # Scans *.py, imports each, adds public functions to __all__
    ├── formatters/        # Pure formatter functions (pages.py, blocks.py, search.py)
    └── *.py               # 21 tool modules — one public async function each

Dynamic Tool Discovery

1. src/tools/__init__.py uses importlib to import every *.py file in src/tools/ (skipping _* and formatters/).
2. It adds any function where obj.__module__ == module.__name__ to __all__.
3. src/registry.py iterates tools.__all__ and calls mcp_server.tool()(fn) for each.

Critical rule: A tool function must be defined in its own file — not imported from another module — for dynamic discovery to pick it up.