# 📖 MCP Manuels — Assistant PDF pour Claude

Un serveur **MCP (Model Context Protocol)** qui permet à **Claude Desktop** de lire et chercher dans vos manuels techniques PDF (manuels d'équipement vidéo, réseau, lumière, fiches techniques…) directement dans la conversation.

Posez une question en langage naturel, Claude va chercher la réponse dans vos PDF et cite la source + le numéro de page.

> ⚠️ **Ce dépôt ne contient aucun manuel.** Les PDF des constructeurs sont sous copyright et ne sont pas redistribués ici. Vous ajoutez **vos propres PDF** dans le dossier `manuals/` (voir plus bas).

---

## ✨ Fonctionnalités

- Charge automatiquement tous les PDF du dossier `manuals/`.
- Recherche dans le **sommaire** (TOC natif du PDF, ou détection heuristique si absent).
- Recherche dans le **contenu** complet (découpage en chunks).
- 4 outils exposés à Claude :

| Outil | Rôle |
|---|---|
| `list_manuals` | Inventaire des manuels chargés + diagnostic d'indexation |
| `ask_manual` | Répond à une question en cherchant dans tous les manuels |
| `search_sections` | Cherche un titre de section dans les sommaires |
| `get_page` | Retourne le texte brut d'une page précise |

---

## 📦 Prérequis

- **Python 3.10+** (testé jusqu'à 3.14). À installer depuis [python.org](https://www.python.org/) — **pas** via le Microsoft Store.
- **Claude Desktop** ([téléchargement](https://claude.ai/download)).

---

## 🚀 Installation

```bash
# 1. Cloner le dépôt
git clone https://github.com/<votre-compte>/mcp-manuels.git
cd mcp-manuels

# 2. (Recommandé) Créer un environnement virtuel
python -m venv .venv
# Windows :
.venv\Scripts\activate
# macOS / Linux :
source .venv/bin/activate

# 3. Installer les dépendances
python -m pip install -r requirements.txt
```

> 💡 Si la commande `pip` n'est pas reconnue (souvent sous Windows), utilisez toujours `python -m pip …`.

---

## 📁 Ajouter vos manuels

Déposez vos fichiers **`.pdf`** directement dans le dossier `manuals/` :

```
mcp-manuels/
└── manuals/
    ├── mon-manuel-1.pdf
    └── mon-manuel-2.pdf
```

Le serveur les charge tous au démarrage. Plus un PDF a un **sommaire natif**, meilleure est la recherche (sinon une détection heuristique prend le relais).

---

## ⚙️ Configurer Claude Desktop

Claude Desktop lance le serveur via un fichier `claude_desktop_config.json`.

### 1. Activer le Mode développeur
Dans Claude Desktop : **Réglages → Développeur → activer le Mode développeur**.
Sans ça, la config des serveurs MCP locaux est **ignorée**.

### 2. Trouver / ouvrir le bon fichier de config
Le plus fiable : dans **Réglages → Développeur → Edit Config**. Ce bouton ouvre le **bon** fichier, quel que soit votre OS ou votre mode d'installation.

Emplacements par défaut :
| OS | Chemin |
|---|---|
| **Windows** (.exe classique) | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Windows** (Microsoft Store) | `…\AppData\Local\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json` |
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |

> 🪟 **Piège Windows / Microsoft Store :** si Claude vient du Store, son `%APPDATA%` est *virtualisé* dans `…\Packages\…\LocalCache\…`. Écrire dans le `%APPDATA%\Roaming\Claude` classique n'aura **aucun effet**. Passez toujours par **Edit Config** pour viser le bon fichier.

### 3. Ajouter le serveur
Copiez le contenu de [`claude_desktop_config.example.json`](claude_desktop_config.example.json) et **adaptez les chemins** :

```json
{
  "mcpServers": {
    "manuels": {
      "command": "python",
      "args": ["/chemin/absolu/vers/mcp-manuels/server.py"],
      "env": {
        "PYTHONUTF8": "1",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

- `command` : chemin vers votre Python. Si vous utilisez un venv, pointez vers le Python du venv
  (`.venv/Scripts/python.exe` sous Windows, `.venv/bin/python` sous macOS/Linux). Sinon `python` suffit souvent.
- `args` : chemin **absolu** vers `server.py`.
- Sous **Windows**, échappez les `\` en `\\` dans le JSON : `"C:\\Users\\...\\server.py"`.
- Le bloc `env` fige l'encodage **UTF-8** (évite les bugs d'accents sous Windows). Gardez-le.

### 4. Redémarrer Claude *complètement*
Fermer la fenêtre ne suffit pas. **Windows** : clic droit sur l'icône dans la barre des tâches → Quitter. **macOS** : ⌘Q. Puis relancer.

### 5. Vérifier
Cliquez sur l'icône **🔨 (outils)** dans la zone de saisie : le serveur `manuels` doit apparaître avec ses 4 outils. Testez avec :
> « liste les manuels disponibles »

---

## 💬 Exemples d'usage

- « Quels manuels sont disponibles ? »
- « Comment configurer la redondance sur le MX30 ? »
- « Cherche les sections sur le backup réseau »
- « Donne-moi le texte de la page 24 du manuel MX30 »

---

## 🛠️ Dépannage

| Symptôme | Cause probable |
|---|---|
| Le serveur n'apparaît pas du tout | Mode développeur désactivé, ou config écrite au mauvais endroit (piège Store) |
| Pas de dossier `logs/` créé | Claude n'a jamais tenté de lancer le serveur → il ne lit pas la config |
| Serveur en rouge / erreur | Voir le log (ci-dessous) |
| Warning « Échec extraction TOC natif » | `pymupdf` non installé → `python -m pip install pymupdf` |
| Aucun PDF chargé | Dossier `manuals/` vide, ou chemin de `server.py` incorrect dans la config |

**Lire les logs** (nom du serveur = clé dans la config, ici `manuels`) :
- Windows : `%APPDATA%\Claude\logs\mcp-server-manuels.log` (ou le chemin virtualisé Store)
- macOS : `~/Library/Logs/Claude/mcp-server-manuels.log`

**Tester le serveur seul** (hors Claude) :
```bash
python server.py
```
Il doit afficher `[INFO] Chargement : …` pour chaque PDF puis `[INFO] Total : …`, et se figer (il attend Claude). `Ctrl+C` pour quitter. Si un warning ou une erreur apparaît ici, le problème est dans le serveur ou les PDF, pas dans Claude.

---

## 📜 Licence

MIT — voir [LICENSE](LICENSE). Le code est libre ; **les manuels PDF que vous y ajoutez restent la propriété de leurs éditeurs respectifs**.