111 lines
5.2 KiB
Markdown
111 lines
5.2 KiB
Markdown
# MCP server: Trilium — v1.1
|
|
|
|
**Soubor:** `mcp_trilium_v1.1.py`
|
|
**Datum:** 2026-06-11
|
|
**Úč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).
|
|
- Summary diskuzí jdou do **root > ClaudeSummaries** (`gwBGibRzpN8d`), složky na
|
|
stejné úrovni jako Claude (hned pod ní), rovněž 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 |
|
|
| `create_summary` | **summary diskuze do ClaudeSummaries** | viz pravidla níže — **nové v1.1** |
|
|
| `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` |
|
|
|
|
### Pravidla pro `create_summary` (nové v1.1)
|
|
|
|
1. **První řádek poznámky doplní tool automaticky**:
|
|
`YYYY-MM-DD HH:MM — <creator>` (kdo a kdy summary vytvořil), creator default
|
|
`ClaudeCode z počítače <COMPUTERNAME>` (např. „ClaudeCode z počítače Z230").
|
|
Klient tedy NEMÁ začínat content vlastní hlavičkou s datem.
|
|
2. **Rozsah summary**: tak podrobné, aby šlo kdykoliv (i za půl roku) navázat na
|
|
práci bez znalosti původní konverzace — kontext/cíl, co se udělalo a jak
|
|
(postupy, příkazy, triky), výsledky, co zbývá, cesty k souborům/skriptům/ID.
|
|
3. Title = datum + téma (např. „2026-06-11 Úklid disku C").
|
|
|
|
### Bezpečnost zápisu
|
|
Dle zvyklostí ostatních zdejších MCP serverů (preview → confirm):
|
|
- `create_note` / `create_summary` / `append_note` / `upload_file` — bez tření
|
|
- `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) |
|
|
| `TRILIUM_SUMMARY_PARENT` | `gwBGibRzpN8d` (složka ClaudeSummaries) |
|
|
|
|
> **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.1.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.1.py # stdio MCP server (běžný režim)
|
|
python mcp_trilium_v1.1.py --selftest # rychlý test create/append/read/delete
|
|
```
|
|
|
|
## Příklady použití (z pohledu LLM klienta)
|
|
|
|
- *„zapiš poznámku …"* → `create_note(title=…, content=…)`
|
|
- *„ulož summary téhle diskuze"* → `create_summary(title="2026-06-11 Téma", 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.1** (2026-06-11) — nový tool `create_summary`: ukládá summary diskuzí do
|
|
root > ClaudeSummaries (`gwBGibRzpN8d`), automatická hlavička „datum čas —
|
|
creator", pravidlo podrobnosti (navázat na práci kdykoliv); env
|
|
`TRILIUM_SUMMARY_PARENT`.
|
|
- **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.
|