# MCP TriliumNext

A Model Context Protocol (MCP) server for [TriliumNext](https://github.com/TriliumNext/Trilium), providing AI assistants with seamless access to your note-taking workflow.

## Overview

This MCP server enables AI assistants like Claude to interact with your TriliumNext notes through a standardized protocol. It provides tools for creating, searching, reading, and updating notes, as well as accessing recent notes as a resource.

## Features

### 🛠️ Tools
- **create_note** - Create new notes with title, content, and type
- **search_notes** - Search notes using fulltext or structured queries
- **get_note** - Retrieve complete note details and content
- **update_note** - Update existing note content

### 📚 Resources
- **trilium://recent-notes** - Access to 10 most recently modified notes

### ✨ Key Capabilities
- Full CRUD operations for notes
- Advanced search with TriliumNext query syntax
- Structured data preservation for AI consumption
- Comprehensive error handling and validation
- Production-ready logging and monitoring

## Installation

### Prerequisites
- Node.js 18.0.0 or higher
- TriliumNext server running and accessible
- ETAPI token from your TriliumNext instance

### Setup

1. **Clone and install**
   ```bash
   git clone git@github.com:RadonX/mcp-trilium.git
   cd mcp-trilium
   npm install
   ```

2. **Configure environment**
   Create a `.env` file with your settings:
   ```env
   TRILIUM_URL=http://localhost:8080
   TRILIUM_AUTH_TOKEN=your_etapi_token_here
   REQUEST_TIMEOUT=30000
   LOG_LEVEL=info
   ```

3. **Get your ETAPI token**
   - Open TriliumNext web interface
   - Go to Options → ETAPI
   - Create a new token or use existing one
   - Copy the token to your `.env` file

4. **Test connectivity**
   ```bash
   npm run test-connectivity
   ```

## Usage

### With Claude Code

Add the MCP server directly using Claude Code:

```bash
claude mcp add trilium-mcp node /path/to/mcp-trilium/src/index.js --env TRILIUM_URL=http://localhost:8080 --env TRILIUM_AUTH_TOKEN=your_etapi_token_here --env REQUEST_TIMEOUT=30000 --env LOG_LEVEL=info
```

### With Claude Desktop

Add to your Claude Desktop configuration (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "trilium": {
      "command": "node",
      "args": ["/path/to/mcp-trilium/src/index.js"],
      "env": {
        "TRILIUM_URL": "http://localhost:8080",
        "TRILIUM_AUTH_TOKEN": "your_token_here"
      }
    }
  }
}
```

### With MCP Inspector

```bash
npx @modelcontextprotocol/inspector src/index.js
```

### Standalone Usage

```bash
npm start
```

## Examples

### Creating a Note
```javascript
// Ask Claude: "Create a note about TypeScript basics"
{
  "tool": "create_note",
  "arguments": {
    "title": "TypeScript Basics",
    "content": "# TypeScript Fundamentals\n\nTypeScript is a typed superset of JavaScript...",
    "type": "text",
    "parentNoteId": "root"
  }
}
```

### Searching Notes
```javascript
// Ask Claude: "Find all notes about JavaScript"
{
  "tool": "search_notes",
  "arguments": {
    "query": "javascript #programming",
    "limit": 10
  }
}
```

### Updating Content
```javascript
// Ask Claude: "Update my JavaScript notes with new ES6 features"
{
  "tool": "update_note",
  "arguments": {
    "noteId": "note123abc",
    "content": "Updated content with ES6 features..."
  }
}
```

## Search Query Syntax

TriliumNext supports powerful search queries:

- **Fulltext**: `machine learning algorithms`
- **Exact match**: `"neural networks"`
- **Labels**: `#programming #javascript`
- **Combined**: `"react hooks" #programming type:code`
- **Date filters**: `dateCreated:>2024-01-01`

## Development

### Running Tests
```bash
# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage
```

### Project Structure
```
src/
├── index.js           # Main MCP server
├── tools/             # MCP tool implementations
│   ├── create-note.js
│   ├── search-notes.js
│   ├── get-note.js
│   └── update-note.js
├── resources/         # MCP resource implementations
│   └── recent-notes.js
└── utils/             # Shared utilities
    ├── trilium-client.js
    ├── validation.js
    └── logger.js
```

### API Reference

#### TriliumNext ETAPI
This server uses TriliumNext's External API (ETAPI). Key endpoints:
- `GET /notes` - Search notes
- `POST /create-note` - Create note
- `GET /notes/{id}` - Get note details
- `PUT /notes/{id}/content` - Update note content

See [docs/trilium-etapi-specification.md](docs/trilium-etapi-specification.md) for complete API documentation.

## Configuration

### Environment Variables
- `TRILIUM_URL` - TriliumNext server URL (default: `http://localhost:8080`)
- `TRILIUM_AUTH_TOKEN` - ETAPI authentication token (required)
- `REQUEST_TIMEOUT` - API request timeout in ms (default: `30000`)
- `LOG_LEVEL` - Logging level: `error`, `warn`, `info`, `debug` (default: `info`)

### Note Types
Supported note types:
- `text` - Rich text notes (default)
- `code` - Code snippets with syntax highlighting
- `file` - File attachments
- `image` - Image notes
- `search` - Saved searches
- `book` - Book/chapter organization
- `relationMap` - Visual relation maps
- `canvas` - Freeform canvas notes

## Troubleshooting

### Common Issues

**Authentication Failed**
```bash
# Check your token
curl -H "Authorization: Bearer your_token" http://localhost:8080/etapi/app-info
```

**Connection Refused**
- Verify TriliumNext is running
- Check `TRILIUM_URL` in `.env`
- Ensure ETAPI is enabled in TriliumNext settings

**Content Stored as [Object]**
- Fixed in v0.1.0 - content now properly sent as text/plain
- Update to latest version if experiencing this issue

### Debug Mode
```bash
LOG_LEVEL=debug npm start
```

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes with tests
4. Run the test suite: `npm test`
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Related Projects

- [TriliumNext](https://github.com/TriliumNext/Trilium) - The note-taking application
- [Model Context Protocol](https://github.com/modelcontextprotocol/servers) - MCP specification
- [Claude Desktop](https://claude.ai/desktop) - AI assistant with MCP support

## Future Enhancements

The following features may be added in future versions:

### 🚀 Planned Features
- **Enhanced note types support** - Full support for all TriliumNext note types (relationMap, canvas, etc.)
- **Advanced search features** - Attribute-based queries, date range filters, and complex search operators
- **Performance optimizations** - Caching, batch operations, and streaming for large note collections
- **Note relationship management** - Tools for managing note relationships and hierarchies
- **Bulk operations** - Create, update, or delete multiple notes in a single operation
- **Attachment handling** - Support for file uploads and downloads
- **Real-time updates** - WebSocket integration for live note synchronization

### 💡 Potential Integrations
- **Export capabilities** - Export notes to various formats (Markdown, PDF, etc.)
- **Template system** - Predefined note templates for common use cases
- **Backup and restore** - Automated backup functionality through MCP
- **Analytics and insights** - Note usage statistics and content analysis

## Changelog

### v0.1.0
- Initial release with full CRUD operations
- MCP resource for recent notes
- Comprehensive test coverage (94 tests)
- Production-ready error handling and validation

---

Made with ❤️ for the TriliumNext and MCP communities