{
  "topic": "deploy-policy",
  "rules": [
    {
      "id": "rules-001",
      "text": "run full CI green before any production deploy.",
      "source": "markdown://deploy-policy.md#rules",
      "severity": "must"
    }
  ],
  "reasoning": [
    {
      "text": "The team adopted these rules after a 2025 incident.",
      "source": "markdown://deploy-policy.md#background"
    }
  ],
  "skills": [],
  "commands": [],
  "fetched_at": "2026-06-11T14:32:00+00:00",
  "cache_hit": false
}

source is a URI scheme — markdown://, github://, confluence://, notion://, jira://, linear://, slack://, harness://. The agent (or you) can trace any rule back to the file, page, or message it came from. cache_hit tells the agent whether to trust the freshness implied by the topic's TTL.

$ uvx keystone-mcp

$ pip install keystone-mcp
$ pip install "keystone-mcp[tokens]"   # + tiktoken-backed budget tokenizer

$ pipx install keystone-mcp

$ git clone https://github.com/tacoda/keystone-mcp.git
$ cd keystone-mcp
$ uv sync
$ uv run keystone-mcp

Add to .mcp.json:

{
  "mcpServers": {
    "keystone": {
      "command": "uvx",
      "args": ["keystone-mcp"],
      "env": {
        "KEYSTONE_CONFIG": "/path/to/your/project/.keystone/context.yaml"
      }
    }
  }
}

KEYSTONE_CONFIG defaults to .keystone/context.yaml relative to the working directory. The .keystone/ directory is team-shared and version-controlled — never put secrets there; reference env vars with the env: prefix instead.

1. Create .keystone/context.yaml

   sources:
     docs:
       type: markdown
       root: .keystone/context/
   
   topics:
     deploy-policy:
       description: |
         Rules and context for production deploys.
       sources:
         - source: docs
           query: { file: deploy-policy.md }
           classify:
             rules: { heading: "Rules", severity: must }
             reasoning: { heading: "Background" }
       cache: 15m

2. Create .keystone/context/deploy-policy.md

   # Deploy Policy
   
   ## Rules
   
   - MUST run full CI green before any production deploy.
   - SHOULD prefer Tuesday/Wednesday morning deploys.
   
   ## Background
   
   The team adopted these rules after a 2025 incident.

3. Start the server. The agent sees the topic.

   keystone_list_topics now returns deploy-policy. The agent reads keystone://context/deploy-policy and gets the envelope — one must rule, one should rule, one reasoning bullet, all cited back to the markdown file.

The repo's own .keystone/context.yaml is a working example with topics for deploys, ownership, coding standards, and a release playbook — plus commented-out examples of every external adapter.

Scaffold tools refuse to write files whose names look like secrets (secret, token, credential, password, api_key, private, envfile, …). The harness root is fixed at .keystone/harness/ — not configurable.

topics:
  repo-policy:
    description: Combined ownership and branch-protection rules.
    sources:
      - source: docs
        query: { file: owners.md }
        classify:
          rules: { heading: "Required reviewers" }
      - source: gh
        query: { type: codeowners }
      - source: gh
        query: { type: branch_protection, branch: main }
    cache: 5m

topics:
  rollback:
    description: Rollback procedure.
    source: docs
    query: { file: rollback.md }
    classify:
      rules: { heading: "Rules" }

classify:
  rules:
    heading: "Rules"             # single or list: ["Rules", "Must"]
    severity: must               # default when bullets lack MUST/SHOULD/MAY
  reasoning:
    heading: "Background"
    # or
    all: true                    # everything not matched by another kind
  skills:
    heading: "Procedures"       # each H3 → one skill (name + body)
  commands:
    heading: "Commands"         # each H3 → one command (first code block = invocation)

sources:
  gh:
    type: github
    repo: acme/widgets
    auth: env:GITHUB_TOKEN

cache:
  backend: sqlite
  path: .keystone/cache.db

Default backend is in-memory (lost on restart). The sqlite backend persists envelopes across server restarts and survives uvx re-invocations. Per-topic TTLs use 5s / 10m / 2h / 1d syntax.

Huckleberry is run by Ian Johnson, the author of keystone-mcp. Engagements are scoped per-team and per-codebase; expect a deliberate, small-batch approach.