logseq-mcp 0.0.2

package/README.md

@@ -0,0 +1,221 @@
+# Logseq 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.
+
+## Installation
+
+You can install the Logseq Agent via npm:
+
+```bash
+npx logseq-mcp
+```
+
+Or install it globally:
+
+```bash
+npm install -g logseq-mcp
+```
+
+## Quick Setup
+
+1. **Prerequisites:**
+   - Logseq with HTTP API enabled
+   - A valid Logseq API token
+
+2. **Configure your environment:**
+   Create a `.env` file with:
+   ```
+   LOGSEQ_PORT=12315
+   LOGSEQ_HOST=127.0.0.1
+   LOGSEQ_TOKEN=your_logseq_token
+   ```
+
+3. **Start the agent:**
+   ```bash
+   logseq-mcp
+   ```
+
+## Setup with Claude Desktop
+
+To use the Logseq Agent with Claude Desktop:
+
+1. Open Claude Desktop settings
+2. Navigate to MCP Servers
+3. Add a new server with the following configuration:
+   ```json
+   {
+     "mcpServers": {
+       "logseq": {
+         "command": "npx",
+         "args": [
+           "logseq-mcp"
+         ],
+         "env": {
+           "LOGSEQ_TOKEN": "your_logseq_token"
+         }
+       }
+     }
+   }
+   ```
+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
+
+### Block Navigation & Organization
+
+- **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
+
+### 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:
+
+1. **Create a daily note:**
+   ```
+   Please create a daily note for today with sections for Tasks, Notes, and Journal.
+   ```
+
+2. **Find and organize tasks:**
+   ```
+   Find all my TODO tasks and organize them by project.
+   ```
+
+3. **Search my knowledge base:**
+   ```
+   Search my notes for information about "machine learning".
+   ```
+
+4. **Summarize a page:**
+   ```
+   Can you summarize my "Project Ideas" page?
+   ```
+
+5. **Organize content:**
+   ```
+   Take my "Research Notes" page and organize it into a proper nested structure.
+   ```
+
+## Troubleshooting
+
+If you encounter connection issues:
+
+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'
+
+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
+
+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
+   ```
+
+## Development
+
+### Running from source
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/logseq-mcp.git
+   cd logseq-mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Run the agent:
+   ```bash
+   npm start
+   ```
+
+### Testing
+
+Run the integration tests with:
+```bash
+npm test
+```
+
+## For Developers
+
+### Releasing New Versions
+
+To release a new version to npm:
+
+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
+
+Note: Make sure you have set the `NPM_TOKEN` secret in your GitHub repository settings.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.