logseq-mcp 0.0.0-development

package/README.md

@@ -0,0 +1,210 @@
+# Logseq MCP Agent
+
+A powerful AI assistant that connects Logseq with Claude and other LLMs using the Model Context Protocol (MCP).
+
+## What is it?
+
+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.
+
+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.
+
+Think of it as giving Claude direct access to your second brain.
+
+## Key Features
+
+### 📝 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
+
+### ✅ Task Management
+- Find all tasks with specific statuses (TODO, DOING, etc.)
+- Extract tasks from meeting notes
+- Create and organize task lists
+- Track task progress
+
+### 🔍 Search & Query
+- Natural language search across your graph
+- Find blocks by content
+- Run advanced Datalog queries
+
+### 📊 Content Organization
+- Restructure content hierarchically
+- Organize blocks by any criteria
+- Transform flat content into nested structures
+
+## Quick Setup
+
+### Prerequisites
+- [Logseq](https://logseq.com/) with HTTP API enabled
+- A Logseq API token
+- Claude Desktop or other MCP-compatible AI assistant
+
+### 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:
+   ```json
+   {
+     "mcpServers": {
+       "logseq": {
+         "command": "npx",
+         "args": [
+           "logseq-mcp"
+         ],
+         "env": {
+           "LOGSEQ_TOKEN": "your_logseq_token"
+         }
+       }
+     }
+   }
+   ```
+4. Replace `your_logseq_token` with your actual token
+5. Save and restart Claude
+
+### 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"
+
+## Alternative Installation
+
+Install via npm:
+```bash
+npx logseq-mcp
+```
+
+Or install globally:
+```bash
+npm install -g logseq-mcp
+```
+
+Configure with a `.env` file:
+```
+LOGSEQ_PORT=12315
+LOGSEQ_HOST=127.0.0.1
+LOGSEQ_TOKEN=your_logseq_token
+```
+
+Run with:
+```bash
+logseq-mcp
+```
+
+## Troubleshooting
+
+- 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`
+
+### Debugging
+Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we recommend using the MCP Inspector.
+
+You can launch the MCP Inspector via npm with:
+
+```bash
+npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-logseq run mcp-logseq
+```
+
+## Technical Details
+
+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
+
+### Setup Development Environment
+
+1. Clone the repository:
+   ```bash
+   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
+   ```
+
+### Running Tests
+
+The project includes unit and end-to-end tests:
+
+```bash
+# 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
+```
+
+### Building
+
+```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
+```
+
+### Contributing Guidelines
+
+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
+
+Please make sure your code passes all tests and follows the existing code style. Add tests for new features.
+
+## Contributing & License
+
+Contributions welcome! MIT License.
+
+## Contributing
+
+### 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.