Get started

One config file.One command to stay current.

Published on PyPI. Python 3.11+. MIT licensed. No index server, no embedding model, no tuning pass — and nothing leaves the machine.

Install

Four commands to a governed estate.

uv tool install shelfmark

pipx install shelfmark

01
shelfmark init
Write a starter config.toml — and when the default root misses, init sweeps for the folders that do hold documents. One keypress fixes the config.
02
shelfmark refresh
Build + rights + prune + assertions, incrementally — a couple of seconds over a ~30k-file tree.
03
claude mcp add shelfmark -s user -- shelfmark-mcp
Connect it. Any client that speaks local MCP can point at the shelfmark-mcp command.
04
shelfmark review --apply
Optional, worth five minutes: a few questions about your own folders, and rights stop being UNKNOWN.

Wire it in

One command with Claude Code — claude mcp add shelfmark -s user -- shelfmark-mcp — or add shelfmark-mcp to any client that speaks the protocol.

// claude_desktop_config.json

{
  "mcpServers": {
    "shelfmark": {
      "command": "shelfmark-mcp"
    }
  }
}

The surface

No chunk sizes, no embedding model to pick, no query language to learn. The sophistication lives in the engine; the surface stays small.

corpus_stats()

The census: counts, sizes, roots — and it volunteers its own freshness.

browse_folder()

Answers “what do I have here” without handing back a query builder.

search_docs()

Full-text search over the catalogue, built to survive hyphenated identifiers.

search_emails()

The same governed discovery over ingested mail archives.

get_file()

One document’s record, fetched when the agent decides it is worth opening.