logseq-mcp 0.0.18 → 0.1.2

package/README.md

@@ -1,47 +1,56 @@
-# Logseq Agent
+# Logseq MCP Agent
 
-A powerful Model Context Protocol (MCP) agent for interacting with Logseq, allowing AI assistants like Claude to access and manipulate your Logseq graph with fine-grained control.
+A powerful AI assistant that connects Logseq with Claude and other LLMs using the Model Context Protocol (MCP).
 
-## Installation
+## What is it?
 
-You can install the Logseq Agent via npm:
+Logseq MCP Agent lets AI assistants like Claude directly interact with your Logseq knowledge graph - search your notes, create content, organize information, and manage tasks.
 
-```bash
-npx logseq-mcp
-```
+MCP (Model Context Protocol) works like a "USB-C port for AI" - providing a standardized way for AI models to connect with your applications and data. This agent implements MCP to give Claude and other LLMs a direct, structured interface to your Logseq knowledge base.
 
-Or install it globally:
+Think of it as giving Claude direct access to your second brain.
 
-```bash
-npm install -g logseq-mcp
-```
+## Key Features
 
-## Quick Setup
+### 📝 Knowledge Management
+- Search your entire graph for information
+- Generate summaries of pages and content
+- Create daily notes with custom sections
+- Organize flat pages into nested structures
 
-1. **Prerequisites:**
-   - Logseq with HTTP API enabled
-   - A valid Logseq API token
+### ✅ Task Management
+- Find all tasks with specific statuses (TODO, DOING, etc.)
+- Extract tasks from meeting notes
+- Create and organize task lists
+- Track task progress
 
-2. **Configure your environment:**
-   Create a `.env` file with:
-   ```
-   LOGSEQ_PORT=12315
-   LOGSEQ_HOST=127.0.0.1
-   LOGSEQ_TOKEN=your_logseq_token
-   ```
+### 🔍 Search & Query
+- Natural language search across your graph
+- Find blocks by content
+- Run advanced Datalog queries
 
-3. **Start the agent:**
-   ```bash
-   logseq-mcp
-   ```
+### 📊 Content Organization
+- Restructure content hierarchically
+- Organize blocks by any criteria
+- Transform flat content into nested structures
+
+## Quick Setup
 
-## Setup with Claude Desktop
+### Prerequisites
+- [Logseq](https://logseq.com/) with HTTP API enabled
+- A Logseq API token
+- Claude Desktop or other MCP-compatible AI assistant
 
-To use the Logseq Agent with Claude Desktop:
+### Enabling Logseq HTTP API
+1. In Logseq → Settings → Advanced: Enable "Developer mode"
+2. Restart Logseq
+3. In Settings: Enable "HTTP API server"
+4. Copy your API token
 
+### Setup with Claude Desktop
 1. Open Claude Desktop settings
 2. Navigate to MCP Servers
-3. Add a new server with the following configuration:
+3. Add a new server:
    ```json
    {
      "mcpServers": {
@@ -57,165 +66,145 @@ To use the Logseq Agent with Claude Desktop:
      }
    }
    ```
-4. Save and restart Claude Desktop
-5. You can now ask Claude to interact with your Logseq graph
-
-## Features
-
-### Block Management
-
-- **Get Block**: Retrieve a block by UUID
-- **Create Block**: Create a new block in a page
-- **Update Block**: Update an existing block
-- **Remove Block**: Remove a block by UUID
-- **Get/Set Block Properties**: Manage block properties
-- **Create Nested Blocks**: Create hierarchical block structures
-- **Edit/Select Blocks**: Manipulate blocks in the UI
+4. Replace `your_logseq_token` with your actual token
+5. Save and restart Claude
 
-### Block Navigation & Organization
+### Using Claude with Logseq
+Try asking:
+- "Find all my TODO tasks in Logseq"
+- "Create a daily note with sections for Tasks, Notes, and Journal"
+- "Summarize my 'Research' page"
+- "Search my notes for information about machine learning"
 
-- **Navigate Siblings**: Move between sibling blocks
-- **Move Block**: Reposition blocks within your graph
-- **Collapse/Expand**: Control block visibility
-- **Scroll to Block**: Navigate to specific blocks
-- **Right Sidebar**: Open blocks in the sidebar
+## Alternative Installation
 
-### Page Management
-
-- **Create Page**: Add new pages to your graph
-- **Get Page**: Retrieve page content by name
-- **Get Current Page**: Access the active page
-- **Get All Pages**: List all pages in your graph
-- **Get Page Blocks**: Access all blocks in a page
-- **Get Linked References**: See all references to a page
-
-### Search & Query
-
-- **Query Logseq**: Run powerful Datalog queries
-- **Search Blocks**: Find blocks matching criteria
-- **Get Tasks**: Retrieve and filter task blocks
-
-## Built-in Prompts
-
-The agent includes several pre-configured prompt templates:
-
-### Task Management
-- **query-tasks**: Find tasks with specific status (TODO, DOING, etc.)
-- **extract-tasks**: Extract and organize tasks from notes
-
-### Content Creation & Organization
-- **create-daily-note**: Generate a daily note with customizable sections
-- **create-nested-content**: Create structured hierarchical content
-- **summarize-page**: Generate concise summaries of pages
-
-### Knowledge Management
-- **search-knowledge**: Search your knowledge base
-- **organize-blocks**: Organize blocks by specified criteria
-- **organize-blocks-as-nested**: Restructure content hierarchically
-- **convert-flat-to-nested**: Transform flat pages into nested structures
-
-## Usage Examples
-
-Here are some examples of how to use the Logseq Agent with Claude:
+Install via npm:
+```bash
+npx logseq-mcp
+```
 
-1. **Create a daily note:**
-   ```
-   Please create a daily note for today with sections for Tasks, Notes, and Journal.
-   ```
+Or install globally:
+```bash
+npm install -g logseq-mcp
+```
 
-2. **Find and organize tasks:**
-   ```
-   Find all my TODO tasks and organize them by project.
-   ```
+Configure with a `.env` file:
+```
+LOGSEQ_PORT=12315
+LOGSEQ_HOST=127.0.0.1
+LOGSEQ_TOKEN=your_logseq_token
+```
 
-3. **Search my knowledge base:**
-   ```
-   Search my notes for information about "machine learning".
-   ```
+Run with:
+```bash
+logseq-mcp
+```
 
-4. **Summarize a page:**
-   ```
-   Can you summarize my "Project Ideas" page?
-   ```
+## Troubleshooting
 
-5. **Organize content:**
-   ```
-   Take my "Research Notes" page and organize it into a proper nested structure.
-   ```
+- Ensure Logseq is running before starting the agent
+- Verify your API token is correct
+- Check that the Logseq HTTP API is enabled
+- Try debug mode: `DEBUG=true logseq-mcp`
 
-## Troubleshooting
+### Debugging
+Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we recommend using the MCP Inspector.
 
-If you encounter connection issues:
+You can launch the MCP Inspector via npm with:
 
-1. **Enable the Logseq HTTP API:**
-   - Open Logseq
-   - Go to Settings
-   - Navigate to 'Advanced'
-   - Enable 'Developer mode'
-   - Restart Logseq
-   - Go to Settings again
-   - Find and enable 'HTTP API server'
+```bash
+npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-logseq run mcp-logseq
+```
 
-2. **Check your configuration:**
-   - Ensure Logseq is running before starting the agent
-   - Verify your LOGSEQ_TOKEN in the .env file
-   - Make sure the port isn't blocked by your firewall
+## Technical Details
 
-3. **Debug mode:**
-   Add `DEBUG=true` to your .env file for more detailed logs:
-   ```
-   DEBUG=true
-   LOGSEQ_PORT=12315
-   LOGSEQ_HOST=127.0.0.1
-   LOGSEQ_TOKEN=your_logseq_token
-   ```
+Built using the Model Context Protocol (MCP), an open standard for connecting AI models with external tools and data sources. The agent acts as an MCP server that provides structured access to your Logseq graph via the Logseq HTTP API.
 
 ## Development
 
-### Running from source
+### Setup Development Environment
 
 1. Clone the repository:
    ```bash
-   git clone https://github.com/yourusername/logseq-mcp.git
+   git clone https://github.com/briansunter/logseq-mcp.git
    cd logseq-mcp
    ```
 
 2. Install dependencies:
    ```bash
+   # Using npm
    npm install
+   
+   # Using Bun (recommended)
+   bun install
    ```
 
-3. Run the agent:
-   ```bash
-   npm start
-   ```
+### Running Tests
 
-### Testing
+The project includes unit and end-to-end tests:
 
-Run the integration tests with:
 ```bash
-npm test
+# Run all tests
+bun test tests/
+
+# Run unit tests only
+bun test:unit
+
+# Run e2e tests only
+bun test:e2e
+
+# Run tests in watch mode
+bun test:watch
 ```
 
-## For Developers
+### Building
 
-### Releasing New Versions
+```bash
+# Standard build
+bun run build
+
+# Build for Node.js
+bun run build:node
+
+# Build for Bun
+bun run build:bun
+
+# Build binaries for various platforms
+bun run build:binary           # Current platform
+bun run build:macos-arm        # macOS ARM
+bun run build:macos-intel      # macOS Intel
+bun run build:linux-x64        # Linux x64
+bun run build:linux-arm64      # Linux ARM64
+bun run build:windows          # Windows
+bun run build:all-binaries     # All platforms
+```
 
-To release a new version to npm:
+### Contributing Guidelines
 
-1. Update your code and make sure all tests pass with `bun test`
-2. Create a new GitHub release with a semantic version tag (e.g., `v1.0.1`)
-3. The GitHub Action will automatically:
-   - Build the package
-   - Update the version number from the tag
-   - Publish to npm
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature-name`
+3. Commit your changes: `git commit -m 'Add some feature'`
+4. Push to the branch: `git push origin feature/your-feature-name`
+5. Submit a pull request
 
-Note: Make sure you have set the `NPM_TOKEN` secret in your GitHub repository settings.
+Please make sure your code passes all tests and follows the existing code style. Add tests for new features.
 
-## License
+## Contributing & License
 
-MIT
+Contributions welcome! MIT License.
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+### Semantic Versioning
+
+This project uses semantic-release to automatically manage version numbers and create GitHub releases. Version numbers are determined by PR titles using the following conventions:
+
+| PR Title Format | Example | Result |
+|-----------------|---------|--------|
+| `feat: ...` | `feat: add new search feature` | Minor version increase (0.X.0) |
+| `fix: ...` | `fix: resolve search bug` | Patch version increase (0.0.X) |
+| `feat(breaking): ...` | `feat(breaking): change API format` | Major version increase (X.0.0) |
+
+Other valid prefixes: `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`, `ci:`, `build:` (all result in patch versions).
+
+When merging PRs to master, please follow these conventions in your PR titles to ensure proper versioning.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logseq-mcp",
-  "version": "0.0.18",
+  "version": "0.1.2",
   "description": "Logseq Model Context Protocol Agent",
   "type": "module",
   "main": "dist/index.js",
@@ -19,6 +19,10 @@
     "test:watch": "bun test --watch tests/",
     "test:unit:watch": "TEST_TYPE=unit bun test --watch tests/unit/",
     "test:e2e:watch": "TEST_TYPE=e2e bun test --watch tests/e2e/",
+    "typecheck": "bun --bun tsc --noEmit",
+    "lint": "bun eslint",
+    "check": "bun --bun tsc --noEmit && bun eslint",
+    "lint:fix": "bun eslint --fix",
     "build": "bun run build.ts",
     "build:node": "bun run build.ts node",
     "build:bun": "bun run build.ts bun",
@@ -40,6 +44,19 @@
     "dotenv": "^16.3.1",
     "zod": "^3.22.4"
   },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/github": "^9.2.0",
+    "@semantic-release/release-notes-generator": "^12.1.0",
+    "@types/node": "^22.13.11",
+    "@typescript-eslint/eslint-plugin": "^6.10.0",
+    "@typescript-eslint/parser": "^6.10.0",
+    "bun-types": "^1.2.5",
+    "eslint": "^9.23.0",
+    "globals": "^13.24.0",
+    "semantic-release": "^23.0.0",
+    "typescript": "^5.2.2"
+  },
   "files": [
     "dist",
     "README.md"