# Amplenote MCP Server

A Model Context Protocol (MCP) server that provides access to your Amplenote SQLite database cache.

## Features

### Note Operations
- **search_notes**: Search notes using full-text search (FTS4)
- **get_note_by_uuid**: Retrieve complete note content by UUID
- **get_note_by_name**: Find notes by name (partial match)
- **list_notes**: List all notes with pagination
- **get_recently_modified_notes**: Get the most recently modified notes
- **get_note_references**: Get bidirectional note references

### Task Operations
- **search_tasks**: Search tasks by description/body text with duration, dates, and priority
- **list_tasks**: List and filter tasks (by priority, due date, etc.)
- **get_recently_modified_tasks**: Get the most recently modified tasks
- **get_tasks_by_note**: Find tasks associated with a specific note

## Installation

The solution uses nix, so you just need to use nix to develop.

```bash
nix develop --no-pure-eval
```

## Running commands

There are two different commands to help, one for starting mcp and one for Running tests.

```bash
nix develop --no-pure-eval --command mcp-start
```

```bash
nix develop --no-pure-eval --command run-tests
```

## Configuration

The database path can be configured via environment variable. By default, it uses:
`~/.config/ample-electron/amplenote.db` which is not a valid database file, update
with your local configuration.

### Automatic Setup for Claude Desktop

The easiest way to configure Claude Desktop is to use the built-in setup script:

```bash
# Use default database path
nix develop --no-pure-eval --command setup-claude-desktop

# Or specify a custom database path
nix develop --no-pure-eval --command setup-claude-desktop /path/to/your/amplenote.db
```

This will automatically:
- Detect your OS and locate the Claude Desktop config directory
- Create or update the MCP server configuration
- Configure the server to use nix for running
- Set the database path

After running the setup script, restart Claude Desktop for the changes to take effect.

### Manual Configuration

If you prefer to configure manually, add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "amplenote_cache": {
      "command": "nix",
      "args": ["develop", "--no-pure-eval", "--command", "mcp-start"],
      "cwd": "/path/to/amplenote_cache_mcp",
      "env": {
        "AMPLENOTE_DB_PATH": "~/.config/ample-electron/<some-file>.db"
      }
    }
  }
}
```

## Available Tools

### Note Tools

#### search_notes
Search your notes using full-text search.
- `query` (str): Search query
- `limit` (int): Max results (default: 10)

**Example**: Search for notes containing "project planning"

#### get_note_by_uuid
Get complete note content by UUID.
- `uuid` (str): Remote or local UUID

**Example**: Retrieve the full content of a specific note

#### get_note_by_name
Find a note by name (case-insensitive partial match).
- `name` (str): Note name to search for

**Example**: Find a note with "Meeting" in its title

#### list_notes
List all notes with pagination.
- `limit` (int): Max results (default: 20)
- `offset` (int): Skip N notes (default: 0)

**Example**: Get the first 20 notes sorted alphabetically

#### get_recently_modified_notes
Get the most recently modified notes.
- `limit` (int): Max results (default: 20)

**Example**: See what notes were updated recently

#### get_note_references
Get bidirectional references for a note.
- `uuid` (str): Note UUID

**Example**: Find all notes that link to or from a specific note

### Task Tools

#### search_tasks
Search tasks by description/body text.
- `query` (str): Search query to match in task body
- `limit` (int): Max results (default: 20)
- `include_deleted` (bool): Include deleted tasks (default: false)

**Returns**: Tasks with duration, due dates, priority (urgent/important level), and other details

**Example**: Find all tasks related to "documentation"

#### list_tasks
List tasks with filtering options.
- `limit` (int): Max results (default: 20)
- `include_deleted` (bool): Include deleted tasks (default: false)
- `priority` (int): Filter by priority level (0-3, where higher is more important)
- `has_due_date` (bool): Filter tasks with/without due dates

**Example**: Get all high-priority tasks with due dates

#### get_recently_modified_tasks
Get the most recently modified tasks.
- `limit` (int): Max results (default: 20)
- `include_deleted` (bool): Include deleted tasks (default: false)

**Returns**: Recently updated tasks with all details including timestamps

**Example**: See what tasks were recently updated

#### get_tasks_by_note
Get tasks associated with a specific note.
- `note_uuid` (str): Note UUID

**Example**: Find all tasks mentioned in a specific note

## Database Schema

The server reads from these Amplenote tables:
- `notes`: Note content and metadata (including `updated_at` timestamp)
- `tasks`: Task details (including priority, duration, due dates, and `updated_at` timestamp)
- `note_references`: Note-to-note references
- `notes_search_index`: FTS4 full-text search index

## Testing

The project includes a comprehensive test suite. To run tests:

```bash
nix develop --no-pure-eval --command run-tests
```

```bash
poetry run pytest
```

To run tests with coverage:

```bash
poetry run coverage run -m pytest
poetry run coverage report
```

## Development

This project follows idiomatic Python practices:
- Modular architecture with separate files for database, models, notes, and tasks
- Type hints throughout the codebase
- Comprehensive docstrings
- Small, focused functions with single responsibilities
- Proper error handling

### Code Style

The project uses `ruff` for linting and formatting:

```bash
poetry run ruff format app/
poetry run ruff check app/
```

## Architecture

The codebase is organized into focused modules:

- `app/database.py`: Database connection and configuration
- `app/models.py`: TypedDict models for data structures
- `app/notes.py`: Note-related functionality
- `app/tasks.py`: Task-related functionality
- `app/__main__.py`: FastMCP server and tool registration

This modular design makes the code easier to maintain, test, and extend.