Notes that stay in order.
A fast, minimal, self-hosted markdown wiki. Plain .md files are the database — agents write through MCP, you read.
Quickstart · Features · Configuration · API & MCP · Architecture · Development
- What is stichpunkt?
- Demo
- Features
- Screenshots
- Quickstart
- Usage
- Configuration
- API & MCP
- Operations
- Architecture
- Development
- Contributing
- License
Stichpunkt is German for "bullet point". It is a small wiki server built around one idea: your knowledge base is just a directory of markdown files. The server renders those files to a fast, mobile-first reading UI, keeps an in-memory index for search, tags and backlinks, and exposes the same operations over a REST API and an MCP server.
The web UI is deliberately read-only. Changes are made by agents (or scripts) writing through MCP or the token-protected REST API, so humans get a clean reading experience and agents get a safe, conflict-aware write path. The single exception is the MANIFEST editor on /manifest, which validates and saves that one system page in place. Because the files are plain markdown, you can still edit, sync, grep and back them up with any tool you like.
A public demo runs at https://stichpunkt.salen7in.de. It follows the latest commit on main and is redeployed automatically a few minutes after each push.
- The demo uses example content only (the
examples/knowledgefolder), bundled into the image as a fallback whenSPACE_DIRis absent or empty. A non-empty mounted space overrides the examples. - The demo is not connected to any production instance or knowledge base. Its write API is closed: the access token is generated at each start and never stored, so agents cannot write to it.
Reading experience
- Folders are namespaces (
Server/SilverBullet.md→ pageServer/SilverBullet);Library/is hidden from navigation. - CommonMark + GFM, frontmatter,
[[Page]],[[Page|alias]],[[Page#Heading]]wikilinks,#tags(inline and frontmatter) and syntax-highlighted code. - Mobile-first shell (bottom bar and sheet), three columns on desktop, quick switcher (Ctrl/⌘+K), breadcrumbs, outline, backlinks and a properties rail.
- Callouts (
> [!note],[!tip],[!warning], … with+/-for foldable ones), footnotes ([^1]), emoji shortcodes (:tada:) and transclusion (![[Page]],![[Page#Heading]], nested up to 3 levels with a loop guard); see theFeatures/demo pages. - Full-text search ranked by BM25 over sections and fields, with German stemming, compound splitting (
Arzttermin→Arzt+Termin), quoted phrases,#tag/in:folderfilters, highlighted snippets around the best match and folder/tag facets. Collection rows are searchable too: they rank on the same scale as pages in one result list, and opening a row hit goes straight to that row in its table. - Automatic
/tag/<name>pages; tag metadata can be declared inCONFIG.mdwithtag.define(parsed, never executed). - Live reload: the UI and the installed PWA follow content changes (API/MCP writes and file edits) over server-sent events (
/_ui/events). The changed blocks flash, the tree and Recent update, a notice appears, and nothing reloads while text is selected. Reconnects catch up automatically; the footer shows the connection state. Behind a reverse proxy, response buffering must be off for/_ui/events(the app sendsX-Accel-Buffering: no, which nginx honours; Traefik streams by default). - Installable PWA (Chrome on Android: "Install" button in the header or menu → Install app); the service worker caches the shell and the last ~50 visited pages for offline reading and shows an offline page for anything not yet visited. The manifest ships a phone and a desktop screenshot for Chrome's richer install dialog. Installing requires HTTPS (or
localhost).
Themes
- A selector in the header offers Light, Dark and System (default; follows the OS preference). The choice is stored in the browser (
localStorage) and applied before first paint, so there is no flash on reload. - All colours are CSS variables in
src/app.css; adding another theme means adding one:root[data-theme='…']block.
Diagrams
- Client-side and lazy: Mermaid rendered by Pele, Vega-Lite, KaTeX.
- Other fence languages (PlantUML, Graphviz, D2, ...) are not rendered; they appear as ordinary code blocks.
- A placeholder holds the space until the figure is ready; broken diagrams show the error and the source.
Declarative queries
- A fenced
```pagesblock with a small YAML body lists pages from the index: filterstag,folder,links-to;sortbytitle,modified,dateor any frontmatter key;showaslist,tableorcount;limitdefaults to 50 (max 200). - Strictly validated (js-yaml CORE + zod) — no expressions, no regex, nothing executed. The same engine backs the
${...}expressions, thequery_pagesMCP tool andPOST /api/v1/query.
Collections (SQLite databases)
- Typed tables in SQLite at
/var/lib/stichpunkt/collections.sqlite(COLLECTIONS_DBoverrides; app state, deliberately outside the mounted space), with properties (title,text,number,select,multi_select,date,checkbox,url,email), rows and cells as real records. - Notion-style table view at
/databases: filter bar, click-to-sort columns, saved views, typed cell rendering and live reload over the existing SSE stream. - Row values join the full-text search: hits open the row directly (
/databases/<collection>?edit=<row>), and the index follows edits within a quarter second — no restart. - Filtering and sorting run in SQL with bound parameters;
base_updated_atgives optimistic concurrency; every row change is recorded with an actor. - REST API under
/api/v1/databasesand the same guarantees over MCP (list_collections,get_collection,query_collection_rows,create_collection_row,update_collection_row,delete_collection_row,save_collection_view,collection_history);import/previewreports the Markdown tables of a page before any migration,export?format=csv|jsonreturns a portable snapshot of one collection. See docs/collections.md. GET /api/v1/exportandnpm run exportwrite the whole instance (all pages, all collections, versioned header) as one bundle. See docs/export.md.- Requires the space on local disk — SQLite must not run on the rclone/FUSE mount.
Expressions
${ ausdruck }is evaluated by a small, own expression language: a Pratt parser and tree-walking evaluator written in TypeScript, with noeval, no Lua and no JavaScript runtime.- Server-side and read-only: literals, arithmetic and comparison,
and/or/not,??and?:, field access and a fixed whitelist of builtins (pages,count,page,sum/min/max/avg,len,join,lower/upper,round,today/date/days/fmt_date,link). Records areMaps, so there is no JS property lookup. - Strict limits: 500 characters, 50 expressions, AST depth 32, a 10000-step budget, 20 engine queries per page and 10000-character strings. Output is always escaped.
- An unreadable body stays a quiet chip; a runtime failure becomes a red chip with the message and the source.
SilverBullet compatibility
- SilverBullet-only syntax (
space-lua,space-style,query,template) renders as an inert chip and is never executed. - The four known
${kb.*}helper calls (kb.section,kb.recent,kb.header,kb.categories) are recognised before the expression grammar and rendered as built-in server-side widgets. Every other${...}in the old Lua style stays an inert chip.
Agent-friendly writes
- MCP tools and REST endpoints for search, read, write, append, delete, expression evaluation and attachment upload.
- Optimistic concurrency via content hash (
base_hash, 409 on conflict) and per-file write serialisation. - Path safety:
.., absolute paths, backslashes, dot-files and symlinks leavingSPACE_DIRare rejected.
Screenshots show the bundled examples/knowledge/ space (dark theme). See Development to run it yourself.
Requires Docker with Compose. (Without Docker you need Node.js ≥ 22.)
git clone https://github.com/ssalentin/stichpunkt.git
cd stichpunkt
cp .env.example .env # set MDWIKI_API_TOKEN (openssl rand -base64 32)
mkdir space # or copy your markdown directory here
STICHPUNKT_COMMIT=$(git rev-parse HEAD) docker compose up -d --buildThe footer shows the app version and the commit the build comes from. The Docker build has no .git, so pass the commit as shown; without it the footer says unknown.
The sample compose.yml starts stichpunkt (port 3000 inside the container) behind your reverse proxy. It does not publish a port — put your reverse proxy in front (see Reverse-proxy contract).
Without Docker:
npm ci && npm run build
SPACE_DIR=./space MDWIKI_API_TOKEN=… node build/index.jsRead — open the site through your proxy. Browse by folder, search, or press Ctrl/⌘+K for the quick switcher.
Write from an agent — register the MCP server, for example with Claude Code:
claude mcp add --transport http stichpunkt https://stichpunkt.example.org/mcp \
--header "Authorization: Bearer $MDWIKI_API_TOKEN"Write from a script — use the REST API:
curl -X PUT https://stichpunkt.example.org/api/v1/pages/Notes/Hello \
-H "Authorization: Bearer $MDWIKI_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "# Hello\n\nA first note #demo", "base_hash": ""}'base_hash: "" means "the page must not exist yet".
Query pages from markdown — put this in any page:
```pages
tag: project
sort: modified desc
show: table
columns: [title, status]
limit: 20
```Set via environment variables (see .env.example).
| Variable | Default | Meaning |
|---|---|---|
SPACE_DIR |
./space (/space in the image) |
markdown directory |
SPACE_FALLBACK_DIR |
– (/app/examples/knowledge in the image) |
read-only example space used when SPACE_DIR is absent or empty |
MDWIKI_API_TOKEN |
– | bearer token for /mcp and /api; at least 32 characters; empty, shorter or change-me = both always answer 401 (a startup error is logged). openssl rand -base64 32 gives 44 |
POLL_INTERVAL |
10000 |
ms between mtime polls for changes made outside the app (CIFS has no reliable inotify) |
MAX_WRITE_BYTES |
1048576 |
max size of a page write |
MAX_UPLOAD_BYTES |
20971520 |
max size of an attachment |
HISTORY_KEEP |
50 |
revisions kept per page under .history/; 0 keeps every revision |
COLLECTIONS_DB |
/var/lib/stichpunkt/collections.sqlite |
SQLite file behind /databases |
DEPLOYED_SHA_FILE |
/var/lib/stichpunkt/deployed.sha |
commit reported by /healthz; missing is not an error |
BACKUP_LOG |
/var/lib/openbot/backup.log |
log whose last backup ok <stamp> line /healthz reads |
HEALTHZ_MAX_BACKUP_AGE_SECONDS |
129600 (36 h) |
older backup evidence turns /healthz into 503 |
BODY_SIZE_LIMIT |
25M (image) |
adapter-node request body limit; keep ≥ MAX_UPLOAD_BYTES |
PORT, HOST, PROTOCOL_HEADER, HOST_HEADER |
adapter-node settings |
Allowed file extensions (read/write/upload): md txt csv json pdf png jpg jpeg gif webp avif heic svg.
The display name, tagline and brand palette live in one place: src/lib/brand.ts.
Naming note: the project was renamed to
stichpunkt, except forMDWIKI_API_TOKEN, theX-Mdwiki-Zoneproxy header and the npm package name, which keep the old id as an internal contract.
The app serves plain HTTP; TLS is terminated by the proxy, so set PROTOCOL_HEADER=x-forwarded-proto and HOST_HEADER=x-forwarded-host, otherwise SvelteKit assumes https for generated URLs.
The web UI has no login of its own, so two routers are needed:
| Router | Paths | Auth | X-Mdwiki-Zone |
|---|---|---|---|
| UI | everything else | your SSO (e.g. Authelia) | must not set |
| Machine | /mcp, /api (see rule below) |
bearer token | must set machine (overwriting any client value) |
Match the machine router with Path(`/mcp`) || PathPrefix(`/mcp/`) || Path(`/api`) || PathPrefix(`/api/`), not a bare PathPrefix(`/api`), which is a plain string match and also catches /apix and /mcp-foo.
With the header present, the app requires the token for every path on that request. This closes path tricks like /api/%2e%2e/_ui/page, which a proxy matching the raw path could otherwise forward as /_ui/page. In Traefik, use a headers middleware with customRequestHeaders.
All routes require Authorization: Bearer <token>. Page names are paths without .md.
| Method and path | Purpose |
|---|---|
GET /api/v1/search?q=&limit=&include_working= |
full-text search over pages and collection rows (working pages hidden by default); the response carries a rows count, and a row hit has a row object with its href |
GET /api/v1/pages?prefix=&include_working=&limit=&offset= |
{pages,total,truncated} (working hidden by default) |
GET /api/v1/pages/<path> |
{content, frontmatter, hash, mtime} |
PUT /api/v1/pages/<path> |
{content, base_hash?}; stale base_hash → 409 with current; base_hash: "" = must not exist |
POST /api/v1/pages/<path> |
{content} append |
DELETE /api/v1/pages/<path> |
delete |
GET /api/v1/tags, GET /api/v1/tags/<name> |
tags, pages by tag |
GET /api/v1/backlinks/<path> |
backlinks |
POST /api/v1/query |
run a pages query ({tag?, folder?, links-to?, sort?, limit?, show?, columns?, self?, include_working?}) |
PUT /api/v1/attachments/<path> |
raw body upload, any allowed type |
GET /api/v1/manifest |
the agent manifest: {exists, path, hash, rules, prose} or {exists: false} |
GET /api/v1/manifest/check |
{ok, issues}; validates the manifest without writing |
POST /api/v1/validate |
{path, content} → {warnings}; checks a page against the manifest, writes nothing |
POST /api/v1/pages/move |
{from, to, dry_run?, overwrite?} → {from, to, dry_run, moved, rewritten, unresolved, warnings, hash, previous_hash?} |
POST /api/v1/pages/batch |
{pages: [{path, content, base_hash?}], dry_run?} → {dry_run, written} |
GET /api/v1/links?path=&include_hidden= |
{dead, ambiguous, orphans, anchors, counts} |
GET /api/v1/export |
the whole instance as one JSON bundle (pages plus all collections); see docs/export.md |
GET /api/v1/history/<path>?limit= |
revision list, newest first |
GET /api/v1/diff/<path>?since= |
unified diff against a revision (id, hash prefix or ISO time) |
GET /api/v1/activity?since=&actor=&folder=&page=&limit= |
revision activity across pages |
MCP (POST /mcp, Streamable HTTP, stateless) tools: search, list_pages, read_page, write_page, write_pages, append_to_page, move_page, delete_page, check_links, check_manifest, history, diff, activity, list_tags, pages_by_tag, get_backlinks, query_pages, evaluate, list_collections, get_collection, query_collection_rows, create_collection_row, update_collection_row, delete_collection_row, save_collection_view, collection_history, upload_attachment, get_manifest, validate_page.
See docs/tools.md for every page operation with signature and example.
write_page, write_pages, append_to_page (and the REST writes behind them) return warnings: [{rule, message, line?}], always present and empty when the page fits the manifest.
- move_page renames or moves a page in one transaction and rewrites only the links that would stop resolving to it. A unique-basename link (
[[Contact]]) keeps working and stays as written;[[Notes/Contact]]and relative links that no longer resolve are rewritten.#Heading,|aliasand![[…]]survive, and nothing inside fenced or inline code is touched. An existing destination is a409 target_exists;dry_runreturns the plan without writing. - write_pages writes several pages atomically: sorted locks, all
base_hashvalues checked before the first write (""= must not exist), one index rebuild. One stale hash returns409with every conflict inconflictsand changes nothing; an unexpected disk error rolls already written files back. Duplicate paths in one batch are a400. - check_manifest validates the manifest against the schema and the space (unknown keys/enums,
allowed_tagswithouttag.define, folders without pages, colliding folder keys) and returns{ok, issues}. Read-only. - history lists the revisions every MCP/REST write keeps under
.history/(newest first, deletion and move markers included; each record carries version, actor,actor_source, tool, byte counts, warning rules and an optional note). activity lists revisions across pages with filters. diff returns a unified diff against a revision id, a hash prefix or a date. Direct file edits are not versioned. Details:docs/tools.md. - check_links is read-only:
dead(target does not resolve),ambiguous(bare basename with several candidates),orphans(no incoming link; root pages are marked),anchors(#Headingthat does not exist).pathlimits the audit to one page or folder;include_hiddenalso checks pages that are hidden from navigation (the repository's hidden prefix,Library/by default).
The optional folders.<name>.layer (reading, working, config, default reading) groups pages for readers. With no layer declarations, nothing changes. Pages of the working layer are hidden from search, list_pages and query_pages unless include_working: true is passed; an explicit in:folder filter is only a filter and does not unlock them. Every result carries its layer; list_pages returns {pages,total,truncated} and accepts limit (default 200) / offset; search adds per_page: [{path,count,layer}].
layers.<layer> can override label, pages (the same page-rule keys as the global block, per key) and checks (replacing the global list when set). layers.pages maps exact page paths to a layer (for root pages such as MANIFEST/CONFIG); a page's frontmatter layer comes next, then the folder layer. viewLabels.all renames the third switch (default All). The web app has a Notes/Working/All switch in the sidebar (labels from the manifest, default English), persisted in localStorage; the search page follows it without leaving the page, and working pages show a "draft, not curated" badge. This is visibility, not access control.
Optional. A page named MANIFEST (MANIFEST.md in the space root) holds the documentation rules of the space. The frontmatter is machine-readable, the body is prose for humans and agents. Without it Stichpunkt behaves exactly as before.
---
manifest: 1 # required, version
summary: "..." # required, 1..2000 chars, sent to agents as MCP `instructions`
pages: # optional
required_frontmatter: [updated] # keys every page must carry
allowed_tags: [project, runbook] # frontmatter tags allowed (with the `frontmatter` check)
forbidden_prefixes: ["Sources:"] # lines starting like this (trimmed, outside code fences)
stand_field: updated # date key for `stand_age` (default: updated)
stand_max_age_days: 90 # limit for `stand_age` (default: 90)
require_agent: false # true: a write without an actor warns `missing_actor`
folders: # optional; key = top-level folder
Notes: { owner: "Team", description: "..." } # owner, template, description: optional strings
actors: # optional; display names for history/activity
team: { name: "Team" }
checks: [secrets, links] # optional; see docs/manifest.md for all checks
---
Prose: the full rules in plain words.All levels are strict: an unknown key makes the manifest invalid, so a typo cannot silently turn a rule off. A complete example is in examples/MANIFEST.md.
- Reading. On MCP connect agents get the
summaryplus a pointer toget_manifestasinstructions;get_manifest(andGET /api/v1/manifest) returnsrules,proseand the contenthash. - Writing. There is no special write tool: use
write_page("MANIFEST", …, base_hash). An invalid manifest (YAML error, missingmanifest/summary, unknown key,summarytoo long) is rejected with400 manifest_invalidplus the issues, and the file stays unchanged.delete_page("MANIFEST")switches the feature off. If the file is edited outside the app, a valid change is picked up by the poll; an invalid one is logged and the last valid manifest stays active (at startup: no manifest,get_manifestreturnsmanifest_invalid). - Checking. Page writes never fail because of the manifest; they return
warningsfor the resulting page:missing_frontmatter,forbidden_prefix,unknown_folder(only whenfoldersis set; root pages are skipped),possible_secret(private-key headers, GitHub tokens,sk-keys, AWS access keys, Slack tokens, longBearertokens), with thelinkscheckdead_linkfor every wikilink whose target does not exist, withfrontmattertag_not_allowedfor tags outsidepages.allowed_tags, withownerowner_mismatchwhen the acting agent (agentargument orX-Agentheader) differs from the folder owner, and withstand_agestand_missing/stand_unparseable/stand_stalefor the configured stand date. Full schema:docs/manifest.md. Apossible_secretwarning names only the rule and the line, never the value.validate_page/POST /api/v1/validatereturn the same warnings without writing.
GET /healthz answers 200 when all checks pass and 503 otherwise. It needs no token, so the deploy script and an uptime monitor can call it; the body never contains filesystem paths, tokens or row content.
{
"status": "ok",
"checked_at": "2026-11-02T19:56:48.000Z",
"checks": {
"database": { "ok": true, "integrity": "ok", "schema_version": 0 },
"write": { "ok": true, "mode": "begin_immediate_rollback" },
"deployed": { "ok": true, "present": true, "sha": "45996c4", "age_seconds": 90 },
"backup": { "ok": true, "last_at": "2026-11-02T18:22:00.000Z", "age_seconds": 5688, "max_age_seconds": 129600 }
}
}databaserunsPRAGMA integrity_checkon a read-only connection and reportsPRAGMA user_version.writetakes the write lock withBEGIN IMMEDIATEand rolls it back: it proves the write path without inserting a row or a revision.deployedreports the commit indeployed.sha; before the first deploy the file is missing and stillok.backupfails when the lastbackup okentry is older than 36 hours.
GET /api/v1/export returns the whole instance as one JSON bundle (every page, every collection, format version and timestamp in the header); npm run export writes the same bundle as a directory tree without a running server. The restore procedure and the limitations (binary attachments are not included) are documented in docs/export.md.
The production deploy script proves every new build can write before it swaps the build into the
service: read a collection, create a scratch row, refuse a stale write with 409, delete the row.
A build that fails any step is not deployed, and the previous build keeps serving. The gate runs
against a throwaway copy of the database, so it never touches live data. Failure modes, the
--gate and --gate-test modes and the refusal test hook: docs/deploy-gate.md.
Token rotation
- Generate a new token:
openssl rand -base64 32; store it in your password manager. - Put it into
.envasMDWIKI_API_TOKEN. docker compose up -d stichpunkt(recreates the container; the web UI is unaffected).- Update the clients (agent runtimes,
claude mcp add … --header). The old token stops working immediately.
Stopping
docker compose stop— keep containers.docker compose down— remove containers;space/is a bind mount and is never touched.
browser ──► UI proxy router (SSO) ───────┐
▼
agents ──► machine router (bearer) ──► stichpunkt (SvelteKit, adapter-node)
+ X-Mdwiki-Zone: machine │ ├─ web UI src/routes
│ ├─ REST API src/routes/api/v1
│ ├─ MCP server src/routes/mcp
│ └─ in-memory index (pages, tags, backlinks, search)
│
▼
SPACE_DIR (*.md)
- Files are the source of truth. The index is rebuilt in memory and refreshed by polling mtimes, so edits made outside the app show up too.
- One service layer, three front doors. The UI, REST API and MCP tools share the same operations (
src/lib/server/service.ts). - Server code lives in
src/lib/server/(store, markdown rendering,pagesquery engine, auth, path safety, MCP); diagram handling is behind one registry insrc/lib/diagrams.ts. - Single container.
npm ci
npm test # vitest: renderer, index, search, polling, conflicts, path safety, auth, MCP
npm run check # svelte-check
npm run search:eval # golden-list ranking check against SPACE_DIR (hit@3, mean rank)
npm run build
npm run dev # vite dev serverTry every feature against the example space:
SPACE_DIR=examples/knowledge node build/index.jsTest fixtures live in test/fixtures/space (synthetic, no real content).
Things to know
- Writes inside one process are serialised per file; optimistic concurrency via content hash protects against other writers, but the check-then-rename window against an external process writing at the same instant cannot be closed on a plain directory.
- Page names starting with
apiormcpas the first segment are not reachable through the UI (those prefixes are reserved for the token-protected interfaces).
See CONTRIBUTING.md. All GitHub text (PRs, issues, comments, commits, branch names, code comments) is in English.
MIT © 2026 the stichpunkt authors

