Channel

Version identity

Artifacts

edge (rolling)

None; the commit is the identity

Docker image :edge rebuilt on every merge to main; .mcpb bundle as the mcpb-bundle-edge workflow artifact; Claude Code plugin .zip as the plugin-zip-edge artifact; rolling unstable docs version. It leaves no git tag, GitHub release, or PyPI entry behind.

Pre-release

vX.Y.Z-rc.N, computed and reviewed in its release pull request

PyPI (as the pre-release X.Y.ZrcN); GitHub release with wheels, sdist, .deb/.rpm packages, .mcpb bundle, plugin .zip, and SBOM attached; Docker image under its immutable vX.Y.Z-rc.N tag plus the ordering-aware rolling rc tag. Skips the plugin marketplace, the MCP registry, and the docs deploy.

Stable

vX.Y.Z

Everything: PyPI, Docker (version tag plus ordering-aware latest / vX / vX.Y), .deb/.rpm, GitHub release assets (wheels, sdist, .mcpb bundle, plugin .zip, SBOM), plugin marketplace and MCP registry entries (when the release is the newest stable), versioned docs with an ordering-aware latest alias.

Variable

Default

Description

MARKDOWN_VAULT_MCP_KV_STORE_URL

file:///data/state

Persistent-state backend URL shared by every pvl-core subsystem that needs state. memory:// is in-process and lost on restart; file:///path persists on one server; redis://, dynamodb:// and mongodb:// each need their matching extra. When unset, defaults to file:///data/state (the volume family Docker images mount), or to memory:// (with a warning) on a host where that directory is not usable.

FASTMCP_LOG_LEVEL

INFO

Log level for FastMCP internals and app loggers (DEBUG / INFO / WARNING / ERROR / CRITICAL). The -v CLI flag overrides to DEBUG.

FASTMCP_ENABLE_RICH_LOGGING

true

Set false for plain or structured JSON log output.

Secret

Used by

How to generate

RELEASE_TOKEN

release-prepare.yml, release.yml, copier-update.yml, renovate.yml, bootstrap.yml

Fine-grained PAT at https://github.com/settings/personal-access-tokens/new with contents: write, pull_requests: write, and administration: write (bootstrap applies the repository rulesets + auto-merge). Must belong to a repository admin: the shipped rulesets grant bypass to the admin role, and the release tag + GitHub release that knope creates after a release pull request merges rely on it (pull requests the token opens also need it so their CI runs). Scoped to this repo.

CODECOV_TOKEN

ci.yml

https://codecov.io: sign in with GitHub and add the repo. The upload token is on its settings page.

CLAUDE_CODE_OAUTH_TOKEN

claude.yml

Optional. Run claude setup-token locally and configure this only for @claude or opted-in automatic review.

Variable

Default

Required

Description

OLLAMA_HOST

http://localhost:11434

No

Ollama server URL for the ollama embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the Ollama ecosystem convention.

OPENAI_API_KEY

(none)

No

OpenAI API key for the openai embedding provider, and the fallback key for the summarize tool when MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY is unset. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OpenAI ecosystem convention.

VOYAGE_API_KEY

(none)

No

Voyage AI API key for the voyage embedding provider. Bare (not MARKDOWN_VAULT_MCP_-prefixed), matching the OPENAI_API_KEY / OLLAMA_HOST convention. Setting it never auto-selects the provider; choose it explicitly with MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER=voyage.

OPENAI_BASE_URL

(none)

No

Bare fallback for MARKDOWN_VAULT_MCP_OPENAI_BASE_URL (embeddings). For the summarize tool it only routes traffic when an API key already enables the feature; it never enables summarize by itself.

OPENAI_EMBEDDING_MODEL

(none)

No

Bare fallback for MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL.

MARKDOWN_VAULT_MCP_BUILD_TIMEOUT_S

60

No

Maximum seconds an index-backed tool or resource waits for the FTS index to become queryable during a cold-start background build before raising IndexUnavailableError(reason="timeout"). Increase for large vaults.

MARKDOWN_VAULT_MCP_DRAIN_TIMEOUT_S

60

No

Maximum seconds an index-querying read tool waits for the IndexWriter to drain when called with wait_for_pending_writes=true. On timeout the tool answers from the current index and reports index_stale=true in the response _meta.

MARKDOWN_VAULT_MCP_SOURCE_DIR

/data/vault

No

Path to the markdown vault directory. Required; the server refuses to start without it. Symbolic links inside the vault are followed on Python 3.13+.

MARKDOWN_VAULT_MCP_READ_ONLY

false

No

Set to true to hide the write tools (write, edit, append, delete, rename, move_folder, fetch, git_sync, the okf_* tools, create_upload_link) and serve a search-only vault. git_sync also needs managed git mode; create_upload_link needs an HTTP transport.

MARKDOWN_VAULT_MCP_WRITE_PROTECT_EXISTING

false

No

Set to true to refuse a write that would overwrite an existing file when no if_match etag is supplied. Deliberate replacement (read first, pass if_match) still works, and edit / append / delete / rename are unaffected.

MARKDOWN_VAULT_MCP_DISABLE_APPS_UI

false

No

Hide the MCP Apps UI tools (browse_vault, show_context) from the tool listing for clients that do not render MCP Apps panels.

MARKDOWN_VAULT_MCP_INDEX_PATH

(none)

No

Path to the SQLite FTS5 index file; unset keeps the index in memory. Set it for persistence across restarts.

MARKDOWN_VAULT_MCP_STATE_PATH

(none)

No

Path to the change-tracking state file. Defaults to {SOURCE_DIR}/.markdown_vault_mcp/state.json.

MARKDOWN_VAULT_MCP_EMBEDDINGS_PATH

(none)

No

Path to the numpy embeddings file; required to enable semantic search.

MARKDOWN_VAULT_MCP_INDEXED_FIELDS

(none)

No

Comma-separated frontmatter fields promoted to the tag index for structured filtering. Changing it cold-rebuilds the index once on next startup; SEARCHABLE_FIELDS inherits this value when unset.

MARKDOWN_VAULT_MCP_REQUIRED_FIELDS

(none)

No

Comma-separated frontmatter fields required on every document; documents missing any are excluded from the index.

MARKDOWN_VAULT_MCP_EXCLUDE

(none)

No

Comma-separated glob patterns excluded from scanning (.obsidian/,.trash/).

MARKDOWN_VAULT_MCP_TITLE_FIELD

title

No

Frontmatter field used as the document title (falls back to title, the first H1, then the filename). Changing it cold-rebuilds the index once on next startup.

MARKDOWN_VAULT_MCP_SEARCHABLE_FIELDS

(none)

No

Comma-separated frontmatter fields whose text values become keyword-searchable and enrich first-chunk embeddings. Inherits INDEXED_FIELDS when unset; the sentinel none means filterable but not searchable. Changing it cold-rebuilds the index and re-embeds once on next startup.

MARKDOWN_VAULT_MCP_TEMPLATES_FOLDER

_templates

No

Relative folder where note templates live (used by the create_from_template prompt).

MARKDOWN_VAULT_MCP_PROMPTS_FOLDER

(none)

No

Directory of .md prompt files that extend or override built-in prompts; a relative path is resolved against SOURCE_DIR.

MARKDOWN_VAULT_MCP_CONVENTIONS_FILE

_conventions.md

No

Filename of the per-folder conventions files surfaced to clients at write time (bare .md filename without glob characters). Set to none to disable folder conventions.

MARKDOWN_VAULT_MCP_OKF_MODE

auto

No

OKF (Open Knowledge Format) read semantics. With auto (the default), read annotations switch on when the vault declares an OKF version in its root index.md. Use off to disable OKF semantics entirely, or on to force them for an undeclared vault. Annotations are read-only; write behavior is never affected.

MARKDOWN_VAULT_MCP_OKF_WRITE

false

No

OKF (Open Knowledge Format) enforced write layer. When true on an OKF-active vault, the server stamps generated provenance on each write and clears any verified attestation when a note's content changes. It also keeps each written folder's log.md and index.md current, and exposes the okf_verify tool. Requires OKF_MODE to be auto or on (a true value with OKF_MODE=off is a config error). Off by default.

MARKDOWN_VAULT_MCP_OKF_VERIFY

elicit

No

How the okf_verify tool attributes a human review. This applies only when OKF_WRITE is on, which gates the tool. With elicit (the default), okf_verify asks the human to confirm the review through an MCP elicitation and records the attestation only on an affirmative reply. It fails closed when the client cannot elicit or the human declines, so a model that holds the human's token cannot self-attest. Use trust-auth to attribute to the authenticated caller with no confirmation (safe only when the sole caller is a human-driven UI), or off to hide the tool so attestation happens through external tooling. A non-default value with OKF_WRITE off is a config error.

MARKDOWN_VAULT_MCP_ATTACHMENT_EXTENSIONS

(none)

No

Comma-separated allowed attachment extensions without the dot (such as pdf,png,jpg); use * to allow every non-markdown file. Unset selects the built-in allowlist.

MARKDOWN_VAULT_MCP_MAX_ATTACHMENT_SIZE_MB

1.0

No

Maximum attachment size in MB returned by read / accepted by write; 0 disables the limit.

MARKDOWN_VAULT_MCP_MAX_NOTE_READ_BYTES

262144

No

Maximum bytes returned by a full-document read of a note; use read(path, section=…) for partial reads. 0 disables the limit.

MARKDOWN_VAULT_MCP_DEFAULT_SEARCH_MODE

auto

No

Mode used when a search call omits 'mode': auto, keyword, semantic, or hybrid. The default 'auto' picks hybrid when embeddings are configured and keyword when they are not. Pin 'keyword' to keep unqualified searches off the embedding provider (each hybrid or semantic search embeds the query, which costs an API call on a metered provider). A configured semantic/hybrid default also degrades to keyword without embeddings, so no setting can make a vault unsearchable; an explicit mode= argument is never downgraded.

MARKDOWN_VAULT_MCP_CHUNKS_PER_FILE

2

No

Maximum chunks returned per document in search results.

MARKDOWN_VAULT_MCP_SNIPPET_WORDS

200

No

Width of the snippet window (words) in search results; 0 returns full chunk content.

MARKDOWN_VAULT_MCP_LENGTH_DOWNWEIGHT_ALPHA

0.25

No

Down-weights longer chunks in ranking: score / (1 + alpha * log(chunk_count)).

MARKDOWN_VAULT_MCP_MAX_CHUNK_WORDS

400

No

Word cap per chunk; the adaptive chunker splits at deeper heading levels, then paragraph/word boundaries, to respect it. Match it to the embedding model's context. A reindex applies a new value.

MARKDOWN_VAULT_MCP_MAX_CHUNK_CHARS

(none)

No

Character cap enforced alongside MAX_CHUNK_WORDS to bound token-dense chunks. Unset derives min(1500, model context * 2.8). Set a positive value for an exact cap, or -1 to scale with the model's full context (can exhaust memory on long-context models). A reindex applies a new value.

MARKDOWN_VAULT_MCP_CHUNK_OVERLAP_WORDS

40

No

Words of overlap between adjacent budget-split fragments of the same heading section (0 disables). A reindex applies a new value.

MARKDOWN_VAULT_MCP_FOLDER_WEIGHTS

(none)

No

Folder-prefix score multipliers (prefix:weight pairs, comma-separated, weights > 0) applied to all search modes; the deepest matching prefix wins (sessions:0.5 demotes sessions/**).

MARKDOWN_VAULT_MCP_FTS_WEIGHTS

(none)

No

Per-column BM25 weights (column:weight pairs, comma-separated, weights >= 0) for keyword ranking. Columns: path, title, folder, heading, content, summary.

MARKDOWN_VAULT_MCP_EMBEDDING_PROVIDER

(none)

No

Embedding provider: openai, voyage, ollama, or fastembed. Unset auto-detects from the environment (never voyage). Any OpenAI-compatible endpoint works with openai plus OPENAI_BASE_URL; see the embeddings guide.

MARKDOWN_VAULT_MCP_OLLAMA_MODEL

nomic-embed-text

No

Ollama embedding model name.

MARKDOWN_VAULT_MCP_OLLAMA_CPU_ONLY

false

No

Force Ollama to embed on CPU only.

MARKDOWN_VAULT_MCP_VOYAGE_MODEL

voyage-4

No

Voyage AI embedding model name.

MARKDOWN_VAULT_MCP_OPENAI_BASE_URL

https://api.openai.com/v1

No

OpenAI-compatible API base URL for embeddings; the bare OPENAI_BASE_URL is honoured as a fallback.

MARKDOWN_VAULT_MCP_OPENAI_EMBEDDING_MODEL

text-embedding-3-small

No

OpenAI-compatible embedding model name; the bare OPENAI_EMBEDDING_MODEL is honoured as a fallback.

MARKDOWN_VAULT_MCP_FASTEMBED_MODEL

BAAI/bge-small-en-v1.5

No

FastEmbed model name.

MARKDOWN_VAULT_MCP_FASTEMBED_CACHE_DIR

(none)

No

FastEmbed model cache directory (in Docker, stored under /data/state/fastembed).

MARKDOWN_VAULT_MCP_EMBED_CONTEXT

false

No

Enrich embedding input with the note title, chunk heading, and (first chunk) searchable-field values. Flipping it re-embeds the whole vault once on next startup.

MARKDOWN_VAULT_MCP_EMBED_TIMEOUT_S

30.0

No

Per-request wall-clock budget in seconds for a single embedding HTTP call (OpenAI/Ollama). The local FastEmbed backend runs in-process with no network call and ignores this. CPU-only or large-model workloads may need 60-120 s; raise this if batches time out.

MARKDOWN_VAULT_MCP_EMBEDDING_BATCH_SIZE

4

No

Number of chunks sent per embedding request. Smaller batches shorten each request (useful under a tight timeout on slow models) at the cost of more round-trips.

MARKDOWN_VAULT_MCP_GIT_TOKEN

(none)

No

Token/password for HTTPS git auth; remotes must be HTTPS when set.

MARKDOWN_VAULT_MCP_GIT_REPO_URL

(none)

No

HTTPS remote URL for managed git mode: the server clones into an empty SOURCE_DIR on startup (or validates an existing origin) and enables the pull loop, auto-commit, and deferred push.

MARKDOWN_VAULT_MCP_GIT_USERNAME

x-access-token

No

Username for HTTPS git auth prompts (x-access-token for GitHub, oauth2 for GitLab, the account name for Bitbucket).

MARKDOWN_VAULT_MCP_GIT_PULL_INTERVAL_S

600

No

Seconds between git fetch + fast-forward update attempts; 0 disables periodic pull.

MARKDOWN_VAULT_MCP_GIT_PUSH_DELAY_S

30.0

No

Seconds of write-idle time before pushing; 0 pushes only on shutdown.

MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME

markdown-vault-mcp

No

Git committer name for auto-commits; set this in Docker where git config user.name is empty.

MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL

noreply@markdown-vault-mcp

No

Git committer email for auto-commits.

MARKDOWN_VAULT_MCP_GIT_COMMIT_NAME_CLAIM

(none)

No

OIDC claim key used as the commit author name (such as name); overrides GIT_COMMIT_NAME per request when an OIDC token is present. The claim is resolved when the tool call arrives and carried to the background commit, so it applies on every write.

MARKDOWN_VAULT_MCP_GIT_COMMIT_EMAIL_CLAIM

(none)

No

OIDC claim key used as the commit author email (such as email); overrides GIT_COMMIT_EMAIL per request when an OIDC token is present. Resolved and carried the same way as the name claim.

MARKDOWN_VAULT_MCP_GIT_LFS

true

No

Run git lfs pull on startup to fetch LFS-tracked attachments; set to false for repos without LFS.

MARKDOWN_VAULT_MCP_FILE_WATCHER

true

No

Watch the vault for external filesystem changes; auto-disabled when git pull or the webhook is active. Requires the file-watcher extra.

MARKDOWN_VAULT_MCP_FILE_WATCHER_DEBOUNCE_S

2.0

No

Seconds of quiet after the last filesystem event before reindexing.

MARKDOWN_VAULT_MCP_FILE_WATCHER_ROOT_FLOOR

true

No

Keep the non-recursive watch on the vault root; set false to register zero source-dir-rooted FSEvents streams (avoids repeated macOS access prompts on a home-rooted vault) at the cost of root-level files relying on scans.

MARKDOWN_VAULT_MCP_GITHUB_WEBHOOK_SECRET

(none)

No

Shared secret for the GitHub push-event webhook; when set, mounts POST /github-webhook on HTTP/SSE transports to trigger an immediate pull + reindex on push events.

MARKDOWN_VAULT_MCP_SUMMARIZE_PROVIDER

(none)

No

Summarization backend (only openai is recognised). Unset auto-detects: the backend activates when credentials or an explicit endpoint are present.

MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_API_KEY

(none)

No

API key for the OpenAI-compatible summarize endpoint; the bare OPENAI_API_KEY is honoured as a fallback. Unset works for keyless local endpoints (Ollama).

MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_BASE_URL

(none)

No

OpenAI-compatible endpoint base URL for the summarize tool; setting it enables the tool even without an API key. The bare OPENAI_BASE_URL routes traffic only when a key already enables the feature.

MARKDOWN_VAULT_MCP_SUMMARIZE_OPENAI_MODEL

gpt-5-mini

No

Chat model id used for summaries.

MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_TOKENS

8192

No

Upper bound on generated tokens per summarize call; on reasoning models this budget also covers internal reasoning tokens.

MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_NOTES

50

No

Cap on the number of notes summarised in one call (subtree expansion truncates to this many).

MARKDOWN_VAULT_MCP_SUMMARIZE_MAX_INPUT_CHARS

200000

No

Aggregate cap on note characters sent to the model in one call; excess is truncated with a flag on the result.

MARKDOWN_VAULT_MCP_SUMMARIZE_TIMEOUT

120.0

No

Per-request wall-clock budget in seconds for a single summarize backend call; keep it below the MCP client's request timeout so the server-side error wins the race.

MARKDOWN_VAULT_MCP_TRANSFER_TTL_DEFAULT_S

3600.0

No

Link lifetime in seconds when the caller requests no explicit TTL.

MARKDOWN_VAULT_MCP_TRANSFER_TTL_MAX_S

86400.0

No

Ceiling in seconds a caller-requested link TTL is clamped to.

MARKDOWN_VAULT_MCP_TRANSFER_GRACE_TTL_S

60.0

No

Post-success grace window in seconds: a served token's TTL shrinks to this so a stalled transfer can retry within it.

MARKDOWN_VAULT_MCP_TRANSFER_LEASE_S

60.0

No

Crashed-handler reclaim window in seconds for an in-flight reservation.

MARKDOWN_VAULT_MCP_TRANSFER_MAX_UPLOAD_BYTES

104857600

No

Maximum size in bytes of a single upload.

MARKDOWN_VAULT_MCP_JOBS_SOFT_DEADLINE_S

25.0

No

Seconds a long-running tool call may run in the foreground before it is promoted to a background job and a job handle is returned instead.

MARKDOWN_VAULT_MCP_JOBS_RESULT_TTL_S

3600.0

No

Seconds a background-job record (working or finished) is retained for polling before it expires from the store.

MARKDOWN_VAULT_MCP_JOBS_MAX_PER_SUBJECT

256

No

Maximum live background jobs per calling subject; further promotions are rejected until older records expire.