Skip to content

About

A fast, minimal, self-hosted markdown wiki. Plain .md files are the database; agents write via MCP, you read.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

stichpunkt

Notes that stay in order.

A fast, minimal, self-hosted markdown wiki. Plain .md files are the database — agents write through MCP, you read.

CI License: MIT Node.js ≥ 22 SvelteKit TypeScript MCP Docker PWA

Quickstart · Features · Configuration · API & MCP · Architecture · Development


Table of contents

What is stichpunkt?

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.

Demo

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/knowledge folder), bundled into the image as a fallback when SPACE_DIR is 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.

Features

Reading experience

  • Folders are namespaces (Server/SilverBullet.md → page Server/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 the Features/ demo pages.
  • Full-text search ranked by BM25 over sections and fields, with German stemming, compound splitting (Arzttermin → Arzt + Termin), quoted phrases, #tag / in:folder filters, 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 in CONFIG.md with tag.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 sends X-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 ```pages block with a small YAML body lists pages from the index: filters tag, folder, links-to; sort by title, modified, date or any frontmatter key; show as list, table or count; limit defaults to 50 (max 200).
  • Strictly validated (js-yaml CORE + zod) — no expressions, no regex, nothing executed. The same engine backs the ${...} expressions, the query_pages MCP tool and POST /api/v1/query.

Collections (SQLite databases)

  • Typed tables in SQLite at /var/lib/stichpunkt/collections.sqlite (COLLECTIONS_DB overrides; 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_at gives optimistic concurrency; every row change is recorded with an actor.
  • REST API under /api/v1/databases and 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/preview reports the Markdown tables of a page before any migration, export?format=csv|json returns a portable snapshot of one collection. See docs/collections.md.
  • GET /api/v1/export and npm run export write 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 no eval, 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 are Maps, 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 leaving SPACE_DIR are rejected.

Screenshots

stichpunkt on desktop: folder tree, article, outline, backlinks and properties

stichpunkt on mobile: bottom navigation bar

Screenshots show the bundled examples/knowledge/ space (dark theme). See Development to run it yourself.

Quickstart

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

The 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.js

Usage

Read — 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
```

Configuration

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 for MDWIKI_API_TOKEN, the X-Mdwiki-Zone proxy header and the npm package name, which keep the old id as an internal contract.

Reverse-proxy 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.

API & MCP

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.

Page operations

  • 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, |alias and ![[…]] survive, and nothing inside fenced or inline code is touched. An existing destination is a 409 target_exists; dry_run returns the plan without writing.
  • write_pages writes several pages atomically: sorted locks, all base_hash values checked before the first write ("" = must not exist), one index rebuild. One stale hash returns 409 with every conflict in conflicts and changes nothing; an unexpected disk error rolls already written files back. Duplicate paths in one batch are a 400.
  • check_manifest validates the manifest against the schema and the space (unknown keys/enums, allowed_tags without tag.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 (#Heading that does not exist). path limits the audit to one page or folder; include_hidden also checks pages that are hidden from navigation (the repository's hidden prefix, Library/ by default).

Layers

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.

Agent manifest

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 summary plus a pointer to get_manifest as instructions; get_manifest (and GET /api/v1/manifest) returns rules, prose and the content hash.
  • Writing. There is no special write tool: use write_page("MANIFEST", …, base_hash). An invalid manifest (YAML error, missing manifest/summary, unknown key, summary too long) is rejected with 400 manifest_invalid plus 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_manifest returns manifest_invalid).
  • Checking. Page writes never fail because of the manifest; they return warnings for the resulting page: missing_frontmatter, forbidden_prefix, unknown_folder (only when folders is set; root pages are skipped), possible_secret (private-key headers, GitHub tokens, sk- keys, AWS access keys, Slack tokens, long Bearer tokens), with the links check dead_link for every wikilink whose target does not exist, with frontmatter tag_not_allowed for tags outside pages.allowed_tags, with owner owner_mismatch when the acting agent (agent argument or X-Agent header) differs from the folder owner, and with stand_age stand_missing / stand_unparseable / stand_stale for the configured stand date. Full schema: docs/manifest.md. A possible_secret warning names only the rule and the line, never the value. validate_page / POST /api/v1/validate return the same warnings without writing.

Operations

Health check

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 }
  }
}
  • database runs PRAGMA integrity_check on a read-only connection and reports PRAGMA user_version.
  • write takes the write lock with BEGIN IMMEDIATE and rolls it back: it proves the write path without inserting a row or a revision.
  • deployed reports the commit in deployed.sha; before the first deploy the file is missing and still ok.
  • backup fails when the last backup ok entry is older than 36 hours.

Export

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.

Deploy gate

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

  1. Generate a new token: openssl rand -base64 32; store it in your password manager.
  2. Put it into .env as MDWIKI_API_TOKEN.
  3. docker compose up -d stichpunkt (recreates the container; the web UI is unaffected).
  4. 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.

Architecture

 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, pages query engine, auth, path safety, MCP); diagram handling is behind one registry in src/lib/diagrams.ts.
  • Single container.

Development

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 server

Try every feature against the example space:

SPACE_DIR=examples/knowledge node build/index.js

Test 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 api or mcp as the first segment are not reachable through the UI (those prefixes are reserved for the token-protected interfaces).

Contributing

See CONTRIBUTING.md. All GitHub text (PRs, issues, comments, commits, branch names, code comments) is in English.

License

MIT © 2026 the stichpunkt authors

About

A fast, minimal, self-hosted markdown wiki. Plain .md files are the database; agents write via MCP, you read.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages