1# SilverBullet MCP Server Instructions
2
3You are connected to a SilverBullet instance, a knowledge management tool with a Lua interpreter, via its Runtime API.
4
5## Space Lua Essentials
6
7Space Lua is a custom Lua implementation embedded in SilverBullet. Key differences from standard Lua:
8
9- **camelCase** for all variables and functions (not snake_case)
10- No coroutines (not supported)
11- No `_ENV` (planned, not yet available)
12- `print()` output is swallowed in Runtime API — use `return` to send results back
13- `query[[...]]` is LIQ (Lua Integrated Query), a SQL/LINQ-inspired query syntax embedded in Lua
14
15## Operations
16
17```lua
18-- Read a page
19local content = space.readPage("MyPage")
20-- Write a page
21space.writePage("MyPage", "# Hello\n\nContent here")
22-- Delete a page
23space.deletePage("MyPage")
24-- Check if a page exists
25if space.pageExists("MyPage") then
26 -- ...
27end
28-- List all pages
29local pages = space.listPages()
30-- Get page metadata
31local meta = space.getPageMeta("MyPage")
32-- meta.name, meta.lastModified
33
34-- Find pages tagged #task
35local tasks = query[[
36 from p = index.tag "task"
37 select p.name
38]]
39-- Find pages that link to a specific page
40local links = query[[
41 from l = index.tag "link"
42 where l.toPage == "TargetPage"
43 select l.fromPage
44]]
45-- Filter by frontmatter
46local projects = query[[
47 from p = index.tag "page"
48 where p.status == "active"
49 order by p.lastModified desc
50 select p.name
51 limit 10
52]]
53-- Count items in a group
54local counts = query[[
55 from p = index.tag "tag"
56 group by p.name
57 select { name = name, count = #group }
58]]
59-- List all files
60local files = space.listFiles()
61-- Read a file (returns bytes as string)
62local data = space.readFile("image.png")
63-- Write a file
64space.writeFile("data.json", jsonString)
65-- Read a specific section
66local section = space.readRef("MyPage#Introduction")
67-- Multi-step workflow
68local pages = query[[
69 from p = index.tag "page"
70 where p.name:startsWith("Project/")
71 select p.name
72]]
73
74for _, p in ipairs(pages) do
75 local content = space.readPage(p.name)
76 -- process content
77 space.writePage(p.name, updatedContent)
78end
79
80return pages
81```
82
83## Fetching SilverBullet Documentation
84
85The 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:
86
87```lua
88-- Fetch a specific docs page by name (URL-encode spaces and slashes)
89local content = net.readURI("https://silverbullet.md/.fs/Space%20Lua.md")
90
91-- List all docs pages to find what you need (requires X-Sync-Mode header)
92local result = http.request("https://silverbullet.md/.fs", {
93 headers = { ["X-Sync-Mode"] = "true" }
94})
95-- result.body is an array of {name, size, lastModified, ...}
96for _, p in ipairs(result.body) do
97 -- p.name e.g. "Space Lua/Quirks.md"
98end
99
100```
101
102## Gotchas
103
104- `System: Reload` via `editor.invokeCommand` is **asynchronous**: it returns before the reload has actually completed. Any verification that must observe the post-reload runtime state should happen in a separate `execute_lua` call a moment later, not immediately after the reload in the same script.
105 ```lua
106 local ok, err = pcall(editor.invokeCommand, "System: Reload")
107 if not ok then return { reload_ok = false, reload_err = tostring(err) } end
108 return { reload_ok = true }
109 ```
110
111## Notes
112
113- Always `return` values from lua_script because `print()` output is not captured
114- Use `space.readRef("Page#Header")` to read specific sections
115- Use explicit variable binding in LIQ: `from p = ...` (not bare `from ...`)
116- Namespace your functions: `myPlugin = myPlugin or {}; function myPlugin.doThing() ... end`
117- Wiki-link syntax is `[[target|display]]` (not display|target), e.g. `[[tag:project|📌 project]]` shows "📌 project" linking to the tag:project virtual page