cosmo-mcp

MCP Server Node.js 20 + TypeScript exposant ERPNext (cosmo_erp) à Hermes Agent.

Architecture

Telegram
   |
   v
Hermes Agent (NousResearch)
   |  MCP Protocol (stdio)
   v
cosmo-mcp  <-- ce serveur
   |  POST /api/method/cosmo_erp.cosmo_erp.api.main.<function>
   v
ERPNext (cosmo_erp)

Prérequis

• Node.js >= 20.0.0
• Clés API ERPNext (API Key + API Secret)
• ERPNext avec l'app cosmo_erp installée

Installation

cd cosmo-mcp
npm install
npm run build

Configuration

cp .env.example .env
# Editer .env avec vos valeurs

Variables requises :

| Variable | Description | |----------|-------------| | ERPNEXT_URL | URL de votre instance ERPNext (ex: https://erp.ma-boutique.com) | | ERPNEXT_API_KEY | API Key du compte ERPNext | | ERPNEXT_API_SECRET | API Secret du compte ERPNext |

Démarrage

# Production
npm run build && npm start

# Développement
npm run dev

Intégration Hermes (config.yaml)

mcp_servers:
  - name: cosmo-erp
    command: node
    args:
      - /chemin/vers/cosmo-mcp/dist/index.js
    env:
      ERPNEXT_URL: "https://erp.ma-boutique.com"
      ERPNEXT_API_KEY: "your_api_key"
      ERPNEXT_API_SECRET: "your_api_secret"

Docker

docker build -t cosmo-mcp .
docker run --env-file .env cosmo-mcp

Tools disponibles (25)

Stock (8)

| Tool | Description | |------|-------------| | get_item_stock | Stock actuel d'un produit spécifique | | get_low_stock_items | Produits sous le seuil de réapprovisionnement | | get_expiring_items | Produits expirant dans les N prochains jours | | search_items | Recherche dans le catalogue par nom/marque/code | | receive_stock | Enregistrer une réception fournisseur | | adjust_stock | Correction d'inventaire (casse, vol) | | create_item | Créer un nouveau produit dans le catalogue | | update_item_price | Mettre à jour le prix de vente |

Ventes (5)

| Tool | Description | |------|-------------| | create_sale | Créer une vente / facture client | | get_daily_sales | Résumé des ventes du jour | | get_sales_period | Analyse sur une période personnalisée | | get_invoice | Détail d'une facture par numéro | | cancel_invoice | Annuler une facture (action irréversible) |

CRM / Clients (4)

| Tool | Description | |------|-------------| | find_or_create_customer | Trouver ou créer un client | | get_customer_profile | Profil complet avec historique achats | | get_inactive_customers | Clients sans achat depuis X jours | | get_top_customers | Meilleures clientes par CA |

Fournisseurs (3)

| Tool | Description | |------|-------------| | create_supplier_order | Créer une commande fournisseur | | get_pending_orders | Commandes en attente de livraison | | get_suppliers | Liste des fournisseurs actifs |

Vision / OCR (3)

| Tool | Description | |------|-------------| | identify_product_from_image | Identifier un produit depuis données image extraites par Hermes | | process_supplier_invoice_image | Traiter une facture fournisseur depuis données OCR | | create_item_from_image | Créer une fiche produit depuis données image |

Rapports / Dashboard (3)

| Tool | Description | |------|-------------| | get_dashboard | Résumé complet de la boutique (briefing matinal) | | get_revenue_trend | Evolution du CA sur N jours | | get_category_performance | Performances par catégorie cosmétique |

Test rapide

# Vérifier que le serveur démarre
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  ERPNEXT_URL=https://test.example.com \
  ERPNEXT_API_KEY=test \
  ERPNEXT_API_SECRET=test \
  node dist/index.js

Le serveur doit répondre avec la liste des 25 tools.