diff --git a/internal/server/silverbullet.md b/internal/server/silverbullet.md index 09f1a4b23bf8c8c887cdc4d83e35088d8aa6f4ae..387c2d7f4828ff6f5115eb8ed2b04975c5994c79 100644 --- a/internal/server/silverbullet.md +++ b/internal/server/silverbullet.md @@ -1,12 +1,6 @@ # SilverBullet MCP Server Instructions -You are connected to a SilverBullet instance via its Runtime API. SilverBullet is a creative coding knowledge management tool with an embedded Lua scripting language called Space Lua. - -## Available Tools - -- **execute_lua**: Run Space Lua scripts. Use for reading/writing pages, querying data, and all Space Lua operations. -- **screenshot**: Capture current viewport as a PNG image. -- **console_logs**: Retrieve recent console log entries. Useful for debugging. +You are connected to a SilverBullet instance, a knowledge management tool with a Lua interpreter, via its Runtime API. ## Space Lua Essentials @@ -18,42 +12,36 @@ Space Lua is a custom Lua implementation embedded in SilverBullet. Key differenc - `print()` output is swallowed in Runtime API — use `return` to send results back - `query[[...]]` is LIQ (Lua Integrated Query), a SQL/LINQ-inspired query syntax embedded in Lua -## Page Operations +## Operations ```lua -- Read a page local content = space.readPage("MyPage") - -- Write a page space.writePage("MyPage", "# Hello\n\nContent here") - -- Delete a page space.deletePage("MyPage") - -- Check if a page exists if space.pageExists("MyPage") then -- ... end - -- List all pages local pages = space.listPages() - -- Get page metadata local meta = space.getPageMeta("MyPage") -- meta.name, meta.lastModified -``` -## Querying with LIQ - -LIQ (`query[[...]]`) is the primary way to search and filter data: - -```lua -- Find pages tagged #task local tasks = query[[ from p = index.tag "task" select p.name ]] - +-- Find pages that link to a specific page +local links = query[[ + from l = index.tag "link" + where l.toPage == "TargetPage" + select l.fromPage +]] -- Filter by frontmatter local projects = query[[ from p = index.tag "page" @@ -62,70 +50,20 @@ local projects = query[[ select p.name limit 10 ]] - -- Count items in a group local counts = query[[ from p = index.tag "tag" group by p.name select { name = name, count = #group } ]] -``` - -## File/Document Operations - -```lua -- List all files local files = space.listFiles() - -- Read a file (returns bytes as string) local data = space.readFile("image.png") - -- Write a file space.writeFile("data.json", jsonString) - -- Read a specific section local section = space.readRef("MyPage#Introduction") -``` - -## Common Patterns - -### Working with Frontmatter - -SilverBullet pages can have YAML frontmatter. Query against indexed tags and frontmatter fields: - -```lua -local pages = query[[ - from p = index.tag "page" - where p.priority == "high" - select { name = p.name, priority = p.priority } -]] -``` - -### Working with Tasks - -```lua -local tasks = query[[ - from t = index.tag "task" - where t.state == "todo" - order by t.lastModified desc - select { name = t.name, page = t.page } -]] -``` - -### Links and References - -```lua --- Find pages that link to a specific page -local links = query[[ - from l = index.tag "link" - where l.toPage == "TargetPage" - select l.fromPage -]] -``` - -### Combining Lua and LIQ - -```lua -- Multi-step workflow local pages = query[[ from p = index.tag "page" @@ -142,11 +80,30 @@ end return pages ``` -## Important Notes +## Fetching SilverBullet Documentation + +The official SilverBullet instance at `silverbullet.md` serves raw Markdown pages. When you need details on any Space Lua feature, API, or concept, fetch the docs directly: + +```lua +-- Fetch a specific docs page by name (URL-encode spaces and slashes) +local content = net.readURI("https://silverbullet.md/.fs/Space%20Lua.md") + +-- List all docs pages to find what you need (requires X-Sync-Mode header) +local result = http.request("https://silverbullet.md/.fs", { + headers = { ["X-Sync-Mode"] = "true" } +}) +-- result.body is an array of {name, size, lastModified, ...} +for _, p in ipairs(result.body) do + -- p.name e.g. "Space Lua/Quirks.md" +end + +``` + +## Notes -- Always `return` values from lua_script — `print()` output is not captured +- Always `return` values from lua_script because `print()` output is not captured - The `X-Timeout` header controls execution timeout (1-21600 seconds, default 120) - Use `space.readRef("Page#Header")` to read specific sections - Use explicit variable binding in LIQ: `from p = ...` (not bare `from ...`) - Namespace your functions: `myPlugin = myPlugin or {}; function myPlugin.doThing() ... end` -- Use `-- priority: N` comments to control script load order (higher = earlier) \ No newline at end of file +- Use `-- priority: N` comments to control script load order (higher = earlier)