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.

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

Page 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

Querying with LIQ

LIQ (query[[...]]) is the primary way to search and filter data:

-- Find pages tagged #task
local tasks = query[[
  from p = index.tag "task"
  select p.name
]]

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

File/Document Operations

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

local pages = query[[
  from p = index.tag "page"
  where p.priority == "high"
  select { name = p.name, priority = p.priority }
]]

Working with Tasks

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

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

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

Important Notes

Always return values from lua_script — 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)

silverbullet.md