boondmanager-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Silamir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# BoondManager MCP Server
+
+[![CI](https://github.com/fauguste/boondmanager-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/fauguste/boondmanager-mcp-server/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/boondmanager-mcp-server.svg)](https://www.npmjs.com/package/boondmanager-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Serveur MCP (Model Context Protocol) pour l'API BoondManager, permettant à Claude (Desktop, Cowork, Code) de rechercher, consulter, créer et modifier des enregistrements dans votre instance BoondManager.
+
+## 🎯 Domaines couverts
+
+| Domaine | Outils | Description |
+|---------|--------|-------------|
+| **Candidats** | search, get, create, update, delete + 4 onglets | Gestion du vivier de candidats |
+| **Ressources** | search, get, create, update, delete + 6 onglets | Gestion des collaborateurs/consultants |
+| **Contacts** | search, get, create, update, delete + 3 onglets | Contacts clients et partenaires |
+| **Sociétés** | search, get, create, update, delete + 3 onglets | Entreprises clientes et prospects |
+| **Opportunités** | search, get, create, update, delete + 3 onglets | Pipeline commercial |
+| **Actions** | search, get, create, delete | Suivi d'activité (appels, emails, RDV) |
+| **Feuilles de temps** | search, get, resource timesheets | Consultation des temps saisis |
+| **Projets** | search, get, create, update, delete + 4 onglets | Gestion des missions / projets |
+| **Factures** | search, get, create, update, delete | Facturation client |
+| **Bons de commande** | search, get, create, update, delete | Bons de commande |
+| **Livraisons / CRA** | search, get | Comptes rendus d'activité |
+| **Absences** | search, get, create, update, delete | Congés, RTT, maladie |
+| **Notes de frais** | search, get, create, update, delete | Remboursement de frais |
+| **Produits** | search, get, create, update, delete | Catalogue de produits/prestations |
+| **Positionnements** | search, get, create, delete | Placement candidats/ressources |
+| **Paiements** | search, get | Suivi des règlements |
+| **Avantages** | search, get | Tickets restaurant, mutuelle, primes... |
+| **Application** | dictionnaire, utilisateur courant | Dictionnaires de référence et profil |
+
+**Total : 84 outils**
+
+### Détail des onglets par entité
+
+| Entité | Onglets disponibles |
+|--------|-------------------|
+| Candidats | information, technical, actions, documents |
+| Ressources | information, technical, financial, actions, contracts, documents |
+| Contacts | information, actions, documents |
+| Sociétés | information, actions, documents |
+| Opportunités | information, actions, documents |
+| Projets | information, planning, actions, documents |
+
+## 📋 Prérequis
+
+- Node.js >= 18
+- Un compte BoondManager avec accès API activé
+- L'option "Allow API Rest calls using BasicAuth authentication" activée dans la configuration BoondManager (si BasicAuth)
+
+## 🚀 Installation
+
+```bash
+git clone <votre-repo>/boondmanager-mcp-server
+cd boondmanager-mcp-server
+npm install
+npm run build
+```
+
+## ⚙️ Configuration
+
+### Variables d'environnement
+
+**Option 1 : BasicAuth (recommandé pour démarrer)**
+```bash
+export BOOND_USER="votre_login"
+export BOOND_PASSWORD="votre_mot_de_passe"
+```
+
+**Option 2 : Token API (JWT)**
+```bash
+export BOOND_API_TOKEN="votre_token_jwt"
+```
+
+**Option 3 : URL personnalisée (si instance dédiée)**
+```bash
+export BOOND_BASE_URL="https://votre-instance.boondmanager.com/api"
+```
+
+### Configuration Claude Desktop / Cowork
+
+Ajoutez dans votre fichier de configuration Claude :
+
+**macOS** : `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows** : `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "boondmanager": {
+      "command": "node",
+      "args": ["/chemin/absolu/vers/boondmanager-mcp-server/dist/index.js"],
+      "env": {
+        "BOOND_USER": "votre_login",
+        "BOOND_PASSWORD": "votre_mot_de_passe"
+      }
+    }
+  }
+}
+```
+
+## 💬 Exemples d'utilisation
+
+Une fois configuré, vous pouvez demander à Claude :
+
+- *"Recherche les candidats avec des compétences en React à Paris"*
+- *"Montre-moi les détails de la ressource #12345"*
+- *"Crée un nouveau contact Jean Dupont chez Acme Corp"*
+- *"Liste toutes les opportunités en cours"*
+- *"Quelles sont les actions récentes sur le candidat #789 ?"*
+- *"Mets à jour l'email du contact #456"*
+- *"Affiche les feuilles de temps de la ressource #100 pour mars 2025"*
+- *"Crée un projet Mission Alpha pour la société #42"*
+- *"Recherche les factures en attente de paiement"*
+- *"Liste les absences prévues ce mois-ci"*
+- *"Affiche les notes de frais de la ressource #200"*
+- *"Quels sont les bons de commande du projet #55 ?"*
+- *"Récupère le dictionnaire des types d'actions"*
+- *"Positionne le candidat #10 sur l'opportunité #20"*
+- *"Affiche le planning du projet #33"*
+
+## 🏗️ Architecture
+
+```
+boondmanager-mcp-server/
+├── src/
+│   ├── index.ts              # Point d'entrée MCP (stdio)
+│   ├── constants.ts          # Configuration et constantes
+│   ├── types.ts              # Types TypeScript (JSON:API)
+│   ├── services/
+│   │   └── boond-client.ts   # Client HTTP API BoondManager
+│   ├── schemas/
+│   │   └── index.ts          # Schémas Zod (validation)
+│   └── tools/
+│       ├── index.ts          # Export barrel
+│       ├── crud-factory.ts   # Factory générique CRUD (DRY)
+│       ├── candidates.ts     # Outils candidats (CRUD + onglets)
+│       ├── resources.ts      # Outils ressources (CRUD + onglets)
+│       ├── contacts.ts       # Outils contacts (CRUD + onglets)
+│       ├── companies.ts      # Outils sociétés (CRUD + onglets)
+│       ├── opportunities.ts  # Outils opportunités (CRUD + onglets)
+│       ├── actions.ts        # Outils actions
+│       ├── timesheets.ts     # Outils feuilles de temps
+│       ├── projects.ts       # Outils projets (CRUD + onglets)
+│       ├── invoices.ts       # Outils factures
+│       ├── orders.ts         # Outils bons de commande
+│       ├── deliveries.ts     # Outils livraisons / CRA
+│       ├── absences.ts       # Outils absences
+│       ├── expenses.ts       # Outils notes de frais
+│       ├── products.ts       # Outils produits
+│       ├── positionings.ts   # Outils positionnements
+│       ├── payments.ts       # Outils paiements
+│       ├── advantages.ts     # Outils avantages
+│       └── application.ts    # Outils application (dictionnaires)
+├── dist/                     # Build JavaScript
+├── .github/                  # CI/CD, templates, Dependabot
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── eslint.config.js
+└── README.md
+```
+
+## 🔒 Sécurité
+
+- Les credentials ne transitent jamais via le réseau MCP — ils sont configurés en variables d'environnement locales
+- Le serveur tourne en local (stdio), pas de port réseau exposé
+- Compatible avec les exigences ISO 27001
+- L'API BoondManager est hébergée en France et conforme RGPD
+
+## 🔧 Développement
+
+```bash
+# Mode watch pour le développement
+npm run dev
+
+# Build
+npm run build
+
+# Lancer le serveur
+npm start
+
+# Tests
+npm test
+npm run test:coverage
+
+# Lint
+npm run lint
+npm run typecheck
+```
+
+## 📚 Ressources
+
+- [Documentation API BoondManager](https://doc.boondmanager.com/api-externe/)
+- [Collection Postman BoondManager](https://www.postman.com/boondmanager)
+- [Spécification MCP](https://modelcontextprotocol.io/)
+- [pyboondmanager (référence Python)](https://github.com/tominardi/pyboondmanager)
+
+## 📄 Licence
+
+MIT - Silamir

package/dist/constants.d.ts

@@ -0,0 +1,32 @@
+export declare const DEFAULT_BASE_URL = "https://ui.boondmanager.com/api";
+export declare const CHARACTER_LIMIT = 50000;
+export declare const DEFAULT_PAGE_SIZE = 20;
+export declare const MAX_PAGE_SIZE = 100;
+export declare const API_PATHS: {
+    readonly candidates: "/candidates";
+    readonly resources: "/resources";
+    readonly contacts: "/contacts";
+    readonly companies: "/companies";
+    readonly opportunities: "/opportunities";
+    readonly actions: "/actions";
+    readonly projects: "/projects";
+    readonly invoices: "/invoices";
+    readonly orders: "/orders";
+    readonly deliveries: "/deliveries";
+    readonly absences: "/absences";
+    readonly expenses: "/expenses";
+    readonly products: "/products";
+    readonly positionings: "/positionings";
+    readonly payments: "/payments";
+    readonly advantages: "/advantages";
+    readonly application: "/application";
+};
+export declare const ENTITY_TABS: {
+    readonly candidates: readonly ["information", "technical", "actions", "documents"];
+    readonly resources: readonly ["information", "technical", "financial", "actions", "contracts", "documents"];
+    readonly contacts: readonly ["information", "actions", "documents"];
+    readonly companies: readonly ["information", "actions", "documents"];
+    readonly opportunities: readonly ["information", "actions", "documents"];
+    readonly projects: readonly ["information", "planning", "actions", "documents"];
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,gBAAgB,oCAAoC,CAAC;AAClE,eAAO,MAAM,eAAe,QAAQ,CAAC;AACrC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,aAAa,MAAM,CAAC;AAGjC,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;CAkBZ,CAAC;AAGX,eAAO,MAAM,WAAW;;;;;;;CAOd,CAAC"}

package/dist/constants.js

@@ -0,0 +1,35 @@
+// BoondManager API constants
+export const DEFAULT_BASE_URL = "https://ui.boondmanager.com/api";
+export const CHARACTER_LIMIT = 50000;
+export const DEFAULT_PAGE_SIZE = 20;
+export const MAX_PAGE_SIZE = 100;
+// API paths
+export const API_PATHS = {
+    candidates: "/candidates",
+    resources: "/resources",
+    contacts: "/contacts",
+    companies: "/companies",
+    opportunities: "/opportunities",
+    actions: "/actions",
+    projects: "/projects",
+    invoices: "/invoices",
+    orders: "/orders",
+    deliveries: "/deliveries",
+    absences: "/absences",
+    expenses: "/expenses",
+    products: "/products",
+    positionings: "/positionings",
+    payments: "/payments",
+    advantages: "/advantages",
+    application: "/application",
+};
+// Tab names available on entities
+export const ENTITY_TABS = {
+    candidates: ["information", "technical", "actions", "documents"],
+    resources: ["information", "technical", "financial", "actions", "contracts", "documents"],
+    contacts: ["information", "actions", "documents"],
+    companies: ["information", "actions", "documents"],
+    opportunities: ["information", "actions", "documents"],
+    projects: ["information", "planning", "actions", "documents"],
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,MAAM,CAAC,MAAM,gBAAgB,GAAG,iCAAiC,CAAC;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC,YAAY;AACZ,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,UAAU,EAAE,aAAa;IACzB,SAAS,EAAE,YAAY;IACvB,QAAQ,EAAE,WAAW;IACrB,SAAS,EAAE,YAAY;IACvB,aAAa,EAAE,gBAAgB;IAC/B,OAAO,EAAE,UAAU;IACnB,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,WAAW;IACrB,MAAM,EAAE,SAAS;IACjB,UAAU,EAAE,aAAa;IACzB,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,WAAW;IACrB,YAAY,EAAE,eAAe;IAC7B,QAAQ,EAAE,WAAW;IACrB,UAAU,EAAE,aAAa;IACzB,WAAW,EAAE,cAAc;CACnB,CAAC;AAEX,kCAAkC;AAClC,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,UAAU,EAAE,CAAC,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,CAAU;IACzE,SAAS,EAAE,CAAC,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAU;IAClG,QAAQ,EAAE,CAAC,aAAa,EAAE,SAAS,EAAE,WAAW,CAAU;IAC1D,SAAS,EAAE,CAAC,aAAa,EAAE,SAAS,EAAE,WAAW,CAAU;IAC3D,aAAa,EAAE,CAAC,aAAa,EAAE,SAAS,EAAE,WAAW,CAAU;IAC/D,QAAQ,EAAE,CAAC,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,CAAU;CAC9D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { initClient } from "./services/boond-client.js";
+import { registerCandidateTools, registerResourceTools, registerContactTools, registerCompanyTools, registerOpportunityTools, registerActionTools, registerTimesheetTools, registerProjectTools, registerInvoiceTools, registerOrderTools, registerDeliveryTools, registerAbsenceTools, registerExpenseTools, registerProductTools, registerPositioningTools, registerPaymentTools, registerAdvantageTools, registerApplicationTools, } from "./tools/index.js";
+const server = new McpServer({
+    name: "boondmanager-mcp-server",
+    version: "1.0.0",
+});
+// Register all domain tools
+registerCandidateTools(server);
+registerResourceTools(server);
+registerContactTools(server);
+registerCompanyTools(server);
+registerOpportunityTools(server);
+registerActionTools(server);
+registerTimesheetTools(server);
+registerProjectTools(server);
+registerInvoiceTools(server);
+registerOrderTools(server);
+registerDeliveryTools(server);
+registerAbsenceTools(server);
+registerExpenseTools(server);
+registerProductTools(server);
+registerPositioningTools(server);
+registerPaymentTools(server);
+registerAdvantageTools(server);
+registerApplicationTools(server);
+// Initialize and run
+async function main() {
+    try {
+        initClient();
+    }
+    catch (error) {
+        console.error("⚠️  Configuration warning:", error.message);
+        console.error("The server will start but API calls will fail without proper credentials.");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("🚀 BoondManager MCP Server running (stdio transport)");
+    console.error("📦 Domains: candidates, resources, contacts, companies, opportunities, actions, timesheets, projects, invoices, orders, deliveries, absences, expenses, products, positionings, payments, advantages, application");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,yBAAyB;IAC/B,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,4BAA4B;AAC5B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,wBAAwB,CAAC,MAAM,CAAC,CAAC;AAEjC,qBAAqB;AACrB,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,UAAU,EAAE,CAAC;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAG,KAAe,CAAC,OAAO,CAAC,CAAC;QACtE,OAAO,CAAC,KAAK,CAAC,2EAA2E,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;IACtE,OAAO,CAAC,KAAK,CAAC,mNAAmN,CAAC,CAAC;AACrO,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}