AGENTS.md

sb-mcp

Commands

go build ./...                  # build all
go test ./...                   # test all
go test ./internal/silverbullet/ # test single package

Build with version: go build -ldflags "-X git.secluded.site/sb-mcp/internal/server.Version=$VERSION" ./cmd/sb-mcp/

Run: sb-mcp serve (stdio) or sb-mcp serve --http :3001 (streamable HTTP)

Landmines

  • print() is silently swallowed in the Runtime API. Always use return to send results back from execute_lua. No error, no warning — just empty output.
  • Space Lua is camelCase, not snake_case. All built-in functions (space.readPage, space.writePage) use camelCase. Writing space.read_page will fail.
  • Bearer auth and password auth coexist — SB_TOKEN sets Authorization: Bearer ..., while SB_USER/SB_PASS logs in via POST /.auth and sends a session Cookie. They use different headers, no override. For proxy auth (e.g. Exe.dev), use SB password authentication with Exe Bearer auth or SB Bearer auth with Exe HTTP Basic credentials embedded in SB_URL (https://user:pass@host).
  • Timeout clamping: Lua timeouts <1 are clamped to 1, >21600 clamped to 21600. No error raised; the value silently changes.

Environment

Required: SB_URL (must be http(s)). Optional: SB_USER/SB_PASS (basic auth), SB_TOKEN (bearer), SB_TIMEOUT (seconds, default 120).