---
name: "silverbullet-mcp"
description: "Accès technique à l'espace SilverBullet shizendo via le MCP silverbullet-ai : instance, outils disponibles, noms de pages, Runtime API, exploitation. Source de vérité des skills & agents = SilverBullet."
---

# Accès technique à SilverBullet (MCP silverbullet-ai)

## Instance

- SilverBullet (YunoHost, multi-espaces) — accès local `127.0.0.1:3000`, espace monté en `/shizendo/`.
- Le MCP `silverbullet-ai` est connecté (pont officiel du plug AI via la Runtime API). SilverBullet n'expose pas de serveur MCP intégré.

## Outils MCP disponibles

`read_note`, `list_pages`, `create_note`, `update_note`, `search_replace`, `rename_note`, `update_frontmatter`, `view_file`, `get_page_info`, `eval_lua`, `refresh_tools`.

## Noms de pages

- **Sans extension** `.md` : `00_INBOX/note` (pas `00_INBOX/note.md`).

## ⭐ Requêtes SLIQ / Lua (eval_lua) — À LIRE EN PRIORITÉ

Pour **toute lecture, recherche ou manipulation** via `eval_lua`, ne pas explorer l'API Lua à l'aveugle : utiliser directement `query[[ ... ]]`.

### Exécuter une requête SLIQ dans eval_lua

`query` est une **syntaxe** (pas une fonction) : écrire la requête en littéral `query[[ ... ]]` ; on peut intégrer des **variables Lua directement dans la requête**.

```lua
-- Ex. : lister les pages portant l'attribut projects, avec détail
local res = query[[
  from p = index.pages()
  where p.projects
  select { PAGE = "[[" .. p.name .. "]]", PROJETS = table.concat(p.projects, ", ") }
]]
```

### Fonctions utiles dans une requête SLIQ

| Fonction | Usage |
|---|---|
| `table.includes(liste, valeur)` | Appartenance **exacte** d'une valeur dans une liste (ex. `table.includes(p.projects, "PROJET")`) |
| `table.concat(liste, sep)` | Concatène une liste en chaîne — il n'y a **pas** de `join` |
| `string.find(chaîne, motif)` | Recherche dans une chaîne |
| `index.tasks("<tag>")` | Tâches par tag (ex. `index.tasks('event')`) |

### Pièges constatés (instance shizendo)

- `join(liste, sep)` **n'existe pas** dans SLIQ → utiliser `table.concat`.
- `index.pages()["query"]("<filtre>")` renvoie **toutes** les pages (avec attributs frontmatter `type`, `tags`, `projects`, …) mais le **filtre est ignoré** → uniquement pour lister, jamais pour filtrer.
- `query` est une syntaxe, pas une fonction : `query[variable]` est invalide → écrire la requête en littéral.
- Mots réservés (`query`, `using`, …) : interdits comme identifiants/attributs (ex. `.query` invalide → `["query"]`).
- `space.readPage(nom)` renvoie une **table de lignes** (clés chaînes « 0 », « 1 », …), pas un objet `{text}` — peu pratique.
- `index.extractFrontmatter(...)` attend le **markdown brut**, pas un nom de page.
- **Recensement fiable d'attributs de frontmatter** (ex. valeurs de `projects:`) : préférer l'**API HTTP /.fs** (skill `silverbullet-api`) qui lit les fichiers directement — plus fiable et plus économe en tokens que l'index Lua.

Documentation officielle : https://docs.silverbullet.md/Space%20Lua/Integrated%20Query

## Runtime API / exploitation

- La Runtime API lance un **Chrome headless** (~300 Mo) : premiers appels 20-60 s, puis rapides.
- Les outils d'écriture passent par la Runtime API **sans confirmation** : les appels sont directs.
- L'index SilverBullet met quelques secondes à se rafraîchir après modification.

## Gestion des skills & agents (source de vérité)

- **SilverBullet est la source de vérité** des skills (`80_CONFIG/IA_SKILLS/`) et des agents (`80_CONFIG/IA_AGENTS/`).
- Toute modification de skill/agent se fait **dans SilverBullet** (créer/éditer la page via `create_note` / `update_note`), **jamais** dans les dossiers locaux `~/.opencode/skills` et `~/.opencode/agents` : ceux-ci sont **écrasés** par la synchronisation.
- Après modification d'un skill/agent dans SilverBullet, resynchroniser les copies locales :
  ```bash
  ~/.opencode/bin/sync-silverbullet.sh
  ```
  puis **redémarrer la session OpenCode** (ou `opencode service restart`) pour recharger les skills/agents.
- **Garde-fou** : `sync-silverbullet.sh` refuse d'écraser un skill/agent local modifié mais non commité (voir le script).
- Workflow détaillé : voir la note `80_CONFIG/IA_DOCUMENTATION/SilverBullet_Manage-Skills-Agents`.