meerkat — CLI & integrations

The CLI#

Every subcommand works under both meerkat and mk. Page IDs are slash-paths from the wiki root without the .md extension (e.g. concepts/Rate-Limiting), optionally prefixed with <collection>: when several collections are mounted.

Global flags#

These apply to every subcommand and select which knowledge base is served. They are resolved once, before the subcommand runs.

Search flags#

mk search "exact phrase"     # phrase match
mk search +cache -queue      # must / must-not
mk search title:eviction     # field-targeted

List filters#

Filters compose with AND, and are applied to frontmatter after loading — they are not query terms.

OpenCode (MCP over stdio)#

Register meerkat as a local MCP server and your agent gains mk_search, mk_show, mk_list, mk_list_collections, and mk_report_outcome on every prompt — plus mk_save_memory when a collection has a memory: block.

{
  "mcp": {
    "meerkat": {
      "type": "local",
      "command": ["mk", "mcp", "serve"],
      "enabled": true
    }
  }
}

The read tools are annotated read-only, idempotent, and closed-world, so a harness can call them without a confirmation prompt. The two writers are mk_save_memory, which only appears when a collection opts in, and mk_report_outcome, which records how a retrieval ended to the traversal log and intake drafts — and only where those stores are configured.

Hosted MCP (Streamable HTTP + OIDC)#

mk mcp serve-http serves the same MCP tools over Streamable HTTP for the deployment stdio can't model: one meerkat, many people, different people allowed to see different collections. meerkat acts as an OAuth 2.0 protected resource — it validates JWTs from configured OpenID Connect issuers (Entra ID, Google, Okta are configuration, not code) and never issues tokens itself. Authorization is per collection via an auth: block in content-source.yaml (or a standalone policy file via --auth-config).

mk mcp serve-http --port 4005            # binds 127.0.0.1, mounts /mcp
# probes & metrics: /livez /readyz /metrics
# SIGHUP runs every refresh: cycle and rebuilds type: local indexes;
# the auth policy is not reloaded

OpenWebUI (HTTP / OpenAPI)#

Serve the knowledge base over HTTP with a bearer token, then point OpenWebUI at the OpenAPI schema. The default bind is loopback.

export MEERKAT_API_KEY=$(openssl rand -hex 32)
mk http serve --port 4004               # binds 127.0.0.1 by default
curl -sS http://127.0.0.1:4004/healthz

POST /list accepts the same type filter as the CLI, POST /show returns trust_tier and stale alongside the page, and all three POST bodies accept an optional collection field.

Environment variables#