# Store a secret
> add a secret called github with username felipe and password xK9!mP2qR8vN4wL7

# List everything (no passwords exposed)
> show me all my saved credentials

# Retrieve one (without exposing the password)
> get the github entry

# Retrieve and reveal
> get the github entry and show me the password

# Generate a strong password
> generate a 40-character password with symbols, no ambiguous characters

# Search across all fields
> find any entry that mentions "opencode"

# Update (rotate a password)
> rotate the password for the github entry to a new generated one

# Delete
> delete the entry called old-mailbox

# Status
> how many entries are in the vault and when was it last accessed?

{ "method": "tools/call", "params": { "name": "add_secret",
  "arguments": { "name": "github", "username": "felipe", "password": "xK9!mP2qR8vN4wL7" } } }

{ "method": "tools/call", "params": { "name": "list_secrets" } }

{ "method": "tools/call", "params": { "name": "get_secret",
  "arguments": { "name": "github", "reveal_password": true } } }

{ "method": "tools/call", "params": { "name": "generate_password",
  "arguments": { "length": 40, "symbols": true, "exclude_ambiguous": true } } }

{ "method": "tools/call", "params": { "name": "search_secrets",
  "arguments": { "query": "opencode" } } }

{ "method": "tools/call", "params": { "name": "update_secret",
  "arguments": { "name": "github", "password": "<new-generated>" } } }

{ "method": "tools/call", "params": { "name": "delete_secret",
  "arguments": { "name": "old-mailbox" } } }

{ "method": "tools/call", "params": { "name": "vault_status" } }

import asyncio, os
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(
        command="/home/felipe/infra/secret-vault-mcp/.venv/bin/python3",
        args=["-u", "/home/felipe/infra/secret-vault-mcp/server.py"],
        env={**os.environ, "VAULT_MASTER_PASSWORD": "your-long-passphrase"},
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            await session.call_tool("add_secret", {
                "name": "github", "username": "felipe", "password": "xK9!mP2qR8vN4wL7",
                "url": "https://github.com",
            })

            result = await session.call_tool("get_secret", {
                "name": "github", "reveal_password": True,
            })
            print(result.content[0].text)

asyncio.run(main())

# Onboarding: create a few entries
> store these credentials: github/felipe/<gen-32>, aws-root/admin/<gen-40>, redis-local/redis/<gen-24>

# Daily use: look up a password to paste into another tool
> get the aws-root entry and reveal the password

# Rotation: replace a weak/old password
> generate a 32-character password, then update the github entry with it

# Audit: what do I have stored?
> list all entries and group them by URL domain

# Cleanup: remove obsolete entries
> delete entries named "test-1", "test-2", and "demo"

cd ~/infra/secret-vault-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# edit .env and set VAULT_MASTER_PASSWORD

# via the MCP stdio transport (used by opencode/Claude Desktop/Cursor)
python server.py

# or with the master password inline
VAULT_MASTER_PASSWORD="my-long-passphrase" python server.py

pytest                                        # 47 tests
pytest --cov=auth --cov=client --cov=models --cov=server

$XDG_DATA_HOME/secret-vault-mcp/   (default: ~/.local/share/secret-vault-mcp/)
  ├── vault.enc      # AES-256-GCM ciphertext
  ├── vault.salt     # 16-byte salt (0600)
  └── vault.lock     # flock file

secret-vault-mcp/
  ├── auth.py            # VaultConfig + constants (KDF, cipher, paths)
  ├── client.py          # VaultClient (encrypt/decrypt, CRUD, lock, search, generate)
  ├── models.py          # Pydantic models (SecretEntry, SecretUpdate, VaultState)
  ├── server.py          # FastMCP server + tool definitions
  ├── tests/
  │   ├── conftest.py
  │   ├── test_auth.py
  │   ├── test_client.py
  │   └── test_server.py
  ├── pyproject.toml
  ├── .env.example
  ├── .gitignore
  ├── LICENSE
  ├── .github/workflows/ci.yml
  └── README.md

{
  "mcp": {
    "secret-vault": {
      "type": "stdio",
      "command": "/home/felipe/infra/secret-vault-mcp/.venv/bin/python3",
      "args": ["-u", "/home/felipe/infra/secret-vault-mcp/server.py"],
      "env": {
        "VAULT_MASTER_PASSWORD": "your-long-passphrase-here"
      },
      "enabled": true
    }
  }
}