Inventory/docs/mcp/README.md

# MCP Server — Inventory

Serveur MCP (Model Context Protocol) pour l'application Inventory. Permet aux assistants IA (Claude, ChatGPT, Codex) de consulter et gérer l'inventaire industriel.

## Prérequis

- Un profil actif avec rôle suffisant (ROLE_VIEWER pour lecture, ROLE_GESTIONNAIRE pour écriture)
- Accès au tunnel pour les clients distants (Claude Desktop, ChatGPT Desktop)
- Docker Compose démarré (`make start`)

## Configuration par client

### Claude Code (local, stdio)

Le fichier `.mcp.json` à la racine du projet est déjà configuré. Remplacez les placeholders :

```json
{
  "mcpServers": {
    "inventory": {
      "command": "docker",
      "args": [
        "exec", "-i",
        "-e", "MCP_PROFILE_ID=VOTRE_PROFILE_ID",
        "-e", "MCP_PROFILE_PASSWORD=VOTRE_PASSWORD",
        "php-inventory-apache",
        "php", "bin/console", "mcp:server"
      ]
    }
  }
}
```

### Claude Desktop (HTTP via tunnel)

Dans `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "inventory": {
      "url": "https://inventory.company-tunnel.com/_mcp",
      "headers": {
        "X-Profile-Id": "VOTRE_PROFILE_ID",
        "X-Profile-Password": "VOTRE_PASSWORD"
      }
    }
  }
}
```

### ChatGPT Desktop / Codex

Meme principe HTTP avec l'URL du tunnel + headers d'auth.

## Catalogue des Tools

### Tools de haut niveau

| Tool | Description | Role |
|------|-------------|------|
| `search_inventory` | Recherche globale (machines, pieces, composants, produits, sites, constructeurs) | VIEWER |
| `get_machine_structure` | Hierarchie complete d'une machine | VIEWER |
| `clone_machine` | Clone une machine avec toute sa structure | GESTIONNAIRE |
| `get_dashboard_stats` | Statistiques globales | VIEWER |
| `get_entity_history` | Historique d'audit d'une entite | VIEWER |
| `get_activity_log` | Journal d'activite global | VIEWER |

### CRUD par entite

Pour chaque entite (Machine, Composant, Piece, Produit, Site, Constructeur) :

| Pattern | Exemple | Role |
|---------|---------|------|
| `list_{entite}s` | `list_machines` | VIEWER |
| `get_{entite}` | `get_machine` | VIEWER |
| `create_{entite}` | `create_machine` | GESTIONNAIRE |
| `update_{entite}` | `update_machine` | GESTIONNAIRE |
| `delete_{entite}` | `delete_machine` | GESTIONNAIRE |

### Slots

| Tool | Description | Role |
|------|-------------|------|
| `list_slots` | Lister les slots d'un composant ou piece | VIEWER |
| `update_slots` | Remplir/vider les slots | GESTIONNAIRE |

### Machine Links

| Tool | Description | Role |
|------|-------------|------|
| `list_machine_links` | Liens composant/piece/produit d'une machine | VIEWER |
| `add_machine_links` | Ajouter des liens | GESTIONNAIRE |
| `update_machine_link` | Modifier un lien | GESTIONNAIRE |
| `remove_machine_link` | Supprimer un lien | GESTIONNAIRE |

### Commentaires

| Tool | Description | Role |
|------|-------------|------|
| `list_comments` | Lister les commentaires d'une entite | VIEWER |
| `create_comment` | Creer un commentaire | VIEWER |
| `resolve_comment` | Resoudre un commentaire | GESTIONNAIRE |
| `get_unresolved_comments_count` | Nombre de commentaires non resolus | VIEWER |

### Custom Fields

| Tool | Description | Role |
|------|-------------|------|
| `list_custom_field_values` | Valeurs de champs perso d'une entite | VIEWER |
| `upsert_custom_field_values` | Creer/mettre a jour des valeurs | GESTIONNAIRE |
| `delete_custom_field_value` | Supprimer une valeur | GESTIONNAIRE |

### Documents

| Tool | Description | Role |
|------|-------------|------|
| `list_documents` | Lister les documents d'une entite | VIEWER |
| `delete_document` | Supprimer un document | GESTIONNAIRE |

> **Limitation :** L'upload de documents n'est pas supporte via MCP (protocole JSON uniquement). Utilisez l'API REST `/api/documents` (POST multipart).

### ModelTypes

| Tool | Description | Role |
|------|-------------|------|
| `list_model_types` | Lister par categorie | VIEWER |
| `get_model_type` | Detail avec skeleton requirements | VIEWER |
| `create_model_type` | Creer | GESTIONNAIRE |
| `update_model_type` | Modifier | GESTIONNAIRE |
| `delete_model_type` | Supprimer | GESTIONNAIRE |
| `sync_model_type` | Preview/sync skeleton | GESTIONNAIRE |

## Workflows guides

### Creer un composant complet

```
1. list_model_types(category: "composant")      -> choisir le type
2. get_model_type(modelTypeId: "...")            -> voir le skeleton
3. create_composant(name, reference, modelTypeId) -> cree + slots auto
4. search_inventory(query: "Roulement", types: "piece") -> trouver pieces
5. update_slots(slots: [{slotId, selectedPieceId}])     -> remplir
6. upsert_custom_field_values(entityType: "composant", entityId, fields: [...])
```

### Creer une machine complete (bottom-up)

```
1. Creer les produits necessaires
2. Creer les pieces (avec produits dans les slots)
3. Creer les composants (avec pieces dans les slots)
4. list_sites -> choisir le site
5. create_machine(name, siteId)
6. add_machine_links(machineId, links: [{type: "composant", entityId, quantity}])
7. upsert_custom_field_values(entityType: "machine", machineId, fields: [...])
```

## Resources MCP

| URI | Description |
|-----|-------------|
| `inventory://schema/entities` | Schema de toutes les entites |
| `inventory://roles` | Hierarchie des roles et permissions |
| `inventory://stats` | Statistiques globales |

## Roles & Permissions

```
ROLE_ADMIN > ROLE_GESTIONNAIRE > ROLE_VIEWER > ROLE_USER
```

- **VIEWER** : lecture, recherche, commentaires
- **GESTIONNAIRE** : ecriture (CRUD, slots, links, clone)
- **ADMIN** : gestion profils (via API REST uniquement)

## Troubleshooting

| Erreur | Cause | Solution |
|--------|-------|----------|
| `401 Unauthorized` | Credentials invalides | Verifier X-Profile-Id et X-Profile-Password |
| `Permission denied: ROLE_GESTIONNAIRE required` | Role insuffisant | Utiliser un profil avec le bon role |
| `Rate limited` | Trop de tentatives echouees | Attendre 1 minute |
| `Tool not found` | Tool non enregistre | Verifier que le cache est a jour (`cache:clear`) |
| `Error while executing tool` | Erreur interne | Verifier les logs et les parametres |