@iflow-mcp/dearcloud09-logseq-mcp 1.0.0

package/README.md

@@ -0,0 +1,302 @@
+# Logseq MCP Server
+
+[![License: Polyform Noncommercial](https://img.shields.io/badge/License-Polyform%20NC-red.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
+
+> **Let AI read and write your Logseq graph directly via MCP**
+
+[한국어 README](README.ko.md)
+
+Talk to Claude and say "add this to today's journal", "find what I did last week", "show me all pages linked to this one" - and it just works.
+
+---
+
+## Why This?
+
+**Problem**: Logseq is a great PKM tool, but integrating with AI assistants requires constant copy-pasting.
+
+**Solution**: With this MCP server:
+- Claude **directly** writes to your journal (no copy-paste)
+- **Search and summarize** past entries (maintain context)
+- **Navigate connections** between pages (backlinks, graph)
+- **Auto-generate** daily journals with templates
+
+```
+You: "Summarize today's meeting notes and add them to my journal"
+Claude: [writes directly to Logseq via logseq-mcp]
+        "Done! Added to today's journal. Anything else?"
+```
+
+---
+
+## Is This For You?
+
+### Good fit if you...
+
+- Use Logseq as your **primary PKM**
+- Use **Claude Code or Claude Desktop** regularly
+- Want to **delegate** note management to AI
+- Use **local file-based** Logseq (not Logseq Sync)
+
+### Not for you if...
+
+- Using **Logseq Sync** (requires local file access)
+- **Obsidian** user (different MCP server needed)
+- Have sensitive info in notes and **uncomfortable with AI access**
+- Use **org-mode** instead of Markdown (not yet supported)
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Page CRUD** | Create, read, update, delete pages + property support |
+| **Search** | Full-text search + tag/folder filtering |
+| **Graph Navigation** | Links, backlinks, page relationship traversal |
+| **Journal** | Access today's/specific date journals + templates |
+| **Content Logging** | Log articles, books, movies, exhibitions to journal |
+| **Resources** | Expose graph pages as MCP resources |
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+git clone https://github.com/dearcloud09/logseq-mcp.git
+cd logseq-mcp
+npm install
+npm run build
+```
+
+### 2. Configure
+
+**Claude Code** (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "logseq": {
+      "command": "node",
+      "args": ["/path/to/logseq-mcp/dist/index.js"],
+      "env": {
+        "LOGSEQ_GRAPH_PATH": "/path/to/your/logseq/graph"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "logseq": {
+      "command": "node",
+      "args": ["/path/to/logseq-mcp/dist/index.js"],
+      "env": {
+        "LOGSEQ_GRAPH_PATH": "/path/to/your/logseq/graph"
+      }
+    }
+  }
+}
+```
+
+### 3. Verify
+
+Ask Claude: "Show me my Logseq page list"
+
+---
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_pages` | List all pages with metadata (tags, links, backlinks) |
+| `read_page` | Read page content and metadata |
+| `create_page` | Create new page (with property support) |
+| `update_page` | Update page content |
+| `delete_page` | Delete a page |
+| `append_to_page` | Append content to existing page |
+| `search_pages` | Search by content/title + tag/folder filters |
+| `get_backlinks` | Get pages that reference a specific page |
+| `get_graph` | Get page connection graph data |
+| `get_journal` | Get today's or specific date's journal |
+| `create_journal` | Create journal with optional template |
+| `add_article` | Add article to journal (title, summary, tags, URL, highlights) |
+| `add_book` | Add book to journal (title, author, tags, memo) |
+| `add_movie` | Add movie to journal (title, director, memo) |
+| `add_exhibition` | Add exhibition to journal (title, venue, artist, memo) |
+
+---
+
+## Usage Examples
+
+```
+"Show me today's journal"
+"Add this content to 'Project A' page: ..."
+"Find all pages with #meeting tag"
+"What pages are connected to my Goals page?"
+"Search for TODO items in last week's journals"
+"Create a new page called 'Reading List'"
+"Summarize our conversation and save it as an article in my journal"
+```
+
+---
+
+## Logseq Graph Structure
+
+```
+your-graph/
+  journals/     # Daily journals (2024_01_15.md format)
+  pages/        # Regular pages
+  logseq/       # Logseq settings
+  whiteboards/  # Whiteboards
+```
+
+---
+
+## Security
+
+- Path traversal protection (graph-only access)
+- Symlink/hardlink attack prevention
+- Input validation and sanitization
+- DoS protection (content size limits)
+- Error message sanitization
+
+---
+
+## Troubleshooting
+
+### "LOGSEQ_GRAPH_PATH environment variable is required"
+
+Set `LOGSEQ_GRAPH_PATH` in your configuration file.
+
+### MCP server not recognized by Claude
+
+1. Restart Claude Code/Desktop
+2. Verify path is absolute (`/Users/...` format)
+3. Ensure `npm run build` was executed
+
+### Pages not showing up
+
+- Check if `.md` files exist in `journals/` or `pages/`
+- Verify you're using **local graph** (not Logseq Sync)
+
+### org-mode files not reading
+
+Currently **Markdown only**. org-mode support planned for future.
+
+---
+
+## Korean-Specific Features
+
+This project includes features optimized for Korean users:
+
+### Daily Automation (Optional)
+
+Auto-generate daily journal with weather (Korea only - uses Naver Weather) and diary template.
+
+1. Copy and edit plist file:
+```bash
+cp com.logseq.daily-automation.plist.example ~/Library/LaunchAgents/com.logseq.daily-automation.plist
+# Edit the file to replace /path/to/ with your actual paths
+```
+
+2. Load launchd agent:
+```bash
+launchctl load ~/Library/LaunchAgents/com.logseq.daily-automation.plist
+```
+
+3. Test manually:
+```bash
+./run-daily-automation.sh
+```
+
+Generated template structure:
+```markdown
+- [[일기]]
+  - [[날씨]]
+    - {weather info}
+  - [[오늘의 일기]]
+    - [[행복도]]
+      - [[오늘의 행복]]
+    - [[오늘의 컨디션]]
+      - [[수면]]
+        - 취침:
+        - 기상:
+        - 질: /5
+    - [[오늘의 생각]]
+  - [[Tasks]]
+    - TODO
+    - [[오늘 잘 해낸 일]]
+  - [[TIL]]
+```
+
+See [Korean README](README.ko.md) for more details.
+
+### Cultural Content Structure
+
+`add_book`, `add_movie`, `add_exhibition` tools use Korean wikilink structure (`[[문화]]`). Customize the templates in `src/index.ts` for your language.
+
+---
+
+## Development
+
+```bash
+# Development mode (watch)
+npm run dev
+
+# TypeScript build
+npm run build
+
+# Production run
+npm start
+```
+
+### Project Structure
+
+```
+src/
+  index.ts    # MCP server entry point, tool handlers
+  types.ts    # TypeScript type definitions
+  graph.ts    # Graph filesystem operations
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome!
+
+1. Fork this repo
+2. Create feature branch (`git checkout -b feature/amazing`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing`)
+5. Open a Pull Request
+
+### Ideas for contribution
+
+- [ ] org-mode support
+- [ ] Logseq property search
+- [ ] Whiteboard support
+- [ ] Better graph visualization data
+- [ ] i18n for templates
+
+---
+
+## License
+
+[Polyform Noncommercial 1.0.0](LICENSE) - Free for personal and noncommercial use.
+
+---
+
+## Related
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Logseq](https://logseq.com/)
+- [Claude Code](https://claude.ai/code)

package/add-today-dairy.js

@@ -0,0 +1,165 @@
+/**
+ * Logseq Daily Note 자동 생성 스크립트
+ * 매일 실행하여 오늘의 일기 템플릿 + 날씨 정보를 자동으로 추가
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { WeatherScraper } from './dist/weather-scraper.js';
+
+// 설정
+const LOGSEQ_GRAPH_PATH = process.env.LOGSEQ_GRAPH_PATH;
+if (!LOGSEQ_GRAPH_PATH) {
+  console.error('Error: LOGSEQ_GRAPH_PATH environment variable is required');
+  process.exit(1);
+}
+const JOURNALS_PATH = join(LOGSEQ_GRAPH_PATH, 'journals');
+
+/**
+ * KST 기준 오늘 날짜 가져오기
+ */
+function getKSTDate() {
+  const now = new Date();
+  const kstOffset = 9 * 60; // KST는 UTC+9
+  const utcTime = now.getTime() + now.getTimezoneOffset() * 60000;
+  return new Date(utcTime + kstOffset * 60000);
+}
+
+/**
+ * 날짜를 저널 파일명 형식으로 변환 (yyyy_MM_dd.md)
+ */
+function formatDateForFilename(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}_${month}_${day}.md`;
+}
+
+/**
+ * 일기 템플릿 생성 (날씨 정보 포함)
+ */
+async function generateTemplate(weatherLines) {
+  const lines = ['- [[일기]]'];
+
+  // 날씨 섹션
+  lines.push('\t- [[날씨]]');
+  if (weatherLines && weatherLines.length > 0) {
+    for (const line of weatherLines) {
+      lines.push(`\t\t- ${line}`);
+    }
+  } else {
+    lines.push('\t\t- 날씨 정보 없음');
+  }
+
+  // 오늘의 일기 섹션
+  lines.push('\t- [[오늘의 일기]]');
+  lines.push('\t\t- [[행복도]]');
+  lines.push('\t\t\t- [[오늘의 행복]]');
+  lines.push('\t\t- [[오늘의 컨디션]]');
+  lines.push('\t\t\t- [[수면]]');
+  lines.push('\t\t\t\t- 취침:');
+  lines.push('\t\t\t\t- 기상:');
+  lines.push('\t\t\t\t- 질: /5');
+  lines.push('\t\t- [[오늘의 생각]]');
+
+  // Tasks 섹션
+  lines.push('\t- [[Tasks]]');
+  lines.push('\t\t- TODO ');
+  lines.push('\t\t- [[오늘 잘 해낸 일]]');
+
+  // TIL 섹션
+  lines.push('\t- [[TIL]]');
+
+  return lines.join('\n');
+}
+
+/**
+ * 기존 저널에 템플릿이 있는지 확인
+ */
+function hasTemplate(content) {
+  return content.includes('[[일기]]') || content.includes('[[날씨]]');
+}
+
+/**
+ * 메인 함수
+ */
+async function addTodayDairy() {
+  const today = getKSTDate();
+  const filename = formatDateForFilename(today);
+  const filePath = join(JOURNALS_PATH, filename);
+
+  console.log(`[${new Date().toISOString()}] Logseq Daily Note 자동 생성 시작`);
+  console.log(`대상 파일: ${filePath}`);
+
+  try {
+    // journals 폴더 확인
+    if (!existsSync(JOURNALS_PATH)) {
+      await mkdir(JOURNALS_PATH, { recursive: true });
+      console.log(`journals 폴더 생성: ${JOURNALS_PATH}`);
+    }
+
+    // 기존 파일 내용 확인
+    let existingContent = '';
+    if (existsSync(filePath)) {
+      existingContent = await readFile(filePath, 'utf-8');
+
+      // 이미 템플릿이 있으면 건너뜀
+      if (hasTemplate(existingContent)) {
+        console.log('이미 일기 템플릿이 존재합니다. 건너뜁니다.');
+        return { success: true, message: '이미 템플릿 존재' };
+      }
+    }
+
+    // 날씨 정보 가져오기 (3회 재시도)
+    let weatherLines = null;
+    const weatherScraper = new WeatherScraper();
+
+    for (let attempt = 1; attempt <= 3; attempt++) {
+      try {
+        console.log(`날씨 정보 가져오기 시도 ${attempt}/3...`);
+        const weather = await weatherScraper.getWeatherForDongcheon();
+        if (weather) {
+          weatherLines = weatherScraper.formatWeatherForLogseq(weather);
+          console.log('날씨 정보 수집 성공');
+          break;
+        }
+      } catch (error) {
+        console.error(`날씨 수집 실패 (시도 ${attempt}):`, error.message);
+        if (attempt < 3) {
+          const waitMs = Math.min(1000 * Math.pow(2, attempt - 1), 5000);
+          await new Promise(resolve => setTimeout(resolve, waitMs));
+        }
+      }
+    }
+
+    // 템플릿 생성
+    const template = await generateTemplate(weatherLines);
+
+    // 파일 작성
+    const newContent = existingContent
+      ? existingContent + '\n' + template
+      : template;
+
+    await writeFile(filePath, newContent, 'utf-8');
+    console.log('Daily Note 템플릿 생성 완료!');
+    console.log(`파일: ${filePath}`);
+
+    return { success: true, message: '템플릿 생성 완료' };
+
+  } catch (error) {
+    console.error('오류 발생:', error.message);
+    return { success: false, message: error.message };
+  }
+}
+
+// 실행
+addTodayDairy()
+  .then(result => {
+    console.log('결과:', result);
+    process.exit(result.success ? 0 : 1);
+  })
+  .catch(error => {
+    console.error('치명적 오류:', error);
+    process.exit(1);
+  });

package/com.logseq.daily-automation.plist.example

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.logseq.daily-automation</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>/path/to/logseq-mcp/run-daily-automation.sh</string>
+    </array>
+
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Hour</key>
+        <integer>6</integer>
+        <key>Minute</key>
+        <integer>0</integer>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>/path/to/logseq-mcp/launchd.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/path/to/logseq-mcp/launchd.error.log</string>
+
+    <key>RunAtLoad</key>
+    <false/>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>LOGSEQ_GRAPH_PATH</key>
+        <string>/path/to/your/logseq/graph</string>
+        <key>WEATHER_LOCATION</key>
+        <string>서울</string>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin</string>
+    </dict>
+</dict>
+</plist>

package/dist/graph.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Logseq Graph Service
+ * Handles file system operations for Logseq graphs
+ */
+import type { Page, PageMetadata, SearchResult, Graph } from './types.js';
+export declare class GraphService {
+    private graphPath;
+    private pagesPath;
+    private journalsPath;
+    constructor(graphPath: string);
+    /**
+     * List all pages in the graph
+     */
+    listPages(folder?: string): Promise<PageMetadata[]>;
+    private collectAllPages;
+    /**
+     * Read a page by path or name
+     */
+    readPage(pathOrName: string): Promise<Page>;
+    /**
+     * Validate page name (whitelist approach for security)
+     */
+    private validatePageName;
+    /**
+     * Create a new page
+     */
+    createPage(name: string, content: string, properties?: Record<string, unknown>): Promise<Page>;
+    /**
+     * Update an existing page
+     */
+    updatePage(pathOrName: string, content: string, properties?: Record<string, unknown>): Promise<Page>;
+    /**
+     * Delete a page
+     */
+    deletePage(pathOrName: string): Promise<void>;
+    /**
+     * Append content to a page
+     */
+    appendToPage(pathOrName: string, content: string): Promise<Page>;
+    /**
+     * Search pages
+     */
+    searchPages(query: string, options?: {
+        tags?: string[];
+        folder?: string;
+    }): Promise<SearchResult[]>;
+    /**
+     * Get backlinks for a page
+     */
+    getBacklinks(pathOrName: string): Promise<PageMetadata[]>;
+    /**
+     * Get graph data
+     */
+    getGraph(options?: {
+        center?: string;
+        depth?: number;
+    }): Promise<Graph>;
+    /**
+     * Get journal page for a date
+     */
+    getJournalPage(date?: string): Promise<Page | null>;
+    /**
+     * Create journal page
+     */
+    createJournalPage(date?: string, template?: string): Promise<Page>;
+    /**
+     * Append content to journal page (creates if doesn't exist)
+     */
+    appendToJournalPage(date?: string, content?: string): Promise<Page>;
+    /**
+     * Validate content size (prevents DoS attacks)
+     */
+    private validateContentSize;
+    /**
+     * Check if path is a symlink (prevents symlink escape attacks)
+     */
+    private checkSymlink;
+    /**
+     * Check if path is a regular file (prevents symlink/hardlink attacks)
+     * More strict than checkSymlink - also detects hardlinks to external files
+     */
+    private checkRegularFile;
+    /**
+     * Validate that a path is within the graph directory (prevents path traversal attacks)
+     */
+    private validatePath;
+    private resolvePath;
+    private extractTags;
+    private extractLinks;
+    private parseProperties;
+    /**
+     * Validate and sanitize properties (prevents injection attacks)
+     */
+    private validateProperties;
+    private buildContent;
+    private getTodayString;
+}