npm package: @quilium/mcp
Description: Model Context Protocol server for Quilium CMS. Note: This package was previously published as 'quilium-mcp-server' - please migrate to @quilium/mcp.
Author: amaxime@gmail.com
Latest version: 1.4.1

# Quilium MCP Server

> **⚠️ Migration Notice**: This package has been renamed from `quilium-mcp-server` to `@quilium/mcp`. Please update your installation.

Serveur MCP (Model Context Protocol) pour le CMS Quilium, permettant aux modèles de langage d'interagir avec l'API Quilium CMS.

## Vue d'ensemble

Ce serveur MCP expose des **Resources** pour accéder aux données du CMS Quilium :

- `quilium://site-configuration` - Configuration complète du site (types de pages, contenus, collections, champs globaux, paramètres divers)
- `quilium://cms-documentation` - Documentation complète du CMS pour comprendre son utilisation

## Installation

### Prérequis

- Node.js 18+
- npm ou yarn
- Accès à une instance Quilium CMS avec API

### Installation des dépendances

```bash
npm install
```

## Configuration

### Variables d'environnement

- `QUILIUM_JWT_TOKEN` : Token JWT RSA signé pour l'authentification

## Utilisation

### Développement

```bash
# Compiler TypeScript et démarrer
npm run dev
```

### Installation pour Claude Desktop

#### Option 1: Avec npx (recommandée - aucune installation requise)

Ajoutez cette configuration dans le fichier de configuration de Claude Desktop :

```json
{
  "mcpServers": {
    "quilium": {
      "command": "npx",
      "args": ["@quilium/mcp"],
      "env": {
        "QUILIUM_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

#### Option 2: Installation globale

```bash
npm install -g @quilium/mcp
```

Puis dans la configuration de Claude Desktop :

```json
{
  "mcpServers": {
    "quilium": {
      "command": "quilium-mcp",
      "env": {
        "QUILIUM_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

#### Option 3: Développement local

Pour le développement local, clonez ce dépôt et utilisez :

```json
{
  "mcpServers": {
    "quilium": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/quilium-mcp",
      "env": {
        "QUILIUM_JWT_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

### Exécution directe

#### Mode par défaut (stdio)

```bash
# Compiler puis exécuter
npm run build
npm start
# ou
node dist/index.js
```

#### Mode HTTP

Pour utiliser le serveur en mode HTTP plutôt que stdio :

```bash
# Compiler puis lancer en HTTP sur le port 3002 (défaut)
npm run build
node dist/index.js http

# Ou sur un port spécifique
node dist/index.js http 3001
```

Le serveur expose alors l'endpoint `/mcp` sur `http://localhost:3002/mcp`.

#### Mode SSE (Server-Sent Events)

```bash
# Lancer en mode SSE
npm run build
node dist/index.js sse
```

Endpoints disponibles :
- SSE : `http://localhost:3002/sse`
- Messages : `http://localhost:3002/messages`

#### Mode Webmaster (Restreint)

Le mode webmaster désactive les outils d'administration pour les utilisateurs avec des privilèges restreints :

```bash
# Démarrer en mode webmaster (stdio)
npm run build
node dist/index.js --webmaster

# Ou en mode HTTP avec webmaster
node dist/index.js http --webmaster

# Ou en mode SSE avec webmaster  
node dist/index.js sse --webmaster
```

**Outils désactivés en mode webmaster :**
- `update-setting` - Modification des configurations YAML
- `update-settings-partial` - Modifications partielles YAML 
- `update-route` - Modification des routes
- `delete-route` - Suppression des routes
- `get-routes` - Consultation des routes
- `create-route` - Création de routes
- `quilium-cli` - Commandes CLI Quilium

Tous les autres outils restent disponibles (gestion du contenu, navigation, médias, ItemSets, etc.).

### Test avec MCP Inspector

Pour tester le serveur avec l'outil MCP Inspector :

1. Installer MCP Inspector : `npm install -g @modelcontextprotocol/inspector`
2. Compiler le serveur : `npm run build`
3. Lancer l'inspector : `mcp-inspector`
4. Configurer la connexion :
   - **Command** : `node`
   - **Args** : `dist/index.js`
   - **Working Directory** : `/path/to/quilium-mcp-python`
   - **Transport** : `stdio`

L'inspector vous permettra de tester les resources `quilium://site-configuration` et `quilium://cms-documentation`.

## Resources disponibles

### site-configuration

Fournit la configuration complète du site en agrégeant les 5 endpoints de configuration :

- Types de pages (`/settings/page-types/raw`)
- Types d'ItemSets (`/settings/item-set-types/raw`) 
- Champs globaux (`/settings/global-fields/raw`)
- Types de contenu (`/settings/content-types/raw`)
- Configuration diverse (`/settings/miscellaneous/raw`)

**URI** : `quilium://site-configuration`

### cms-documentation

Fournit la documentation complète du CMS en concaténant les fichiers :

- `docs/cms/all-examples.md` - Exemples pratiques
- `docs/cms/all-guides.md` - Guides d'utilisation  
- `docs/cms/all-settings.md` - Spécifications YAML

**URI** : `quilium://cms-documentation`

## Tools disponibles

### add-content-to-page

Ajoute un bloc de contenu à une page spécifique du CMS.

**Paramètres requis :**
- `navigation_key` : Clé de la navigation (ex: "main")
- `page_id` : UUID de la page où ajouter le contenu
- `section` : Nom de la section (ex: "main", "sidebar")
- `content_type` : Type de contenu (doit exister dans la configuration)

**Paramètres optionnels :**
- `custom` : Objet avec les données spécifiques au type de contenu
- `order` : Position dans la section (auto-assigné si omis)
- `state` : État du contenu ("active" ou "inactive", défaut: "active")
- `visible` : Visibilité du contenu (défaut: true)
- `website` : UUID du site web (ou utilise quilium.json)
- `pool` : Nom du pool (ou utilise quilium.json)

**Exemple d'utilisation :**
```json
{
  "navigation_key": "main",
  "page_id": "550e8400-e29b-41d4-a716-446655440000",
  "section": "main",
  "content_type": "text",
  "custom": {
    "title": "Mon titre",
    "content": "Contenu de l'article...",
    "imagefield": [{"id": "uuid-of-image"}]
  }
}
```

### Autres tools

Le serveur MCP expose également d'autres tools pour la gestion du CMS :

- `update-setting` : ⚠️ REMPLACE la configuration complète (voir [workflow](docs/workflow-configuration-update.md))
- `get-documentation` : Récupère la documentation complète du CMS
- `get-site-settings` : ⭐ TOUJOURS utiliser en premier - Obtient les paramètres actuels du site
- `get-navigations-with-pages` : Liste toutes les navigations avec leurs pages
- `add-page-to-navigation` : Ajoute une nouvelle page à une navigation
- `order-contents` : Réorganise les blocs de contenu d'une page

**⚠️ Important** : Avant de modifier des configurations avec `update-setting`, consultez le [workflow de modification](docs/workflow-configuration-update.md) pour éviter de perdre des données.

## Structure du projet

```
quilium-mcp/
├── package.json             # Dépendances Node.js
├── tsconfig.json           # Configuration TypeScript
├── src/
│   ├── index.ts            # Serveur MCP principal
│   ├── quilium-client.ts   # Client API Quilium
│   ├── resources.ts        # Implémentation des Resources MCP
│   └── config.ts           # Configuration & authentification
├── dist/                   # Code compilé (généré)
├── docs/
│   └── cms/                # Documentation CMS (exemples, guides, specs)
└── README.md
```

## Cas d'usage

- **Analyse de configuration** : Comprendre l'architecture d'un site Quilium
- **Génération de contenu** : Créer des configurations YAML valides basées sur la documentation
- **Assistance développement** : Accéder rapidement aux spécifications et exemples
- **Documentation contextuelle** : Fournir au LM toutes les informations nécessaires sur le CMS

## Contribuer

1. Fork le projet
2. Créez une branche pour votre fonctionnalité
3. Commitez vos changements  
4. Poussez vers la branche
5. Ouvrez une Pull Request

## Licence

MIT License - voir le fichier LICENSE pour plus de détails.