# Logseq AI Architecture
## Overview
This project provides AI-powered interactions with Logseq through two interfaces:
1. **MCP Server** - Enables external AI tools (Windsurf, Claude Desktop) to interact with your Logseq graph
2. **Lain** - Embedded AI assistant plugin within the Logseq UI
> "No matter where you go, everyone's connected." - Serial Experiments Lain
Both interfaces share a common core library to maximize code reuse.
## Architecture Diagram
```
┌─────────────────────────────────────────────────────────┐
│ Shared Core Library │
│ (TypeScript - Logseq API interactions) │
│ • searchPages() • createBlock() • getPageContent() │
│ • runDatalogQuery() • updateBlock() • deletePage() │
└───────────────────────┬─────────────────────────────────┘
│
┌─────────────┴─────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────────────┐
│ MCP Server │ │ Lain │
│ (Node.js/stdio) │ │ (Browser-based JS/TS) │
│ │ │ │
│ • Exposes tools to │ │ • UI components (sidebar, │
│ external AI │ │ slash commands, toolbar) │
│ • Calls Logseq │ │ • Calls LLM API directly │
│ HTTP API │ │ • Uses native Plugin API │
└─────────────────────┘ └─────────────────────────────┘
▲ ▲
│ │
Windsurf/Claude Logseq UI
```
## Package Structure
```
logseq-ai/
├── packages/
│ ├── core/ # Shared logic
│ │ ├── src/
│ │ │ ├── logseq-client.ts # HTTP API wrapper
│ │ │ ├── operations/ # Business logic (modular)
│ │ │ │ ├── index.ts # Main exports
│ │ │ │ ├── base.ts # Core page/block operations
│ │ │ │ ├── tasks.ts # Task management
│ │ │ │ ├── journals.ts # Journal & discovery
│ │ │ │ └── helpers.ts # Date/content parsing
│ │ │ ├── types.ts # Shared types
│ │ │ ├── errors.ts # Error classes
│ │ │ └── index.ts # Package exports
│ │ └── package.json
│ │
│ ├── mcp-server/ # MCP server
│ │ ├── src/
│ │ │ ├── index.ts # Server setup
│ │ │ ├── tools/ # Tool definitions
│ │ │ │ ├── page-tools.ts
│ │ │ │ ├── task-tools.ts
│ │ │ │ └── journal-tools.ts
│ │ │ └── handlers/ # Tool handlers
│ │ │ ├── page-handlers.ts
│ │ │ ├── task-handlers.ts
│ │ │ └── journal-handlers.ts
│ │ └── package.json
│ │
│ └── logseq-plugin/ # Lain plugin
│ ├── src/
│ │ ├── main.ts # Plugin entry
│ │ ├── ui/ # React components
│ │ └── agent.ts # LLM orchestration
│ └── package.json
│
├── pnpm-workspace.yaml # pnpm workspace config
├── package.json # Monorepo root
└── tsconfig.base.json
```
## Component Details
### Core Library (`@logseq-ai/core`)
Shared TypeScript library containing:
- **LogseqClient**: HTTP API wrapper for Logseq's local server (default: `http://localhost:12315`)
- **Operations**: High-level functions for common tasks
- **Types**: Shared TypeScript interfaces
The core library is environment-agnostic and works in both Node.js and browser contexts.
### MCP Server (`@logseq-ai/mcp-server`)
Node.js application that implements the Model Context Protocol:
- Communicates via stdio transport
- Exposes Logseq operations as MCP tools
- Connects to Logseq via HTTP API
**Exposed Tools:**
*Page & Block Tools:*
- `search_logseq` - Search pages by title or content
- `get_page` - Retrieve page content
- `list_pages` - List all pages
- `create_page` - Create a new page
- `delete_page` - Delete a page
- `create_block` - Create a new block
- `update_block` - Modify existing block
- `delete_block` - Remove a block
- `query_logseq` - Run Datalog queries
- `get_current_graph` - Get current graph info
*Task Management Tools:*
- `get_tasks` - Get TODO/DOING tasks (optionally filtered by page)
- `create_task` - Create a new task with optional priority, deadline, scheduled date
- `mark_task` - Change task status (TODO, DOING, DONE, CANCELED)
- `set_task_priority` - Set or remove task priority (A, B, C)
- `set_task_deadline` - Set or remove task deadline
- `set_task_scheduled` - Set or remove task scheduled date
*Search & Discovery Tools:*
- `search_tasks` - Search tasks by keyword with optional marker/page filter
- `find_related_pages` - Get backlinks and forward links for a page
*Task Analytics Tools:*
- `get_overdue_tasks` - Get tasks past their deadline
- `get_tasks_due_soon` - Get tasks due within N days
- `get_task_stats` - Get aggregated task statistics
*Journal Tools:*
- `get_today` - Get or create today's journal page
- `append_to_today` - Append content to today's journal
- `get_recent_journals` - Get recent journal entries
- `get_block_backlinks` - Find blocks referencing a given block
### Lain (`logseq-lain`)
Browser-based plugin running inside Logseq:
- Uses Logseq's native Plugin API (no HTTP needed)
- Provides UI components (sidebar chat, slash commands)
- Directly calls LLM APIs (Claude, OpenAI, etc.)
- Orchestrates multi-step agent workflows
## Key Differences
| Aspect | MCP Server | Logseq Plugin |
|--------|------------|---------------|
| **Runtime** | Node.js | Browser (Electron) |
| **Logseq Access** | HTTP API (localhost:12315) | Native Plugin API |
| **LLM Integration** | External AI client | Direct API calls |
| **User Interaction** | External AI chat | In-app UI |
## Prerequisites
### For MCP Server
- Logseq HTTP API server enabled (Settings → Features → HTTP APIs server)
- Authorization token configured
### For Logseq Plugin
- Logseq desktop app
- Developer mode enabled for local plugin development
## Development Workflow
1. **Core first**: Build and test shared operations
2. **MCP Server**: Wrap core in MCP tools, test with AI clients
3. **Plugin**: Add UI layer and LLM orchestration
## Configuration
### Logseq HTTP API
Enable in Logseq: Settings → Features → HTTP APIs server
Default endpoint: `http://localhost:12315/api`
### Environment Variables
```bash
# MCP Server
LOGSEQ_API_URL=http://localhost:12315
LOGSEQ_API_TOKEN=your-token-here
# Plugin (for LLM calls)
ANTHROPIC_API_KEY=your-key-here
# or
OPENAI_API_KEY=your-key-here
```
