# zk-utils

zk-utils is an MCP (Model Context Protocol) server for zk note management tools. It provides functionality for note search, creation, and link analysis by integrating with zk.

## Prerequisites

- [zk](https://github.com/zk-org/zk) command line tool

## Usage

### Using uvx (Recommended)

Add the following to mcp configuration file:

```json
{
  "mcpServers": {
    "zk-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/koei-kaji/zk-utils", "zk-utils-mcp"],
      "env": {
        "ZK_DIR": "/path/to/your/notes"
      }
    }
  }
}
```

### Environment Variables

- `ZK_DIR`: Path to zk notes directory (required)

### Using Docker

#### Initial Setup

If you are creating a zk notebook for the first time, initialize the note directory with `zk init`:

```bash
cd /path/to/your/zk-notes
docker run -it --rm -v $(pwd):/zk-notes -w /zk-notes koeikajidev/zk-utils-mcp zk init
```

#### MCP Configuration

Add the following to mcp configuration file:

```json
{
  "mcpServers": {
    "zk-utils": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/your/zk-notes:/zk-notes:ro",
        "koeikajidev/zk-utils-mcp"
      ]
    }
  }
}
```

**Note**: Use absolute path for the zk-notes directory.

## Available MCP Tools

- `get_notes`: Search and retrieve zk notes with filtering and pagination
- `get_note_content`: Retrieve the full content of a specific zk note
- `get_link_to_notes`: Get all notes that are linked FROM the specified note (outbound links)
- `get_linked_by_notes`: Get all notes that link TO the specified note (inbound links)
- `get_related_notes`: Find notes that could be good candidates for linking
- `get_tags`: Retrieve all available tags from the zk note collection
- `create_note`: Create a new zk note with the specified title and path
- `get_last_modified_note`: Retrieve the most recently modified note
- `get_tagless_notes`: Retrieve all notes that have no tags assigned
- `get_random_note`: Retrieve a randomly selected note from the zk collection

## Index Freshness

zk-utils automatically runs `zk index --quiet` before operations that rely on zk's index. Notes changed outside an LSP-aware editor, such as by shell scripts, sync tools, or AI agents, are therefore reindexed before zk-utils queries them; no separate scheduled reindexing is required for zk-utils itself.