Holster MCP

Holster MCP

Holster MCP exposes local Holster Doctor checks to MCP-compatible agents. The server is local-first: free tools shell out to the bundled holster-doctor binary and never send repository contents to a network service.

Install

From PyPI:

pip install holster-mcp

Development install:

cd /path/to/holster/mcppython3.11 -m pip install -e '.[dev]'

Runtime command:

holster-mcp

MCP client config:

{  "mcpServers": {    "holster": {      "command": "uvx",      "args": ["holster-mcp"]    }  }}

See the main Holster README for vault and holster-cli release binary installation.

License: MIT for the MCP package.

Binary Resolution

The server locates holster-doctor in this order:

1. HOLSTER_DOCTOR_BIN
2. Packaged wheel binary at holster_mcp/bin/holster-doctor
3. holster-doctor on PATH
4. Repo-local target/release/holster-doctor
5. Repo-local target/debug/holster-doctor

Free Tools

holster.scan_repo

Input:

{"path": "/absolute/repo/path", "depth": 3}

Output:

{  "ok": true,  "scanned_files": 15,  "findings": [    {      "file": "src/main.py",      "line": 12,      "secret_kind": "openai_api_key",      "severity": "error",      "suggestion": "Rotate this key and move it into a local vault."    }  ]}

holster.check_gitignore

Input:

{"path": "/absolute/repo/path"}

Output:

{  "ok": true,  "missing_patterns": [".env.local"],  "existing_safe": [".env"],  "existing_unsafe": [],  "suggested_append": ".env.local\n*.pem"}

holster.rotation_playbook

Input:

{"provider": "github"}

Output:

{  "ok": true,  "provider": "github",  "steps": ["Create a replacement token...", "Update local consumers...", "Revoke the old token..."],  "estimated_minutes": 15,  "warnings": ["Do not revoke the old credential until the replacement has been verified."]}

Platform Wheels

Day 1 wheels are built for:

• macOS ARM (aarch64-apple-darwin)
• Linux x86_64 (x86_64-unknown-linux-gnu)

The wheels bundle the platform's holster-doctor binary and are intentionally not universal.

Paid Tools

Paid tools are local-only wrappers around holster-cli and are gated by a Holster license.

License Configuration

License lookup order:

1. license_key argument passed to a paid MCP tool
2. HOLSTER_LICENSE_KEY
3. ~/.holster/config.toml

Supported config.toml shapes:

license_key = "holster_live_ABCDEFGHIJKLMNOPQRSTUVWX"vault_path = "/absolute/path/to/holster-vault.db"

or:

[license]key = "holster_live_ABCDEFGHIJKLMNOPQRSTUVWX"
[vault]path = "/absolute/path/to/holster-vault.db"

License cache:

~/.holster/licenses.db

If no license is configured, the first paid-tool call creates a local 7-day trial key with prefix holster_trial_.

Vault Configuration

Vault path lookup order:

1. explicit tool argument where supported
2. HOLSTER_VAULT_PATH
3. ~/.holster/config.toml

holster.vault_add

Input:

{  "provider": "github",  "account": "nauta-ai",  "secret": "user-pasted-secret",  "label": "primary"}

Output:

{"ok": true, "vault_entry_id": "123e4567-e89b-12d3-a456-426614174000", "error": null}

The secret value is never placed in CLI argv, logs, or structured error output.

holster.vault_rotate

Day 2 supports github and stripe.

Without new_secret, the tool returns the provider playbook and waits for the human to rotate/paste the replacement:

{  "provider": "github",  "account": "nauta-ai",  "vault_entry_id": "old-id"}

With new_secret, the replacement is added to the local vault and the old entry is marked superseded when the installed CLI supports that command.

holster.audit_log

Input:

{"provider": "github", "account": "nauta-ai", "since_days": 30}

Output:

{"ok": true, "events": [{"ts": "...", "action": "add", "provider": "github", "account": "nauta-ai", "ok": true}]}

License Architecture

flowchart TD  A["Paid MCP tool call"] --> B["Resolve license key from arg/env/config"]  B --> C{"Key present?"}  C -- "No" --> D["Create local 7-day trial in ~/.holster/licenses.db"]  C -- "Yes" --> E["Read ~/.holster/licenses.db"]  D --> F{"Trial valid?"}  E --> G{"Cached license valid?"}  G -- "Valid" --> H["Dispatch paid tool"]  G -- "Expired but within 7-day grace" --> I["Dispatch with license_warning"]  G -- "Missing/stale live key" --> J["Stripe refresh: Customer.retrieve + Subscription.list"]  J -- "Active" --> K["Update cache valid_until + last_checked"]  J -- "Inactive/error/no API key" --> L["Return license_required_or_expired"]  F -- "Valid" --> H  F -- "Expired" --> L  K --> H  I --> H  H --> M["Local holster-cli subprocess"]

The background poller refreshes cached live licenses every 10 minutes after a paid tool validates. There is no webhook receiver in Day 2 and no telemetry in V1.