npm package: @kestrin/mcp-server
Description: MCP server for Kestrin — read, search, and navigate your knowledge graph
Latest version: 0.1.1

# @kestrin/mcp-server

MCP server for [Kestrin](https://github.com/kestrin/kestrin) — read, search, and navigate your knowledge graph from any MCP-compatible client.

## Features

- **Read & search** notes via on-disk reads plus daemon-aware retrieval
- **Graph and tag navigation** through daemon-backed metadata queries
- **Write with version history** through the same daemon pipeline as the desktop app
- **Version restore and write completion** with daemon revision IDs and `waitFor` checkpoints
- **Semantic helpers** for related notes, link suggestions, and tag suggestions when local models are configured

## Install

```bash
npm install -g @kestrin/mcp-server
```

Or run directly:

```bash
npx @kestrin/mcp-server
```

## Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kestrin": {
      "command": "npx",
      "args": ["@kestrin/mcp-server"]
    }
  }
}
```

### Claude Code

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "kestrin": {
      "command": "npx",
      "args": ["@kestrin/mcp-server"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "kestrin": {
      "command": "npx",
      "args": ["@kestrin/mcp-server"]
    }
  }
}
```

## CLI Options

```
kestrin-mcp [options]

  --verbose, -v        Log diagnostics to stderr
  --version            Show version
  --help, -h           Show help
```

## Tools

| Tool                   | Description                        | Mode         |
| ---------------------- | ---------------------------------- | ------------ |
| `read_note`            | Read markdown content              | Mixed        |
| `write_note`           | Create/update with version history | Daemon       |
| `patch_note`           | Find-and-replace edit              | Daemon       |
| `rename_note`          | Rename or move a note              | Daemon       |
| `delete_note`          | Delete a note                      | Daemon       |
| `await_write`          | Wait for a write token checkpoint  | Daemon       |
| `list_note_versions`   | List available version IDs         | Daemon       |
| `restore_note_version` | Restore a version by revision ID   | Daemon       |
| `list_directory`       | List vault files                   | Standalone   |
| `search_notes`         | Daemon retrieval or FTS fallback   | Mixed        |
| `get_backlinks`        | Documents linking to a note        | Daemon       |
| `get_outlinks`         | Documents a note links to          | Daemon       |
| `get_graph_context`    | Backlinks + outlinks in one call   | Daemon       |
| `list_tags`            | List tags on a document            | Daemon       |
| `search_by_tag`        | Find documents by tag              | Daemon       |
| `find_related_notes`   | Semantic related-note lookup       | Daemon+Model |
| `suggest_links`        | Semantic wiki-link suggestions     | Daemon+Model |
| `suggest_tags`         | Semantic tag suggestions           | Daemon+Model |

## Resources

| URI                    | Description                            |
| ---------------------- | -------------------------------------- |
| `kestrin://vault/info` | Vault name, path, doc count, tag count |
| `kestrin://tags`       | All unique tags with counts            |
| `kestrin://recent`     | Recently opened documents              |

## Canonical Paths

`write_note` returns a `path` field containing the actual vault-relative path where the file was saved. For new files, this will be a UUID directory (e.g. `a1b2c3d4-.../my-note.md`) to isolate version history per document — matching the Kestrin frontend convention.

**Always use the returned `path` for subsequent operations** (`patch_note`, `delete_note`, `read_note`). The originally requested flat path (e.g. `my-note.md`) will not resolve after the file has been placed in its UUID directory. Existing files keep their current path unchanged.

## Modes

**Standalone** — Works without the Kestrin app for direct file reads, directory listing, and local SQLite-backed fallback search.

**Daemon** — Requires the Kestrin app and `kestrin-daemon`. Uses daemon RPC for reads, writes, graph/tag queries, version restore, and completion checkpoints.

## Consistency Notes

- `read_note` prefers a daemon read when available and falls back to direct disk reads only when the app is not running.
- `search_notes` prefers daemon retrieval when available and falls back to local FTS metadata only in standalone mode.
- Graph, tag, version, and semantic tools are daemon-backed and require the app runtime to be available.
- Write and restore tools go through `kestrin-daemon`. A successful response always means the change was persisted on disk and version metadata was updated. Lexical indexing is guaranteed only when the call uses the default `waitFor: "indexed"` checkpoint; callers that opt into earlier checkpoints such as `accepted` or `materialized` may observe the write before search/tag/graph reads catch up.