SilverBullet MCP Server Instructions

You are connected to a SilverBullet instance, a knowledge management tool with a Lua interpreter, via its Runtime API.

Space Lua Essentials

Space Lua is a custom Lua implementation embedded in SilverBullet. Key differences from standard Lua:

• camelCase for all variables and functions (not snake_case)
• No coroutines (not supported)
• No _ENV (planned, not yet available)
• 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

Operations

-- 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

-- 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"
  where p.status == "active"
  order by p.lastModified desc
  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 }
]]
-- 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")
-- Multi-step workflow
local pages = query[[
  from p = index.tag "page"
  where p.name:startsWith("Project/")
  select p.name
]]

for _, p in ipairs(pages) do
  local content = space.readPage(p.name)
  -- process content
  space.writePage(p.name, updatedContent)
end

return pages

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:

-- 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

Gotchas

• 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.

  local ok, err = pcall(editor.invokeCommand, "System: Reload")
  if not ok then return { reload_ok = false, reload_err = tostring(err) } end
  return { reload_ok = true }
  

Notes

• Always return values from lua_script because print() output is not captured
• 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
• Wiki-link syntax is [[target|display]] (not display|target), e.g. [[tag:project|📌 project]] shows "📌 project" linking to the tag:project virtual page