z230

2026-06-11 09:34:01 +02:00
parent bff5cc4cac
commit c4d353a343
7 changed files with 624 additions and 1 deletions
@@ -0,0 +1,90 @@
+# 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.