src/kioku_mcp/ — the server: server.py
(tools, /upload, auth), anki_backend.py,
trilium_backend.py, files.py (files passed by
reference), config.py (environment set by the NixOS
module), publish_skills.py.nix/ — package.nix,
module.nix (services.kioku-mcp) and
test.nix (VM test).skills/ — convention docs, published as Open WebUI
skills.skills.toml — which docs are published, and the
workspace models created with them.openwebui/ — the default_terminal
filter.docs/ — this documentation; docs-html/
holds the compiled HTML.A skill is a doc under skills/ plus a
[[skill]] entry in skills.toml with its id,
tag, name and description. The tag groups it and selects it for the
models whose tags list it. Docs refer to each other as
<skill id> (<FILE>.md), which resolves both in
the repo and in Open WebUI.
Templates — a doc whose entry sets
template = true is rendered with Jinja before publishing,
with the variables from [openwebui] of
secrets.toml (reference Open WebUI). Docs without it
are published verbatim, since e.g. CARDS.md quotes Anki’s
own double-brace field syntax. skills.toml itself is always
a template, which keeps deployment values such as the base model out of
the repo.
Models — a [[model]] entry creates or
updates one workspace model:
[[model]]
id = "kioku"
name = "Kioku"
base_model = "{{ base_model }}"
system = """..."""
tags = ["kioku", "diagrams"]
tools = ["server:mcp:kioku"]
terminal = true
disable_builtin = ["notes"]Name, base model, description and system prompt are overwritten on every publish; tools, skills and filters are merged into what the model already has.
nix flake check boots a NixOS VM with real
anki-sync-server and trilium-server instances
and exercises every write path, backup restore, the full-sync policy,
Trilium revisions and attachments, files by reference (sandbox paths,
uploads, path escapes), auth and restarts. Forgejo Actions runs it on
every push and pull request (.forgejo/workflows/ci.yml);
there is no need to run it locally. The VM needs KVM, so the runner
passes /dev/kvm to job containers. A push or pull request
whose commits are all docs:, chore: or
style: skips the test, unless one of them touches
src/, nix/, flake.nix,
flake.lock or pyproject.toml.
The nixos repo pins this flake and runs the server from it. After
pushing here, update the pin in the nixos repo, then rebuild the server
there; rebuild desktop and laptop too when kioku-client.nix
changed:
nix flake update kiokupublish-skills runs from a checkout of this repo, not
from the deployment: rerun it after changing a doc or
skills.toml (reference Open WebUI).
Anki version — the pin follows the nixos repo’s
anki-suite input, shared with anki-sync-server
(reference Server). Neither moves
on a general nix flake update. Move them only deliberately,
and run the VM test against the new pin before deploying:
nix flake update anki-suiteThe docs compile with tern and its pandoc template, installed into
.tern/ and pinned in .tern/config.toml. Two
installs of the template give two profiles: docs/ and the
top-level README.md, both into docs-html/.
After changing .tern/config.toml, reinstall:
nix develop path:.#docs --command tern -uThen compile:
nix develop path:.#docs --command tern