Metadata-Version: 2.4
Name: keysmith-mcp
Version: 0.1.0
Summary: Secure secret vault for AI agents via Model Context Protocol (MCP)
Author-email: Adam <adam@example.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "test"
Dynamic: license-file

# Keysmith MCP 🔐

[![PyPI version](https://img.shields.io/pypi/v/keysmith-mcp.svg)](https://pypi.org/project/keysmith-mcp/)
[![Tests Passing](https://github.com/adam/keysmith-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/adam/keysmith-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Secure secret vault for AI agents using the Model Context Protocol (MCP). Give your agents access to what they need, without compromising your master password or exposing long-lived credentials.

## Why Keysmith?

AI agents and autonomous systems often need access to API keys, database credentials, or other secrets to perform tasks. Most current solutions involve:
1. **Environment Variables**: Hard to manage, visible to all processes, and persist indefinitely.
2. **Hardcoding**: Dangerous and bad practice.
3. **Complex Vaults (HashiCorp/1Password)**: Overkill for local agent development, often requiring complex CLI authentication.

**Keysmith** is designed to be the "Goldilocks" solution: simple enough for a single developer, yet secure enough to protect your most sensitive keys.



## Key Features

- **Strong Encryption**: Uses Fernet (AES-128-CBC) with key derivation via PBKDF2 (SHA-256, 480k iterations).
- **Time-To-Live (TTL)**: Automatically expires secrets after a set period. Great for temporary agent access.
- **Audit Logging**: Every single access (or attempted access) is logged to `~/.keysmith/audit.log`.
- **MCP Native**: Implements the Model Context Protocol, making it plug-and-play with any MCP-compatible environment or autonomous agent.
- **Multi-Agent Swarms**: Designed to support multiple agents on the same machine reading from the same vault simultaneously.
  > [!NOTE]
  > Multi-agent file locking currently requires Unix/macOS. Windows support is planned for v0.2.

## Installation

```bash
pip install keysmith-mcp
```

## Quickstart

1. **Initialize the vault**:
   ```bash
   keysmith init
   ```
   This will prompt you for a master password and create your encrypted vault in `~/.keysmith/`.

2. **Add a secret**:
   ```bash
   # Permanent secret
   keysmith add OPENAI_KEY sk-your-key
   
   # Secret that expires in 3 hours (180 minutes)
   keysmith add GITHUB_TOKEN ghp_your_token --ttl 180
   
   # Short-lived secret for a single task (30 minutes)
   keysmith add STRIPE_KEY sk_live_... --ttl 30
   ```

3. **Configure your MCP Client**:
   Add Keysmith to your MCP host configuration file (e.g., `mcp_config.json` or your custom agent settings):
   ```json
   {
     "mcpServers": {
       "keysmith": {
         "command": "keysmith",
         "args": ["serve"],
         "env": { "KEYSMITH_PASSWORD": "your-master-password" }
       }
     }
   }
   ```

## Security Model

Keysmith follows a simple but robust security model:
- **At Rest**: Your data is stored in `~/.keysmith/vault.enc`, encrypted with a key derived from your master password + a unique salt.
- **In Memory**: The MCP server requires the `KEYSMITH_PASSWORD` environment variable. It decrypts the vault into memory only when the server starts.
- **Agent Visibility**:
    - **list_secrets**: Agent sees only the names (e.g., `STRIPE_KEY`), never the values.
    - **get_secret**: Agent gets the value. This action is permanently recorded in the audit log.
    - **add_secret**: Agent can store new temporary credentials.
    - **revoke_secret**: Agent can "self-destruct" a key after use.

## Comparison

| Feature | 1Password / Vault | Env Vars | Keysmith |
|---------|-------------------|----------|----------|
| Setup Complexity | High | Low | **Low** |
| Agent Integration | Via custom SDKs | Native | **Native (MCP)** |
| Audit Logs | Yes (Enterprise) | No | **Yes (Built-in)** |
| Auto-Expiry | No | No | **Yes (TTL)** |
| Local First | Mostly Cloud | Yes | **Yes** |
| Multi-Agent Support | No | No | **Yes** |

## Roadmap

- OS keychain integration (macOS Keychain, Windows Credential Locker)
- Local web dashboard for audit log visualization
- `.env` file importer

## License

MIT - See [LICENSE](LICENSE) for details.
