golk connects LegendKeeper, the worldbuilding wiki, to Go programs and to Claude. It has three parts:
| Part | What it is | For |
|---|---|---|
lk |
A Go SDK for the LegendKeeper v3 REST API: retries, idempotency, versioned writes, pagination, rate limiting, typed blocks, and a lossless Markdown converter | Go developers |
lk-mcp |
An MCP server with 60 task-shaped tools and 4 prompts, covering 100% of the LegendKeeper API, built on lk |
Claude Desktop (chat and Cowork), Claude Code and any MCP client |
| Claude Desktop extension and plugin | A one-click Claude Desktop extension (.mcpb), plus a plugin with two skills |
People who want Claude to read and write their wiki |
It was built for a DM who publishes a D&D world wiki that players read. So it puts correctness, data safety, and keeping DM-only content away from players ahead of speed:
- Versioned writes never overwrite an edit made in the app since Claude read the page.
- Every write tool has a dry run.
- An optional spoiler guard refuses any write that would show a protected term to players.
This project is not affiliated with or endorsed by LegendKeeper.
- Quick start (Claude Desktop)
- Install in Claude Desktop
- What Claude can do
- lk-mcp, the MCP server
- The spoiler guard
- LK Markdown
- The lk Go SDK
- Building from source
- Testing
- Repository layout
- Design documents
- Supported platforms
- License
You need an Apple Silicon Mac with Claude Desktop 3.6556.2 or later, a LegendKeeper project and an API key for it. Use a test project first.
Download lk-mcp-darwin-arm64.mcpb and legendkeeper-plugin.zip from the latest release, or build them yourself:
git clone https://github.com/swiftj/golk.git
cd golk
make mcpb plugin # needs Go 1.27+ and Node (npx) for the packer- Double-click
lk-mcp-darwin-arm64.mcpband enter your API key. - In a new chat, ask: "List my LegendKeeper projects."
- Recommended: in Claude Desktop, open Customize and choose Add › Upload plugin, then pick
legendkeeper-plugin.zip. This adds the two skills to every chat and every Cowork task. Cowork is part of Claude Desktop, so it uses the same extension, with nothing else to set up.
Cowork is part of Claude Desktop, so everything below covers both chat and Cowork. The integration has two pieces, installed separately. (Why not one file? A plugin can carry an .mcpb, but Claude Desktop ignores a local server inside a plugin in chat. Cowork ignores it too when a setting has no default, as the API key doesn't. The extension is what gets prompted for settings. See D-019.)
| Piece | File | Contains |
|---|---|---|
| Claude Desktop extension | dist/lk-mcp-darwin-arm64.mcpb |
The lk-mcp server binary and its settings. This is what gives Claude the LegendKeeper tools. |
| Plugin (skills) | dist/legendkeeper-plugin.zip |
Two skills that teach Claude to use the tools well: legendkeeper-wiki (pages, LK Markdown, hidden content, the guard) and legendkeeper-worldbuilding (maps, timelines, calendars, templates, boards). It holds no server and no key. |
Download both from the releases page, and check them with shasum -a 256 -c SHA256SUMS. Or build them:
make mcpb # dist/lk-mcp-darwin-arm64.mcpb (runs `npx -y @anthropic-ai/mcpb@2.1.2` to validate and pack)
make plugin # dist/legendkeeper-plugin.zip-
Open it in one of three ways:
- double-click
dist/lk-mcp-darwin-arm64.mcpb - drag it onto the Claude Desktop window
- in Claude Desktop, open Settings › Extensions › Advanced settings › Install Extension
- double-click
-
Fill in the settings:
Setting Required Meaning LegendKeeper API key yes The key of the one project Claude should work in. Claude Desktop stores it masked, and lk-mcp never writes it to a file or a log. Spoiler terms file no A text file of protected terms, one per line. Leave it empty for full DM access, so every write is allowed. Set it to turn on the spoiler guard. Read-only no Offer Claude only the read tools. -
Check that the extension is switched on in Settings › Extensions.
-
Start a new chat and ask "List my LegendKeeper projects." The answer names your project and ends with a line such as
read-only: false; spoiler guard: off (no terms file).
To change a setting later, open Settings › Extensions › LegendKeeper. To upgrade, install a newer .mcpb over the old one; your settings are kept.
In Claude Desktop, open Customize and choose Add › Upload plugin, then pick dist/legendkeeper-plugin.zip. Plugin skills apply to ordinary chats as well as Cowork tasks. You can see them under Customize › Skills.
Cowork runs inside Claude Desktop and uses the extensions installed there, so the LegendKeeper tools and your settings carry over. Start a Cowork task and ask, for example, "List my LegendKeeper projects, then add a paragraph to the Tree Fort page." If a task doesn't show the LegendKeeper tools, check that the extension is switched on in Settings › Extensions, then start a new task.
Run the binary directly and pass settings as environment variables (see Configuration). For example, in a client's JSON config:
{
"mcpServers": {
"legendkeeper": {
"command": "/path/to/golk/dist/lk-mcp-darwin-arm64",
"env": { "LEGENDKEEPER_API_KEY": "<your key>" }
}
}
}Build the plain binaries with make build. On Linux, use dist/lk-mcp-linux-amd64 or dist/lk-mcp-linux-arm64.
Once the extension is installed, you can ask for things like:
- "Find everything about the Candy Kingdom and summarise it."
- "Create a page for Princess Bubblegum under Characters, with an infobox for species and title."
- "Add a secret section to the Ice King's page saying he's really Simon Petrikov."
- "Hide the Lich's page from players.", or "Make the Mushroom War page visible to players."
- "Put a pin on the Ooo map at pixel 512, 300 named Tree Fort, linked to the Tree Fort page."
- "Add a timeline event 'The Mushroom War' in year −1000 on the History lane."
- "Save the Kingdom page as a template, then create Fire Kingdom from it."
- "On the Rivalries board, add the Fire Kingdom and an arrow from it to the Candy Kingdom."
- "Sort the children of Atlas alphabetically."
- "Tick off 'Find the Enchiridion' on the Quests page."
- "Add a Vitals meter to Finn's sidebar with HP 3 of 5."
- "Who are the members of this wiki?"
How it stays safe:
- Reads first. Claude reads a page, gets its
version, and edits with that version. If you changed the page in LegendKeeper since, the write is refused and Claude re-reads it. - Dry runs. Every write tool takes
dry_run, which describes the change without making it. Deletes, replaces and unhides are worth previewing. - Nothing silently dropped. Content that Markdown can't express (
lk-rawand::unsupportedblocks) is kept. Deleting it needs explicit permission (allow_remove_opaque).
lk-mcp is a single static binary that speaks MCP over stdio. stdout carries only protocol messages, and logs go to stderr. Logs never contain API keys, and page content is never logged at INFO.
Every tool carries MCP annotations (read-only, destructive, idempotent), and every write tool takes dry_run. Every tool takes an optional project when several projects are configured. Output is concise text with ids, names and versions, plus structured data. Errors include the LegendKeeper error code, the request ID and a hint.
| Area | Read tools | Write tools |
|---|---|---|
| Projects and search | list_projects, search, list_tags |
|
| Resources (wiki entries) | list_resources (in sidebar order, with ranks), get_resource |
create_resource (with a page, or 1–5 documents of any type), create_resources (up to 100 at once), update_resource (rename, tags, aliases, icon, lock, banner, permissions, move, reorder with after/before, hide or show), delete_resource, restore_resource |
| Documents (tabs) | (in get_resource) |
create_document (page, map, time, board, blank), update_document (rename, hide or show, tab order, full width, timeline calendar and chained sources), delete_document, restore_document |
| Pages | read_page (as LK Markdown, with its version) |
edit_page (the whole page) |
| Blocks | read_block |
insert_block, replace_block, update_block, move_block, delete_block, assign_block_ids |
| Properties and infoboxes | (in get_resource, read_block) |
set_property (any kind, sidebar or infobox), delete_property, set_row, delete_row |
| Assets | list_assets, get_asset |
upload_image (from a local file), create_asset_folder, update_asset, delete_asset |
| Maps | read_map |
set_map_feature (pins, labels, regions, paths, folders; place by lat/lng or by image pixel), delete_map_feature, set_map_image |
| Timelines | read_timeline |
set_timeline_lane, delete_timeline_lane, set_timeline_event, delete_timeline_event |
| Calendars | list_calendars, get_calendar |
create_calendar, replace_calendar, delete_calendar |
| Templates | list_templates |
save_as_template, create_from_template |
| Boards (tldraw canvases) | read_board |
add_board_shapes, update_board_shapes, delete_board_shapes, replace_board |
| Members and invites | list_members, list_invites |
invite_member (emails someone), remove_member, revoke_invite |
| Icons | find_icon (search the 1,402 Font Awesome 6 Free icons by idea or category; no API call) |
(set with icon_glyph on resources, map pins and timeline events) |
That's 18 read tools and 43 write tools. In read-only mode the write tools aren't registered at all.
Icon names are normalized before they're sent: fa- prefixes and capitals are dropped, and old Font Awesome 5 names are renamed (home → house). The icon directory comes from Font Awesome Free's metadata (MIT; see internal/fontawesome/NOTICE.md).
100% API coverage. Every one of the 89 operations of the LegendKeeper v3 API, and every request field, is reachable through these tools. docs/API_COVERAGE.md maps each operation and field to the tool parameter that carries it. A test checks that table against the API spec and the live tool schemas, so a gap fails the build.
lk-mcp also offers four MCP prompts. These are ready-made requests that walk Claude through a multi-step job in the right order:
| Prompt | Arguments | Does |
|---|---|---|
summarize_topic |
topic |
Finds and summarizes what the wiki says about a topic, marking what's DM-only. It only reads. |
edit_page_safely |
page, change |
Reads the page, makes only that change, previews it with a dry run, then writes with the version it read |
add_map_location |
map, place, where (optional) |
Places a pin on a map, linked to the place's page if one exists |
session_notes |
notes, session (optional) |
Turns rough session notes into a session page plus updates to the pages they touch, proposing the changes before making any |
The three write prompts exist only when the write tools do. Clients that support MCP prompts, such as Claude Code, list them for you. Whether Claude Desktop shows MCP prompts isn't documented, so the skills cover the same workflows.
The extension declares a minimum Claude Desktop version of 3.6556.2 (compatibility.claude_desktop in the manifest). That's the version it was tested with, because no documentation names an earlier one that supports manifest 0.3.
All settings come from the environment. The Desktop extension sets them for you.
| Variable | Meaning |
|---|---|
LEGENDKEEPER_API_KEY |
The key of the default project |
LEGENDKEEPER_API_KEY_<NAME> |
Adds a project named <name> (lower-case letters, digits, _). Tools take project: "<name>". |
LEGENDKEEPER_BASE_URL |
The API host (default https://www.legendkeeper.com) |
LK_MCP_READ_ONLY |
true registers only the read tools |
LK_MCP_GUARD_FILE |
The spoiler-guard terms file. Unset means no guard: every write is allowed. |
LK_MCP_GUARD |
off (or false) disables the guard even with a terms file; on (or true) is the default |
LK_MCP_LOG_LEVEL |
debug, info (default), warn or error |
Empty values count as unset, and a malformed value stops lk-mcp at startup with an error. lk-mcp --version prints the version.
What "hidden" means
LegendKeeper content is DM-only when it is any of these:
- a hidden resource (all of it)
- a hidden document (tab)
- a hidden sidebar property or infobox row
- inside a
:::secretblock
"Hidden" is each item's own flag: a resource does not inherit its parent's flag, and a document does not inherit its resource's.
The guard is optional. Without a terms file, Claude has full DM access, and list_projects reports spoiler guard: off (no terms file).
With a terms file (LK_MCP_GUARD_FILE, or the extension's Spoiler terms file setting), every write is checked before it is sent. A write that would put a protected term anywhere players can see it is refused, and the error lists each term and where it was found.
The terms file
- Plain text with one term per line. A multi-word term matches across line breaks and extra spaces.
- Keep it outside the wiki and out of any repository.
- Matching ignores case and invisible formatting characters, and matches whole words only.
- The file is reloaded when it changes. An empty file, or a file that changes while it is being read, refuses writes (fails closed) rather than switching protection off.
What is checked: everything the write would show players. That includes page blocks, names, tags, aliases, image URLs, sidebar properties, map features, timeline lanes and events, calendar specs, board shapes and template copies.
- Unhiding or restoring content checks everything it would reveal.
- Content that is DM-only (see What "hidden" means) may hold any term.
- Hidden map pins and hidden timeline events are still checked as if public. The API can't show what players see, so this stays the safe default until the owner confirms otherwise (
hiddenFeaturesConfirmedin the code).
The guard can't see edits you make in the LegendKeeper app, or text the server derives itself (such as formatted dates). See docs/DECISIONS.md D-011, D-014 and D-017 for its exact rules and known limits.
read_page and edit_page exchange pages as LK Markdown: CommonMark plus GFM (tables, task lists, strikethrough), with directives for LegendKeeper's own blocks. It is lossless. A page read and written back unchanged is byte-for-byte the same, and anything Markdown can't express is kept as an lk-raw JSON fence.
# The Ice King
:::callout tone=warning
Beware the **crown**.
:::
:::secret
He is really Simon Petrikov.
:::
:::keyvalue title=Stats
- Species :: Human (mostly)
- Title :: King of the Ice Kingdom
:::
See also [Gunter]{mention=gunter1}.Edits are matched to the base page by content, so block ids, unmodelled fields and comments survive an edit. The converter fails closed:
- raw HTML is refused
- a stray
::line is refused - a code fence that could swallow a
:::secretis refused - deleting opaque content needs explicit permission
The full spec is in docs/LK_MARKDOWN.md.
go get github.com/swiftj/golk/lklk matches the official TypeScript SDK (@legendkeeper/sdk) in behaviour, but is idiomatic Go in shape.
package main
import (
"context"
"errors"
"fmt"
"log"
"github.com/swiftj/golk/lk"
"github.com/swiftj/golk/lk/markdown"
)
func main() {
ctx := context.Background()
c, err := lk.NewFromEnv() // LEGENDKEEPER_API_KEY, LEGENDKEEPER_BASE_URL
if err != nil {
log.Fatal(err)
}
p, err := c.Project(ctx) // resolved once and cached
if err != nil {
log.Fatal(err)
}
fmt.Println("connected to", p.Name)
// Every list is an iterator; pagination is handled for you.
for r, err := range c.Resources.All(ctx, lk.ResourceListParams{}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(r.Name, r.ID)
}
// Create a resource, then edit its first page as Markdown.
r, err := c.Resources.Create(ctx, lk.ResourceCreate{Name: "The Tree Fort"})
if err != nil {
log.Fatal(err)
}
doc := lk.DocRef{ResourceID: r.ID, DocumentID: r.Documents[0].ID}
page, err := markdown.Get(ctx, c, doc)
if err != nil {
log.Fatal(err)
}
_, _, err = markdown.Replace(ctx, c, doc, page, "Home of **Finn** and **Jake**.\n", markdown.ReplaceOptions{})
if errors.Is(err, lk.ErrVersionMismatch) {
log.Fatal("someone edited the page since it was read; read it again")
} else if err != nil {
log.Fatal(err)
}
}Client and options
lk.New(apiKey, opts...).Newnever reads the environment;lk.NewFromEnv(opts...)does.WithBaseURL,WithHTTPClient,WithProjectID,WithTimeout(default 30s per attempt),WithMaxRetries(default 2),WithRateLimits/WithRateLimiter,WithoutIdempotencyKeys,WithLogger(*slog.Logger),WithUserAgent.- Per call:
lk.IfMatch(version),lk.WithIdempotencyKey(key),lk.ForProject(id),lk.CaptureResponse(&meta).
Behaviour (every rule is numbered in docs/SDK_CONTRACT.md and named by a test):
- Project: resolved once from the credential and cached. A key that reaches several projects is an error that asks for an explicit ID.
- Retries: GET, PUT, PATCH and DELETE retry on 429, 502, 503, 504, timeouts and connection failures, with exponential backoff and jitter.
Retry-Afteris honoured. Above 8s on a 429 or 503, the error is returned withRetryAfterset instead of retrying.- Every POST carries an
Idempotency-Key, reused on each retry, so POSTs retry safely too, including on 409IN_PROGRESS. - Never retried: context cancellation, 500, or any other 4xx.
- Versioned writes:
IfMatchsendsIf-Match, and a mismatch islk.ErrVersionMismatch, with the server's current version inAPIError.CurrentVersion. When a body lacks a version, it is taken from theETag. - Errors:
*lk.APIErrorcarriesStatus,Code,Message,Errors,RequestID,RetryAfterandCurrentVersion. Branch on the code witherrors.Is(err, lk.ErrNotFound)and similar, never on the message.*lk.ConnectionErrorwraps transport failures. - Three-state fields:
lk.Optional[T](omitted or set) andlk.Nullable[T](omitted,nullor set). Fields you don't set are never sent, and tests assert the exact JSON. - Rate limits: requests are paced client-side, below 120 writes/min and 300 requests/min per key. Use
Resources.CreateManyfor bulk creates. - Blocks:
lk/blocksholds a sealedBlockinterface with builders (blocks.P,blocks.H,blocks.Callout,blocks.KeyValue…) and readers (Walk,FindBlock,PlainText).- A kind the SDK doesn't know decodes into a raw block that keeps its JSON.
unsupportedblocks keep their ids.- Unmodelled fields round-trip.
Namespaces: Projects, Resources (with templates), Documents, Blocks, Properties, Search, Tags, Assets (with image upload), Features (map features), Timelines (lanes and events), Calendars, Templates, Boards, Members and Invites: every operation of the API. There are map helpers too: lk.PixelToPos and lk.PosToPixel. lk/markdown has ToMarkdown, FromMarkdown, Get and Replace (with DryRun).
Runnable ports of the examples in LegendKeeper's developer guide are in examples/. They are integration tests against a sandbox project.
Requirements:
- Go 1.27 or later
make- Node.js, for
npx, only to pack the Desktop extension golangci-lint,staticcheckandgovulncheckformake lint;make toolsinstalls pinned versions
| Command | Does |
|---|---|
make build |
Cross-compiles dist/lk-mcp-darwin-arm64, dist/lk-mcp-linux-amd64 and dist/lk-mcp-linux-arm64 |
make verify-static |
Checks every binary (and the one inside the .mcpb) was built with CGO_ENABLED=0, and that Linux binaries are statically linked |
make mcpb |
Packs the Claude Desktop extension dist/lk-mcp-darwin-arm64.mcpb |
make plugin |
Zips the skills plugin dist/legendkeeper-plugin.zip |
make lint |
gofmt, go vet, staticcheck, golangci-lint, govulncheck |
make test / make test-race |
Unit tests, without and with the race detector |
make test-integration |
Integration tests against a sandbox project (see below) |
make generate |
Regenerates lk/internal/gen from docs/legendkeeper/openapi.json |
Every release binary is static and CGO-free: no cgo dependency is allowed. The release version of the extension and plugin is in plugin/mcpb/manifest.json, and plugin/.claude-plugin/plugin.json must match it.
-
Unit tests run against
httptestfakes and assert each request exactly: method, path, query,Authorization,If-Match,Idempotency-Keyand the body JSON. Retry tests use an injected clock and random source, so they never sleep. -
Fuzz tests cover block JSON decoding and the Markdown converter.
-
Contract coverage: a test fails the build if any numbered requirement in
docs/SDK_CONTRACT.mdhas no test naming it. -
Integration tests (
-tags integration) run against a sandbox LegendKeeper project:export LK_SANDBOX_API_KEY=... # a key for a throwaway project export LK_SANDBOX_PROJECT_NAME="..." # that project's exact name make test-integration
They read the key's project first and abort unless its name equals
LK_SANDBOX_PROJECT_NAME, so they can never touch a real wiki. Every test deletes what it creates, all tests share one rate limiter, and a final sweep fails the run if anything was left behind. They never readLEGENDKEEPER_API_KEY.
cmd/lk-mcp/ MCP server entrypoint
lk/ public SDK: client, options, errors, retry, pagination, namespaces
lk/internal/gen/ generated from openapi.json (never hand-edited; `make generate`)
lk/blocks/ block types, builders, readers
lk/markdown/ LK Markdown <-> blocks, Get/Replace
internal/mcpserver/ MCP tools, config, output, errors
internal/mcpserver/guard/ the spoiler guard
internal/sandbox/ guarded sandbox client for integration tests
internal/cmd/lkgen/ the code generator
examples/ ports of the guide's examples (integration-tagged)
plugin/ Desktop extension manifest, skills plugin
docs/ sources of truth, contract, decisions, LK Markdown spec
scripts/ build verification
| Document | What it holds |
|---|---|
docs/SDK_CONTRACT.md |
Every numbered behavioural requirement (C-* SDK, M-* Markdown, X-* MCP), each tested |
docs/DECISIONS.md |
Every non-obvious choice, sandbox probe result and conflict between the LegendKeeper spec and guide (D-001 to D-021) |
docs/API_COVERAGE.md |
Every API operation and request field, and the tool parameter that carries it |
docs/LK_MARKDOWN.md |
The LK Markdown format and its fail-closed rules |
docs/legendkeeper/ |
LegendKeeper's public API docs, the build's sources of truth (see NOTICE) |
plugin/README.md |
Short install guide for the extension and plugin |
CLAUDE.md |
The working rules this project was built under with Claude Code |
| Platform | Binary | Claude Desktop extension |
|---|---|---|
| macOS, Apple Silicon | lk-mcp-darwin-arm64 |
lk-mcp-darwin-arm64.mcpb |
| Linux x86-64 (e.g. servers, AWS Lightsail) | lk-mcp-linux-amd64 |
— (no Claude Desktop for Linux) |
| Linux ARM64 | lk-mcp-linux-arm64 |
— |
Windows and Intel Macs are deliberately not supported.
The code is under the MIT License. The files in docs/legendkeeper/ are copies of LegendKeeper's public developer documentation. They are not covered by this license and remain LegendKeeper's; see NOTICE.