# psamvault-mcp

**v0.5.5** — MCP server for [psamvault](https://pypi.org/project/psamvault/).

Lets AI agents use your stored credentials without ever seeing their plaintext values. Also integrates with [pv-dotenv](https://pypi.org/project/pv-dotenv/) for runtime credential resolution in your `.env` files.

> **Agents installing or repairing this MCP:** read
> [docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md](docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md)
> before debugging. Common failures are PATH shadowing, corrupt pipx installs,
> missing absolute paths in client config, expired vault sessions, and
> mid-session MCP not reloading until restart.

## Features

Tools are grouped into three categories. Always start in **Entry & Orientation**.

### 🛠  Entry & Orientation
*Discover what tools are available and verify the server is running.*

| Tool | What it does |
|------|-------------|
| **`search_vault_tools`** | Discovery tool — call this first to find the right tool for your task |
| **`get_version`** | Get the installed server version |

### 🔐  Site Authentication
*End-to-end: discover, check, and log into websites.*

| Tool | What it does |
|------|-------------|
| **`list_vault_sites`** | List all stored credential sites (names and username hints only) |
| **`check_credential_exists`** | Check if a credential exists for a site |
| **`get_username_for_site`** | Get stored username (never the password) |
| **`browser_login`** | Opens Chromium, navigates to any site, fills credentials directly in the browser — agent never sees them |

### 🔑  API Key Operations
*All tools that deal with API keys — discover, use, inject, and protect.*

| Tool | What it does |
|------|-------------|
| **`list_api_keys`** | Lists all stored API key names with service hints and project grouping — never returns key values |
| **`use_credential`** | Authenticated HTTP to that entry's own site or the API key's service. Any other host is refused. The response is returned with the secret scrubbed out |
| **`run_with_credential`** | A CLI that reads a token from the environment or stdin. URLs in the command are host-checked. Output is scrubbed of the secret and its common encodings |
| **`scan_and_protect`** | Scans a project directory for `.env` files, encrypts secrets into psamvault, replaces plaintext with `psamvault:KEY` placeholders |
| **`export_key_to_mcp_config`** | Exports a vault API key directly into a client MCP config file (Hermes — the only host whose config shape is verified) — auto-verifies HTTP keys before writing |
| **`export_key_to_env_file`** | Exports a vault API key into an agent's `.env` as an environment variable (default `HERMES_HOME/.env`) — updates in place, backs up, auto-verifies |
| **`verify_api_key`** | Verifies a stored API key is valid against its provider's API — returns status, provider, and verification result |

> **New in v0.4.6:** `export_key_to_mcp_config`, `verify_api_key`, and the auto-verifying export gate (verified-before-write for HTTP keys).

> **Breaking in v0.5.0:** `capture_stripe_credentials` was REMOVED (the Stripe Projects
> capture flow is gone). Use `scan_and_protect` for project `.env` secrets.
>
> **New in v0.5.0:** `export_key_to_env_file` — put a vault key into an agent `.env` as an environment
> variable (default `HERMES_HOME/.env`, explicit `env_path` for other hosts), updating in place with a
> timestamped backup.
>
> **New in v0.4.0:** `use_credential`, `run_with_credential`, `scan_and_protect`, `list_api_keys`, single-process browser architecture (no fragile subprocess daemon), auto-restart on crash.

## How it works

### Browser login flow (`browser_login`)

When an AI agent needs to log you into a website, psamvault opens a real
Chromium browser, navigates to the site, and fills in the credentials directly
inside that browser process.

**The agent never sees the credentials.** It only sees whether the login succeeded.

```
Agent: "Log me into kaggle.com"
         ↓
psamvault opens Chromium → navigates to kaggle.com → finds the login page
         ↓
psamvault decrypts credential locally
         ↓
psamvault fills username + password fields directly in the browser
         ↓
If a CAPTCHA appears, psamvault takes a screenshot, pauses automation,
and tells you to solve the CAPTCHA and click Sign in manually
         ↓
Agent receives:
         {
           "success": true,
           "message": "Logged in to github.com successfully.",
           "steps_count": 8,
           "url": "https://github.com/dashboard",
           "captcha_detected": false
         }
         ↓
Browser stays open — you take over from there.
The browser session is saved and reused on subsequent calls to the same site.
```

### API credential flow (`use_credential`)

When an AI agent needs to make an authenticated API call on your behalf:

```
Agent: "Get my top 10 starred repos"
         ↓
use_credential("github.com", target_url="https://api.github.com/users/psam-717/starred")
         ↓
psamvault decrypts the credential locally, sends it only to that site
(or the key's service), and returns the response with the secret scrubbed out
```

A site password goes to the registrable domain of its site name or login URL, and to subdomains of that domain. An API key goes to hosts its service already names (a bundled verify recipe such as `github` → `api.github.com`, or a hostname in the service, the service hint, or the key name), including that registrable domain and its subdomains. Anything else is refused, including a redirect off an allowed host. An API key with no known service host is refused until a human adds the host under `entries["<entry>"].allow_hosts` in `~/.psamvault/policy.json` (mode 0600). There is no MCP parameter that grants a host. `target_url` must be an absolute `http` or `https` URL. Loopback and private addresses stay blocked.

The response scrub (raw value, reversed text, base64, URL-encoding, hex, and the basic-auth blob) is defence in depth. The host check is the boundary.

Supports three injection modes:
- **Bearer token** — `Authorization: Bearer ***`
- **API key header** — `<custom-header>: <key>`
- **Basic auth** — `Authorization: Basic base64(user:pass)`

The `fields` parameter lets you return only the response keys you need, reducing token usage.

### CLI command flow (`run_with_credential`)

When an agent needs to run a CLI tool that requires a credential (upload to PyPI, push to a private git repo, log into Docker, publish an npm package):

```
Agent: "Upload my package to PyPI"
         ↓
run_with_credential("pypi", "twine upload dist/*",
                    inject_as="env", env_var_name="TWINE_PASSWORD")
         ↓
psamvault decrypts the credential locally, spawns the subprocess
with the credential injected as an env var (or piped via stdin)
         ↓
Every http(s) URL in the command is checked the same way as use_credential.
A command with no URL is not host-checked.
Stdout and stderr are scrubbed of the secret, its reversed text, and the
common encodings before being returned. That scrub is defence in depth.
```

Supports two injection modes:
- **`env`** (default) — credential set as an environment variable (e.g. `TWINE_PASSWORD`, `GITHUB_TOKEN`, `NPM_TOKEN`). When `TWINE_PASSWORD` is used, `TWINE_USERNAME=__token__` is set automatically.
- **`stdin`** — credential piped via stdin (e.g. for `docker login`).

Use cases include: `twine upload`, `git push`, `docker login`, `npm publish`, `pip install` (private repos), and any CLI tool that needs an API key or password.

### Protecting your `.env` files (`scan_and_protect`)

```
Agent: "Protect the secrets in my project"
         ↓
scan_and_protect scans the project directory for .env files
         ↓
Detects API keys, passwords, tokens (pattern matching)
         ↓
Encrypts each secret into the psamvault vault
         ↓
Replaces plaintext with "psamvault:KEY_NAME" placeholders
         ↓
Your app resolves them at runtime with pv-dotenv
```

Secrets can be stored under a project namespace by passing `project_name`:
- Keys stored as `project_name/.env/KEY_NAME` for clean per-project organisation
- When omitted, keys are stored as `env/.env/KEY_NAME` (backwards-compatible)
- Use `list_api_keys(project_name="myproject")` to view only that project's keys

After protecting, pair with [pv-dotenv](https://pypi.org/project/pv-dotenv/) — a drop-in replacement for `python-dotenv` that resolves `psamvault:` placeholders at runtime. No code changes needed beyond the import:

```python
# Before:
from dotenv import load_dotenv

# After:
from pv_dotenv import load_dotenv
```

## Prerequisites

- Python ≥ 3.11
- [psamvault](https://pypi.org/project/psamvault/) installed and logged in

```bash
pipx install psamvault
psamvault configure
psamvault login
```

- Playwright Chromium browser (only for `browser_login`)

`pipx` puts `psamvault-mcp` on PATH and does not put `playwright` there. Run the copy
inside the pipx venv, and let pipx say where that venv is (current pipx uses
`~/.local/share/pipx` on Linux, `~/Library/Application Support/pipx` on macOS, and
`%LOCALAPPDATA%\pipx\pipx` on Windows; an older install keeps `~/.local/pipx` or
`%USERPROFILE%\pipx` when that directory is already there):

```bash
VENVS="$(pipx environment --value PIPX_LOCAL_VENVS)"
"$VENVS/psamvault-mcp/bin/python" -m playwright install chromium          # Linux / macOS
```

```powershell
$venvs = (pipx environment --value PIPX_LOCAL_VENVS).Trim()
& "$venvs\psamvault-mcp\Scripts\python.exe" -m playwright install chromium   # Windows
```

## Installation

**Prefer pipx** (isolated venv). Avoid `pip install` into system Python — on
Windows this often leaves a broken shim on PATH that shadows the good install.

```bash
pipx install psamvault-mcp
psamvault-mcp --version   # safe smoke test (prints and exits)
psamvault-mcp --help      # same — usage text, then exit
```

### After install — resolve the real binary

If `where psamvault-mcp` / `which -a psamvault-mcp` shows **more than one**
path, configure your MCP client with the **absolute path** under your user
local bin (pipx), not the system `Python3xx\Scripts` copy:

| OS | Typical pipx path |
|----|-------------------|
| Windows | `%USERPROFILE%\.local\bin\psamvault-mcp.exe` |
| Linux / macOS | `~/.local/bin/psamvault-mcp` |

### Hardened client config (recommended)

Always pass an absolute `command` and clear `PYTHONPATH` so other tools
(e.g. Hermes) cannot contaminate imports:

```json
{
  "mcpServers": {
    "psamvault": {
      "command": "C:\\Users\\YOU\\.local\\bin\\psamvault-mcp.exe",
      "args": [],
      "env": { "PYTHONPATH": "" }
    }
  }
}
```

**Grok Build** (`~/.grok/config.toml`):

```toml
[mcp_servers.psamvault]
command = "C:\\Users\\YOU\\.local\\bin\\psamvault-mcp.exe"
args = []
enabled = true
tool_timeout_sec = 300

[mcp_servers.psamvault.env]
PYTHONPATH = ""
```

On Linux the OS keyring is Secret Service, and the library this package uses
(jeepney 0.9) reads only `DBUS_SESSION_BUS_ADDRESS`. The official MCP SDKs do not
include that variable in the environment they pass to a stdio server, so
`PYTHONPATH=""` alone used to make a working keyring look missing. The server
fills the variable in from `/run/user/<uid>/bus` when that socket exists and is
owned by this user. It does not replace a value you set, and it does not store
secrets anywhere else. A container that cannot see that socket must pass
`DBUS_SESSION_BUS_ADDRESS` and `XDG_RUNTIME_DIR` explicitly — the SDK does not
expand `${...}`. macOS Keychain and Windows Credential Manager need nothing
beyond the variables those SDKs already pass (`HOME`, and on Windows
`USERPROFILE` / `APPDATA` / `SYSTEMROOT`). Details:
[Configuration](docs/reference/configuration.md#os-keyring).

Then **restart the agent session** (or refresh MCP). Config edits do not always
reload tools mid-chat. Verify with `get_version`, then `list_vault_sites`.

Full agent playbook (corrupt pipx, PATH shadowing, session timeout, reload):
[docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md](docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md).

## Transport modes

psamvault-mcp speaks **stdio transport** — the MCP standard for desktop agents, and the only transport implemented.

### stdio (default — for Hermes, Goose, Claude Desktop, Cline, Grok Build)

```bash
psamvault-mcp
```

Starts the MCP server over stdin/stdout. This is the default mode and works with all major MCP desktop clients.

> **Note for agents:** a bare `psamvault-mcp` invocation **waits on stdin** for
> the MCP protocol. That is not a hang — use `--version` / `--help` for smoke
> tests, and let the host spawn the process for real use.

### HTTP/SSE — not implemented

Earlier versions of this README documented `psamvault-mcp --http --port 8433` and an SSE endpoint at
`http://127.0.0.1:8433/sse`. **Neither exists**: the entry point defines no `--http`, `--port` or
`--host` flag, and nothing in the package serves HTTP. A host configured against that URL fails to
connect — stdio is the only transport.

That is deliberate rather than an oversight to patch around: the stdio model gets its safety from the
host process boundary. A network transport for a credential vault needs an authentication design first,
because an unauthenticated local socket would hand any local process the agent's own vault access.

### Goose setup

#### Option A — One-click deeplink

Click or paste this URL into your browser while Goose Desktop is running:

```
goose://extension?cmd=psamvault-mcp&timeout=300&id=psamvault&name=psamVault&description=Use%20stored%20credentials%20without%20exposing%20them%20to%20the%20agent
```

Goose will prompt you to confirm, then the extension is added instantly.

#### Option B — Goose Desktop UI

1. Open Goose Desktop.
2. Click the **sidebar button** (top-left) → **Extensions**.
3. Click **Add custom extension**.
4. Fill in the form:

   | Field | Value |
   |---|---|
   | **Type** | `Standard IO` |
   | **ID** | `psamvault` |
   | **Name** | `psamVault` |
   | **Description** | `Use stored credentials without exposing them to the agent` |
   | **Command** | `psamvault-mcp` |
   | **Timeout** | `300` |

5. Click **Add**.

The extension appears in your Extensions list — toggle it on to activate it.

#### Option C — Config file (advanced)

Edit `~/.config/goose/config.yaml` and add the following under `extensions:`:

```yaml
extensions:
  psamvault:
    name: psamVault
    cmd: psamvault-mcp
    args: []
    enabled: true
    type: stdio
    timeout: 300
```

Save the file and restart Goose (or reload the session).

#### Verifying the extension works

Once added, start a Goose session and try:

```
What credentials do I have stored in my vault?
```

Goose will call `list_vault_sites` via psamvault-mcp. If you see your stored sites, everything is working.

### Hermes setup

Connect to psamvault-mcp via **stdio transport** (default). Add this block to
`~/.hermes/config.yaml` under `mcp_servers`:

```yaml
mcp_servers:
  psamvault:
    command: psamvault-mcp
    enabled: true
```

Restart or reload Hermes — the tools will be discovered automatically.

### Claude Desktop setup

Config file location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "psamvault": {
      "command": "psamvault-mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

### Grok Build setup

1. Install with pipx (see [Installation](#installation)).
2. Add the server to `~/.grok/config.toml` using the **absolute** pipx path
   (example above), or to `~/.mcp.json` if you already use that file.
3. Restart Grok or open `/mcps` and refresh so tools load into the session.
4. Confirm: `grok mcp doctor psamvault` → handshake OK, tools discovered.
5. Ensure the vault CLI session is active: `psamvault login`.

### Other MCP clients

Any MCP client supporting stdio transport can use psamvault-mcp.
**Prefer the absolute pipx path** over a bare command name:

```json
{
  "mcpServers": {
    "psamvault": {
      "command": "/home/YOU/.local/bin/psamvault-mcp",
      "env": { "PYTHONPATH": "" }
    }
  }
}
```

## Troubleshooting

| Symptom | Guide |
|---------|--------|
| MCP will not start / agent cannot connect | [docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md](docs/troubleshooting/MCP-INSTALL-AND-CONNECT.md) |
| `pydantic` / `pydantic_core` import errors with Hermes | [docs/troubleshooting/PYTHONPATH-CONFLICT.md](docs/troubleshooting/PYTHONPATH-CONFLICT.md) |
| Index of all troubleshooting docs | [docs/troubleshooting/README.md](docs/troubleshooting/README.md) |

Quick recovery for a broken Windows pipx install:

```powershell
pipx uninstall psamvault-mcp
Remove-Item -Recurse -Force "$env:USERPROFILE\pipx\venvs\psamvault-mcp" -ErrorAction SilentlyContinue
pipx install psamvault-mcp
# Point MCP config at: $env:USERPROFILE\.local\bin\psamvault-mcp.exe
```

## Configuration

psamvault-mcp reads its backend URL from `~/.psamvault/config.env`, written
automatically by `psamvault configure`.

| Variable | Default | Description |
|---|---|---|
| `PSAMVAULT_API_URL` | `https://psam-vault-backend.onrender.com` | psamvault backend endpoint |
| `PSAMVAULT_LOG_LEVEL` | `INFO` | Log verbosity. Accepts any standard Python level: `DEBUG`, `INFO`, `WARNING`, `ERROR`. Logs go to stderr. |

To point at a self-hosted backend, set the variable in `~/.psamvault/config.env`:

```
PSAMVAULT_API_URL=https://your-backend.example.com
```

## Available tools

Tools are grouped by purpose so AI agents can find the right tool faster:

### 🛠  Entry & Orientation
*Always start here to discover what tool to use.*

| Tool | Description |
|---|---|
| `search_vault_tools` | Discovery tool — call this first to find the right tool for your task |
| `get_version` | Return the installed psamvault-mcp version |

### 🔐  Site Authentication
*End-to-end: discover, check, and log into websites.*

| Tool | Description |
|---|---|
| `list_vault_sites` | List stored site names with username hints (no passwords). Call before `browser_login` |
| `check_credential_exists` | Check if a credential exists for a site. Returns username hint |
| `get_username_for_site` | Get the username only (not password) for a site |
| `browser_login` | Open a real browser and log into a website — credentials filled silently, never shown to the agent |

### 🔑  API Key Operations
*All tools that deal with API keys — discover, use, inject, and protect.*

| Tool | Description |
|---|---|
| `list_api_keys` | List stored API key names with service hints and project grouping (never key values). Optional `project_name` filter |
| `use_credential` | Authenticated HTTP to the entry's own site or the API key's service — other hosts are refused; the response is scrubbed |
| `run_with_credential` | CLI with the credential in env or stdin — URLs in the command are host-checked; output is scrubbed of the secret and its encodings |
| `scan_and_protect` | Scan a project for `.env` secrets, encrypt them into psamvault, replace with placeholders. Supports `project_name` for per-project namespacing |
| `export_key_to_mcp_config` | Export a vault API key into a client MCP config file (Hermes — the only host whose config shape is verified) — auto-verifies HTTP keys before write, with `skip_verify` / `verify_url` overrides |
| `export_key_to_env_file` | Export a vault API key into an agent `.env` as a variable (`agent="hermes"` → `HERMES_HOME/.env`, or explicit `env_path`) — updates in place, timestamped backup, auto-verifies HTTP keys |
| `verify_api_key` | Verify a stored API key is valid against its provider's API. Returns `success`, `verification`, `provider`, `status`, `detail` |

> **Key verification is mandatory before an export write.** HTTP keys are probed against the
> provider's read-only endpoint, and a failed probe blocks the write —
> `skip_verify=true` cannot override it (it covers only providers that cannot be probed at all, and
> the result then records `verification: skipped`). Invalid keys never reach a config or `.env`.

## Changelog and unreleased tracking

Two files, one rule: **nothing merged to `main` should have to be rediscovered at release time.**

| File | Holds | Who writes it |
|---|---|---|
| [`CHANGELOG.unreleased.md`](CHANGELOG.unreleased.md) | merges that are on `main` but **not yet on PyPI** — the answer to "what is pending for the next release?" | whoever merges the change (usually via a follow-up PR) |
| [`CHANGELOG.md`](CHANGELOG.md) | released history, newest first | rolled over **at release time** from the unreleased file |

At release time the unreleased entries are used twice: pasted into the **GitHub release notes** and
prepended to `CHANGELOG.md` under the new version heading; the unreleased file is then reset to its
header. `scripts/docs-sync-check.py` fails the release when `CHANGELOG.md`'s newest section is not the
release the contract calls newest, so a release that forgets the roll-over cannot ship quietly.

## Version lockstep (MCP ↔ skill)

The server and its usage skill are a **pair with a floor**. The pairing ships *inside the wheel* as
`mcp_server/compatibility.json` (each MCP release → the minimum skill version that documents it, plus
the expected tool fingerprint). The skill is the optional Hermes copy at
`HERMES_HOME/skills/psam-custom/psamvault-mcp/SKILL.md`. Public procedures are in this repository under
[docs/skills/](docs/skills/README.md). A fresh install with no Hermes skill is healthy.

```bash
psamvault-mcp compat --check                     # exit 0 in sync, 1 drift (advisory: a newer published release never changes this)
psamvault-mcp compat --check --json              # machine-readable
psamvault-mcp compat --apply                     # install the target release and bring the skill up to date
psamvault-mcp compat --apply --latest            # ...or the newest release published on PyPI — the only way OUT of an install that is already behind
psamvault-mcp compat --apply --allow-breaking    # required when the target REMOVES a tool, or is newer than the installed contract
psamvault-mcp compat --sync-skill                # skill-only update: install the clone's newest skill, MCP untouched
psamvault-mcp compat --apply --from-git          # install the local repo (merged but not yet released)
psamvault-mcp compat --apply --from-git --pull   # ...after stashing local changes and pulling origin/main

psamvault-mcp selfcheck                          # installed vs what a NEW session actually serves (exit 1 on mismatch)
psamvault-mcp doctor                             # why an install looks broken: entry points, pipx records, processes holding the venv
psamvault-mcp doctor --fix                       # ...and repair it: an in-place repair works with sessions up
```

`doctor --fix` has **two repair paths**, and only one of them needs a quiet machine. A stale pipx
**record** — `pipx list` showing an older version than the code that actually runs — is corrected **in
place**: the venv is not recreated, so it works with sessions and MCP servers running, which is nearly
always the case. Relinking an entry point pipx never linked *is* a venv recreation, so that path still
refuses while the venv is held. When it refuses it names every holder (`pid` + image) and what to stop —
read that list before stopping anything twice: the usual holder is the desktop app, whose open sessions
each own an MCP server and which respawns one moments after you kill it.

`--apply` exit codes: **0** ok, **1** install failed, **2** refused (needs `--allow-breaking`), **3** the
contract's release is not on PyPI yet (publish it, or use `--from-git`). `--check` only ever returns 0 or 1 —
an available update is news, not breakage.

The check runs as a **subcommand of the server's own entry point**, so it needs no separate install and no
venv path. On Windows the shim is `psamvault-mcp.exe` (the same one your MCP host config already calls);
the pre-0.5.3 standalone compat console script was **removed** in 0.5.3 because `pipx` never linked it onto
`PATH` — it answered `command not found`.

**The recorded skill version is a floor, not a pin.** Each release says the *minimum* skill version that
documents it, and any skill at or above that floor is healthy:

| State | Meaning |
|---|---|
| skill ≥ floor | ✅ fine — the skill may legitimately move **ahead** of the MCP |
| skill < floor | drift — the skill is older than the server it documents; `--sync-skill` repairs it when you already have a local skill checkout |
| skill missing | not drift — the Hermes skill is optional; follow [docs/skills/](docs/skills/README.md) |

That is what makes a **skill-only update** possible: improving the description of an existing tool is a
skill change with no MCP release behind it. With a local skill checkout (maintainers; override the
path with `PSAMVAULT_SKILL_CLONE`), edit it, then:

```bash
psamvault-mcp compat --sync-skill     # installs the clone's working-tree skill, if it meets the floor
```

`--sync-skill` reads the clone **as-is** (mirrors `--from-git`: uncommitted skill work is installable),
snapshots the current skill first, and applies two guards so the skill can never move backwards
silently:

| Guard | Behaviour |
|---|---|
| floor | refuses when the clone's skill is *below* the floor the installed server requires — and writes nothing |
| no downgrade | refuses when the clone's skill is *older* than the skill already installed (a clone parked on an older branch holds an older skill); the message names the clone, its branch and both versions. `--allow-downgrade` overrides |

`--check` also reports `skill_source` / `skill_source_stale` — when the clone is behind the installed
skill it says so, because a silent downgrade opportunity is exactly what nobody notices.

A contract entry exists the moment a release is **merged**, before it ships. The index pre-check is
deliberately **advisory**: PyPI's JSON API lags an upload (CDN cache), so it never blocks an install
that would succeed — it only explains a real failure (exit 3). Use `--from-git` for the
merged-but-unreleased case.

### Upgrade safety (`--apply`)

Same model as the psamvault CLI's upgrade path: **local work is never lost, and a failed upgrade is
never left installed.**

| Step | What it does |
|---|---|
| Snapshot | copies the installed skill aside (`backups/backup-<stamp>/`, keeps the newest 5) before overwriting it |
| `--pull` | stashes uncommitted work (untracked included), `git pull --ff-only origin main`, then restores it. A failed pull restores immediately and stops; a *conflicting* restore leaves the work parked in a labelled stash and prints the recovery commands |
| Repo report | `--from-git` prints branch, HEAD, dirtiness and position vs `origin/main` (fetched, or marked "as of the last fetch"), and warns when the venv is an editable/source install that a released wheel would detach |
| Smoke test | imports the freshly installed server in a **fresh** interpreter from a neutral cwd — so the repo tree cannot masquerade as the install — and reports its version + tool count |
| Rollback | if the install fails or the smoke test fails, the previously installed release is put back automatically |

- **The installed server wins** — the skill is pulled to match it, never the reverse, and never rolled
  back: an older clone skill is refused (see the guards above).
- A release marked **breaking** is never applied without `--allow-breaking`: a silently disappearing
  tool is exactly the change a human should see.
- `get_version` reports the pairing (`compatibility.paired_skill_version`, newest release,
  `breaking_pending`), so an agent can self-check without extra tooling.
- A tool count alone is **not** a version check: v0.5.0 removed one tool and added another, leaving
  the count at 13 — only the fingerprint reveals that.
- `tests/test_compat.py` fails when the newest contract entry disagrees with the code's actual tool
  surface, so a release that forgets to record itself cannot ship quietly.
- `scripts/docs-sync-check.py` is the release-time **docs gate**: it fails when any doc still names a
  tool the code dropped, claims a stale tool count, omits a tool, or disagrees with the contract.
  Run it first in every release — a tool count alone cannot reveal a renamed or removed tool.

## Architecture

The MCP server manages a single Playwright Chromium instance in-process.
No subprocess daemon is used — the browser lives in the same process as the
MCP server. If the browser crashes, it is automatically restarted on the
next `browser_login` call.

This eliminates the fragile 3-process chain (MCP → CLI daemon → browser)
that caused connection errors with certain MCP clients (e.g. Goose's
`ECONNREFUSED` on internal proxy ports).

## Example agent prompts

Once connected, you can ask your agent things like:

- *"What credentials do I have stored in my vault?"*
- *"What API keys do I have stored?"*
- *"Log me into kaggle.com"*
- *"Open github.com and log me in"*
- *"Check if I have a credential stored for z.ai"*
- *"Get my top 10 starred repos from GitHub"*
- *"Upload my package to PyPI"*
- *"Push to my private repo"*
- *"Protect the secrets in my project directory"*

## Related projects

| Package | What It Does |
|---------|-------------|
| [`pv-dotenv`](https://pypi.org/project/pv-dotenv/) | Drop-in replacement for `python-dotenv` — resolves `psamvault:` placeholders at runtime |
| [`psamvault-cli`](https://github.com/psam-717/psamvault-cli) | CLI + vault management — store, list, and manage credentials |

## Testing

```bash
pip install -e .
pip install pytest pytest-asyncio pytest-httpx pytest-timeout
pytest
```

CI runs that with `PSAMVAULT_PEPPER` set to 64 `a` characters, `PSAMVAULT_API_URL=https://test.example.com`,
and `PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring`. Tests live in `tests/` and cover crypto
primitives, session management, the API client (with httpx mocking), and MCP tool behaviour. The suite
requires no real network access or OS keychain — external dependencies are mocked, and a missing keyring
is exercised with `keyring.backends.fail.Keyring` rather than a live Secret Service.

## Security

- Credentials are decrypted locally on your machine — never sent to the agent
- The agent only receives HTTP responses or redacted CLI output, never credential values
- All communication with the psamvault backend uses HTTPS
- The browser is managed in-process — no subprocess daemon or internal HTTP proxy
- CLI command output is scanned for the credential value and redacted before returning to the agent

## License

MIT — see [LICENSE](LICENSE).