# MCP server: Trilium — v1.0

**Soubor:** `mcp_trilium_v1.0.py`
**Datum:** 2026-06-09
**Účel:** umožnit libovolnému MCP klientovi (Claude Code v jiné session, Claude
Chat, Cowork, …) **číst a hlavně psát** poznámky a soubory do Trilia běžícího na
<https://trilium.buzalka.cz>. Slouží k rychlému předávání poznámek do prostředí,
kam se jinak nedá kopírovat (JNJ remote PC apod.).

## Jak to funguje

- Komunikuje s Trilium přes **ETAPI** (REST), autentizace hlavičkou
  `Authorization: <token>`.
- Používá **jen Python stdlib** (`urllib`) — žádné externí HTTP knihovny.
- Jediná závislost je balík `mcp` (FastMCP), který už je v prostředí ostatních
  zdejších MCP serverů.
- Výchozí cílová složka je **root > Claude** (`NeoXOIw0uBK2`), která má nastaveno
  `#sorted=dateCreated` + `#sortDirection=desc`, takže **nové poznámky jdou
  automaticky nahoru** (newest-first).

## Nástroje (tools)

| Tool | Co dělá | Pozn. |
|------|---------|-------|
| `ping` | health check + verze + default složka | zavolej první |
| `create_note` | nová textová poznámka | plain text → HTML; default rodič = Claude |
| `append_note` | připíše text na konec poznámky | nedestruktivní |
| `set_note_content` | **přepíše** obsah poznámky | vyžaduje `confirmed=True` |
| `create_folder` | nová podsložka | volitelně newest-first + na začátek |
| `upload_file` | nahraje lokální soubor jako poznámku `file` | ověří SHA-256 |
| `read_note` | přečte obsah + metadata | |
| `list_children` | vypíše potomky (default Claude) | |
| `search_notes` | fulltext / atributové hledání | Trilium search syntax |
| `delete_note` | **smaže** poznámku (+ potomky) | vyžaduje `confirmed=True` |

### Bezpečnost zápisu
Dle zvyklostí ostatních zdejších MCP serverů (preview → confirm):
- `create_note` / `append_note` / `upload_file` — bez tření (hlavní účel)
- `set_note_content` (přepis) a `delete_note` — vrátí nejdřív **náhled**;
  reálná akce až s `confirmed=True`.

### Diakritika
Text se posílá v **UTF-8** jako `text/plain; charset=utf-8`. Ověřeno selftestem
(`První řádek`, `—`, `ěščřž` se ukládají i čtou správně).

## Konfigurace (volitelné přepsání přes proměnné prostředí)

| Proměnná | Default |
|----------|---------|
| `TRILIUM_URL` | `https://trilium.buzalka.cz` |
| `TRILIUM_ETAPI_TOKEN` | (zabudovaný token) |
| `TRILIUM_DEFAULT_PARENT` | `NeoXOIw0uBK2` (složka Claude) |

> **Bezpečnost:** token je pro pohodlí zabudovaný přímo ve skriptu (stejně jako
> hesla v ostatních zdejších MCP serverech). Lze ho kdykoli **revoknout** v
> Triliu (Options → ETAPI) a/nebo nahradit proměnnou `TRILIUM_ETAPI_TOKEN`
> (viz `.env.example`). Token dává plný přístup k poznámkám přes API.

## Registrace v `.mcp.json`

```json
"trilium": {
  "command": "python",
  "args": ["U:\\PythonProject\\Janssen\\TrilliumMCP\\mcp_trilium_v1.0.py"],
  "cwd": "U:\\PythonProject\\Janssen\\TrilliumMCP"
}
```

Pro jiné klienty (Claude Desktop / Cowork) přidej obdobný záznam do jejich
konfigurace MCP serverů (stejný `command` + `args`).

## Spuštění a test

```bash
python mcp_trilium_v1.0.py            # stdio MCP server (běžný režim)
python mcp_trilium_v1.0.py --selftest # rychlý test create/append/read/delete
```

## Příklady použití (z pohledu LLM klienta)

- *„zapiš poznámku …"* → `create_note(title=…, content=…)`
- *„přidej k té poznámce …"* → `append_note(note_id=…, text=…)`
- *„nahraj tenhle PDF do Trilia"* → `upload_file(file_path=…)`
- *„co je ve složce Claude"* → `list_children()`
- *„najdi poznámku o protokolu"* → `search_notes(query="protokol")`

## Historie verzí
- **v1.0** (2026-06-09) — první verze: ping, create/append/set_content,
  create_folder, upload_file, read/list/search, delete. Selftest OK proti
  TriliumNext 0.103.0.