# mcp-server-sqlite

Serveur **MCP (Model Context Protocol)** en Python exposant une base **SQLite** à un
assistant IA via un unique outil : `execute_sql`. Usage **local et personnel**.

L'IA peut exécuter n'importe quelle requête SQL (`SELECT`, `INSERT`, `UPDATE`,
`DELETE`, DDL…) et récupérer les résultats au format JSON.

> ⚠️ **Aucun garde-fou de sécurité** : le SQL est totalement libre, il n'y a ni
> mode lecture seule, ni authentification, ni limite. Destiné à un usage local
> par un utilisateur unique.

## Prérequis

- Python **3.12+**
- [`uv`](https://docs.astral.sh/uv/)

## Installation

```bash
uv sync
```

## Lancement

Le chemin de la base SQLite est fourni via `--db-path` **ou** la variable
d'environnement `SQLITE_DB_PATH`. Le fichier est **créé automatiquement** s'il
n'existe pas.

### Mode stdio (usage local standard)

```bash
uv run mcp-server-sqlite --db-path ./ma_base.db
```

### Mode HTTP (JSON, sans SSE)

```bash
uv run mcp-server-sqlite --transport http --db-path ./ma_base.db --host 127.0.0.1 --port 8000
```

Le transport HTTP répond en `application/json` (pas de flux SSE), adapté aux
clients incapables de streamer. Par défaut : `127.0.0.1:8000`.

**Accès navigateur** : le serveur fonctionne sans aucune configuration d'origine.
La protection anti DNS-rebinding du SDK MCP est désactivée (sinon les origines
non-localhost sont rejetées avec « Invalid Origin header ») et le CORS autorise
par défaut toutes les origines (`*`). Si vous souhaitez malgré tout restreindre
le CORS, utilisez `--cors-origin` (répétable) :

```bash
uv run mcp-server-sqlite --transport http --cors-origin http://localhost:3000 --cors-origin https://mon-app.example
```

L'en-tête `Mcp-Session-Id` est exposé pour permettre aux clients navigateurs de
lire l'identifiant de session MCP.

## L'outil `execute_sql`

- **Entrée** : `sql` — une chaîne contenant du SQL arbitraire. Plusieurs
  instructions peuvent être séparées par `;` (exécution de type `executescript`).
- **Sortie** (chaîne JSON) :
  - Requête renvoyant des lignes (`SELECT`) : `{"rows": [{"colonne": valeur, ...}, ...]}`
  - Requête de modification / DDL : `{"rowcount": <nombre de lignes affectées>}`
  - Erreur SQL : `{"error": "<message>"}`
- Les types non natifs JSON sont convertis en chaîne : `BLOB` décodé en UTF-8
  (repli en hexadécimal), dates au format ISO.
- **Commit automatique** après chaque appel réussi.

## Configuration côté client MCP

Deux cas de figure : le client lance lui-même le serveur (**mode stdio**), ou le
client se connecte à un serveur **HTTP** déjà démarré.

### Mode stdio (le client lance le serveur)

#### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "sqlite": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "d:/___AGENTS/mcp-server-sqlite-uv",
        "mcp-server-sqlite",
        "--db-path",
        "d:/___AGENTS/mcp-server-sqlite-uv/ma_base.db"
      ]
    }
  }
}
```

#### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "sqlite": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "d:/___AGENTS/mcp-server-sqlite-uv",
        "mcp-server-sqlite",
        "--db-path",
        "d:/___AGENTS/mcp-server-sqlite-uv/ma_base.db"
      ]
    }
  }
}
```

### Mode HTTP (le serveur est démarré à part)

Démarrez d'abord le serveur en mode HTTP :

```bash
uv run mcp-server-sqlite --transport http --db-path ./ma_base.db --host 127.0.0.1 --port 8000
```

Le point de terminaison MCP est alors disponible sur **`http://127.0.0.1:8000/mcp`**.
Configurez ensuite le client pour s'y connecter par URL.

#### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "sqlite": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

#### Claude Desktop (`claude_desktop_config.json`)

Claude Desktop ne se connecte qu'en stdio ; on passe par le proxy
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) pour atteindre un
serveur HTTP :

```json
{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}
```

> ℹ️ Si le client tourne dans un navigateur, autorisez son origine avec
> `--cors-origin` au lancement du serveur (voir la section Lancement).

## Tests

```bash
uv run pytest
```

## Développement avec mise

Le projet fournit un [mise.toml](mise.toml) qui gère les outils (Python 3.12, uv)
et expose des tâches. `uv` est configuré pour utiliser le Python fourni par mise.

```bash
mise install       # installe Python + uv
mise run install   # uv sync
mise run test      # tests pytest
mise run serve     # serveur en mode stdio
mise run serve-http # serveur en mode HTTP (JSON)
```

## Licence

MIT — voir [LICENSE](LICENSE).