Metadata-Version: 2.4
Name: agent-vault-sdk
Version: 0.1.0
Summary: Zero-trust credential manager for AI agents — Python SDK
Author: agent-vault contributors
License: MIT
Project-URL: Homepage, https://github.com/ewimsatt/agent-vault
Project-URL: Repository, https://github.com/ewimsatt/agent-vault
Project-URL: Issues, https://github.com/ewimsatt/agent-vault/issues
Keywords: security,encryption,credentials,ai-agents,age,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyrage>=1.2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: gitpython>=3.1
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# agent-vault Python SDK

Read-only Python SDK for [agent-vault](https://github.com/ewimsatt/agent-vault) — a zero-trust credential manager for AI agents.

## Installation

```bash
pip install agent-vault

# With MCP server support:
pip install 'agent-vault[mcp]'
```

## Quick Start

```python
from agent_vault import Vault

vault = Vault(
    repo_path="/path/to/vault",
    key_path="~/.agent-vault/agents/my-agent.key",
)

# Pull latest and decrypt
api_key = vault.get("stripe/api-key")
```

## Key Resolution

The SDK resolves the identity key in this order:

1. `key_str=` parameter (raw key string)
2. `key_path=` parameter (path to key file)
3. `AGENT_VAULT_KEY` environment variable (key as string)
4. `~/.agent-vault/owner.key` (default owner key)

## API

### `Vault(repo_path, key_path=None, key_str=None, auto_pull=True)`

Create a read-only vault connection.

- `repo_path`: Path to the Git repo containing `.agent-vault/`
- `key_path`: Path to an age private key file
- `key_str`: Raw age private key string
- `auto_pull`: Git pull before each `get()` (default: True)

### `vault.get(secret_path) -> str`

Decrypt and return a secret. Raises `SecretNotFoundError` or `NotAuthorizedError`.

### `vault.list_secrets(group=None) -> list[SecretMetadata]`

List secret metadata without decrypting.

### `vault.list_agents() -> list[dict]`

List agents and their group memberships.

### `vault.pull()`

Manually pull latest changes from Git remote.

### `vault.reload()`

Reload the manifest from disk (e.g., after a pull).

## MCP Server

The package includes an MCP server for use with MCP-compatible AI agents:

```bash
agent-vault-mcp --repo /path/to/vault --key ~/.agent-vault/agents/my-agent.key
```

This runs a stdio-based MCP server exposing:

- `agent_vault_get(secret)` — retrieve and decrypt a secret
- `agent_vault_list(group?)` — list available secrets

### Claude Desktop Configuration

```json
{
  "mcpServers": {
    "agent-vault": {
      "command": "agent-vault-mcp",
      "args": ["--repo", "/path/to/vault", "--key", "/path/to/agent.key"]
    }
  }
}
```
