Claude-config/mcp/INSTALL.md

# Installation MCP Lesstime — Claude Code & Claude Desktop

Guide d'installation du serveur MCP **Lesstime** (Malio) pour exposer les outils de gestion de projet (projets, tâches, time-entries, etc.) directement dans Claude Code et Claude Desktop.

---

## 1. Prérequis

### 1.1 Node.js (npx)

Claude Desktop a besoin de `npx` pour lancer le proxy `mcp-remote`. Vérifier qu'il est installé :

```bash
which npx
node --version
```

Si rien ne sort, installer Node.js :
- **Debian/Ubuntu** : `sudo apt install nodejs npm`
- **Via nvm** (recommandé) : voir https://github.com/nvm-sh/nvm

### 1.2 Token API Lesstime

Chaque utilisateur a son **propre token**, lié à ses droits dans l'application. Il n'existe **pas** de token partagé.

1. Aller sur **http://project.malio-dev.fr/profile** (connecté avec son compte Lesstime)
2. Section **Token API MCP**
3. Cliquer sur **Régénérer**
4. **Copier le token affiché immédiatement** (il ne sera plus visible après)

> ⚠️ Le token est un secret personnel. Ne jamais le commiter, ne jamais le partager dans Slack / mail / logs publics. Si tu le compromets, retourne sur le profil et régénère-en un nouveau (l'ancien est invalidé).

---

## 2. Installation Claude Code

Claude Code supporte nativement les transports MCP `http`. C'est la méthode la plus simple.

### 2.1 Éditer le fichier de config

```bash
# Créer le dossier si besoin
mkdir -p ~/.claude

# Ouvrir le fichier
nano ~/.claude/.mcp.json
```

### 2.2 Coller la configuration

```json
{
  "mcpServers": {
    "lesstime": {
      "type": "http",
      "url": "http://project.malio-dev.fr/_mcp",
      "headers": {
        "Authorization": "Bearer TON_TOKEN_ICI"
      }
    }
  }
}
```

Remplacer `TON_TOKEN_ICI` par le token récupéré à l'étape 1.2.

### 2.3 Redémarrer Claude Code

```bash
/exit
```

puis relancer la commande `claude` dans le terminal. Le serveur `lesstime` doit apparaître dans la liste des MCPs connectés.

---

## 3. Installation Claude Desktop

Claude Desktop ne supporte **pas** nativement le transport HTTP — il faut passer par un wrapper local `mcp-remote` (lancé via `npx`).

### 3.1 Localiser le fichier de config

Sur Linux :

```
~/.config/Claude/claude_desktop_config.json
```

Sur macOS :

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

Sur Windows :

```
%APPDATA%\Claude\claude_desktop_config.json
```

### 3.2 Éditer le fichier

```bash
mkdir -p ~/.config/Claude
nano ~/.config/Claude/claude_desktop_config.json
```

### 3.3 Ajouter le bloc `mcpServers`

Si le fichier est **vide** ou inexistant :

```json
{
  "mcpServers": {
    "lesstime": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://project.malio-dev.fr/_mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer TON_TOKEN_ICI"
      ]
    }
  }
}
```

Si le fichier contient **déjà** d'autres clés (ex. `preferences`), ajouter juste la clé `mcpServers` à côté, sans toucher au reste :

```json
{
  "preferences": {
    "...": "..."
  },
  "mcpServers": {
    "lesstime": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://project.malio-dev.fr/_mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer TON_TOKEN_ICI"
      ]
    }
  }
}
```

> 💡 Le flag `--allow-http` est **obligatoire** : `mcp-remote` refuse par défaut les URLs non-HTTPS. Comme `project.malio-dev.fr` est en HTTP, sans ce flag tu auras l'erreur : `Error: Non-HTTPS URLs are only allowed for localhost or when --allow-http flag is provided`.

### 3.4 Redémarrer Claude Desktop

Quitter **complètement** l'app (`Ctrl+Q` ou via le menu — fermer la fenêtre ne suffit pas), puis relancer. Le serveur `lesstime` doit apparaître dans la liste des outils MCP disponibles.

---

## 4. Vérification

Une fois Claude (Code ou Desktop) relancé, demander par exemple :

> *« Liste-moi les projets via le MCP lesstime »*

Si tout est bien configuré, Claude appelle l'outil `list-projects` et renvoie la liste des projets actifs (ADMIN, COLTURA, Ferme, Formation, etc.).

### Outils exposés par le MCP Lesstime

Le serveur expose une vingtaine d'outils, regroupés par entité :

- **Projets** : `list-projects`, `get-project`, `create-project`, `update-project`
- **Tâches** : `list-tasks`, `get-task`, `create-task`, `update-task`, `delete-task`
- **Récurrences de tâches** : `create-task-recurrence`, `update-task-recurrence`, `delete-task-recurrence`
- **Time-entries** : `list-time-entries`, `create-time-entry`, `update-time-entry`, `delete-time-entry`
- **Groupes** : `list-groups`, `create-group`, `update-group`
- **Référentiels** : `list-clients`, `list-users`, `list-statuses`, `list-priorities`, `list-tags`, `list-efforts`

---

## 5. Troubleshooting

### Erreur : `Non-HTTPS URLs are only allowed for localhost...`

Tu as oublié `--allow-http` dans les `args` de la config Claude Desktop. Voir 3.3.

### Erreur : `command not found: npx`

Node.js n'est pas installé ou pas dans le PATH. Voir 1.1.

### Erreur 401 / 403 dans les logs

Token invalide ou révoqué. Régénérer un nouveau token sur http://project.malio-dev.fr/profile et le remettre dans la config.

### Le serveur ne monte pas après redémarrage

- Vérifier que le JSON est **syntaxiquement valide** (virgule manquante, accolades non fermées). On peut tester avec : `cat ~/.config/Claude/claude_desktop_config.json | jq .`
- Vérifier les logs Claude Desktop :
  - Linux : `~/.config/Claude/logs/`
  - macOS : `~/Library/Logs/Claude/`
- Vérifier que le serveur Lesstime est joignable : `curl http://project.malio-dev.fr/_mcp` (devrait répondre, même si c'est une erreur 401 sans header).

### Tester `mcp-remote` à la main

```bash
npx -y mcp-remote http://project.malio-dev.fr/_mcp --allow-http --header "Authorization: Bearer TON_TOKEN_ICI"
```

Le process doit rester en vie et écouter sur stdin. Ctrl+C pour quitter.

---

## 6. Désinstallation

Pour retirer le MCP : supprimer la clé `"lesstime"` du bloc `mcpServers` dans le fichier de config correspondant, puis redémarrer Claude.

Si plus aucun serveur n'est configuré, on peut laisser un bloc vide :

```json
{
  "mcpServers": {}
}
```

---

*Dernière mise à jour : 13 mai 2026*