# secret-vault-mcp

Serveur MCP (Model Context Protocol) de **coffre-fort de secrets** : il stocke vos identifiants, clés d'API et tokens dans le **gestionnaire de credentials du système d'exploitation**, et les expose à tout client MCP (agents IA, opencode, assistants) via quatre outils simples.

Aucune valeur sensible ne transite par le serveur de façon persistante ailleurs que dans le magasin sécurisé de l'OS : le serveur ne conserve localement qu'un **index de noms** (utile pour lister les secrets sans jamais exposer leurs valeurs).

## Fonctionnalités

| Outil | Description |
|---|---|
| `secret_set(name, value)` | Stocke un secret dans le gestionnaire de credentials OS. Retourne uniquement des métadonnées (jamais la valeur). |
| `secret_get(name)` | Récupère un secret. À utiliser uniquement lorsque la valeur est réellement nécessaire. |
| `secret_delete(name)` | Supprime un secret du magasin OS et de l'index local. |
| `secret_list()` | Liste les **noms** des secrets stockés. **Ne retourne jamais les valeurs.** |

Chaque secret est enregistré sous une cible préfixée par le service (`<service>/<name>`), ce qui évite les collisions avec d'autres applications du gestionnaire de credentials.

## Sécurité

- **Stockage OS natif** : sur Windows, les secrets sont écrits dans le *Credential Manager* via l'API Win32 (`CredWriteW` / `CredReadW` / `CredDeleteW`) appelée directement par `ctypes` — **aucune dépendance native**, aucun mot de passe en clair sur disque.
- **Valeurs jamais retournées dans les listes** : `secret_list()` ne renvoie que les noms ; la lecture d'une valeur exige un appel explicite à `secret_get`.
- **Index local minimal** : un fichier JSON ne contenant que les noms des secrets est conservé hors du code source (`%APPDATA%\secret-vault\index.json` sous Windows, `~/secret-vault/index.json` ailleurs). Il ne contient aucune valeur.
- **Aucun secret en dur** : le serveur ne contient aucun token, clé ou mot de passe embarqué.
- **Messages d'erreur contrôlés** : les erreurs mentionnent le nom du secret mais ne révèlent jamais sa valeur.

## Prérequis

- **Python 3.10+** (le code utilise les annotations de type `str | None`)
- **Windows** : Credential Manager (backend natif, support complet)
- **macOS / Linux** : le serveur démarre, mais le backend natif (Keychain / libsecret) **n'est pas encore implémenté** — `secret_set`, `secret_get` et `secret_delete` renvoient une erreur sur ces plateformes. Seul `secret_list()` fonctionne (index local).
- Une seule dépendance externe : le SDK Python MCP (`mcp>=1.2.0`)

## Installation

```bash
pip install mcp
```

Clonez ou copiez `secret_vault_mcp_server.py` dans un dossier de votre choix, puis lancez le serveur :

```bash
python secret_vault_mcp_server.py
```

Le serveur démarre en mode stdio et attend les appels MCP.

## Configuration MCP (opencode.json)

Ajoutez le serveur à la section `mcpServers` de votre configuration opencode :

```json
{
  "mcpServers": {
    "secret-vault": {
      "type": "local",
      "command": ["python", "C:/chemin/vers/secret_vault_mcp_server.py"],
      "enabled": true
    }
  }
}
```

> Remplacez `C:/chemin/vers/` par le dossier où vous avez placé le serveur. Après modification, rechargez la configuration (`opencode mcp reload` ou redémarrage).

### Utilisation

Une fois connecté, les agents peuvent utiliser les outils du serveur :

```
secret_set("github_token", "ghp_...")     # stocke un secret
secret_get("github_token")                # récupère la valeur
secret_list()                             # liste les noms (jamais les valeurs)
secret_delete("github_token")             # supprime le secret
```

## Outils exposés

- `secret_set(name: str, value: str) -> str`
- `secret_get(name: str) -> str`
- `secret_delete(name: str) -> str`
- `secret_list() -> str`

## Structure du projet

```
secret_vault_mcp_server.py   # serveur MCP (fichier unique)
requirements.txt             # dépendances
README.md                    # ce document
LICENSE                      # licence MIT
```

## Licence

[MIT](LICENSE) — © 2026 Jean-Luc KOUMAGLO (menoxz)