Inventory/docs/mcp

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 :

{
  "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 :

{
  "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