# Serveur MCP OPS Hubpost CRM

Serveur MCP (Model Context Protocol) personnalisé pour HubSpot CRM — segmentation ICP, scoring, détection de doublons, Data Quality Score et automatisation lifecycle stage.

## Structure

```
hubspot-mcp-server/
├── server.py           # Serveur MCP FastMCP (39 outils)
├── requirements.txt    # Dépendances Python
├── .env.example        # Template de configuration
└── .gitignore
```

## Rôle

Expose la logique métier propre au workspace (Fit Score ICP, détection doublons, calcul DQS) que le MCP officiel HubSpot ne fournit pas nativement.

## Installation

```bash
cd hubspot-mcp-server
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Éditer .env avec ton Private App Access Token HubSpot
```

## Démarrage

```bash
python server.py
# Tester avec MCP Inspector : npx @modelcontextprotocol/inspector python server.py
```

## Outils exposés (39)

### Audit & Qualité
- `audit_contacts_completeness` — calcule le taux de complétude
- `compute_dqs` — calcul du Data Quality Score (DQS)
- `detect_duplicate_contacts` — détection de doublons (name+company, email)
- `detect_duplicate_companies` — détection de doublons companies

### Scoring & Segmentation
- `calculate_fit_score` — applique la grille ICP Fit Score
- `calculate_company_fit_score` — scoring firmographique companies
- `calculate_company_engagement_score` — scoring engagement companies
- `calculate_company_combined_score` — score combiné (fit + engagement + techno)
- `calculate_company_techno_score` — scoring technographique
- `sync_segmentation_properties` — synchronise les propriétés ICP
- `sync_company_segmentation` — segmentation companies

### Lifecycle & Pipeline
- `update_lifecyclestage` — promotion automatique de lifecyclestage
- `update_company_lifecyclestage` — lifecyclestage companies
- `detect_founder_signals` — détection des signaux forts founder-led
- `detect_company_signals` — détection signaux companies

### Enrichissement & Complétion
- `standardize_contact` — standardisation des contacts
- `standardize_company_properties` — standardisation companies
- `complete_missing_fields` — complétion champs critiques
- `complete_company_fields` — complétion companies

### Reporting
- `generate_weekly_report` — rapport hebdomadaire complet
- `generate_company_report` — rapport companies
- `generate_revops_report` — rapport RevOps

### Administration
- `create_custom_properties` — création des propriétés custom
- `fix_lifecycle_stages` — correction lifecycle stages
- `dedupe_contacts` — fusion de doublons contacts
- `dedupe_companies` — fusion de doublons companies
- `bulk_update_properties` — mise à jour en masse

## Propriétés Custom

### Contacts (6)
| Propriété | Type | Description |
|-----------|------|-------------|
| `fit_score` | number | Score ICP 0-50 |
| `icp_tier` | dropdown | Tier 1 / Tier 2 / Tier 3 / Not ICP |
| `founder_signal_type` | string | Type de signal founder détecté |
| `last_signal_date` | date | Date du dernier signal |
| `duplicate_flag` | boolean | Contact potentiellement dupliqué |
| `tier1_alert_sent_date` | date | Date d'alerte Tier 1 |

### Companies (11)
| Propriété | Type | Description |
|-----------|------|-------------|
| `icp_tier_company` | dropdown | Tier 1 / Tier 2 / Tier 3 |
| `company_fit_score` | number | Score fit 0-60 |
| `company_engagement_score` | number | Score engagement 0-40 |
| `company_combined_score` | number | Score combiné 0-118 |
| `company_techno_score` | number | Score techno 0-18 |
| `last_company_sync_date` | date | Dernière synchronisation |
| `company_tier1_alert_sent_date` | date | Date d'alerte Tier 1 |
| `recent_funding_amount` | number | Financement récent |
| `num_locations` | number | Nombre de localisations |
| `existing_hubspot_customer` | boolean | Client HubSpot existant |
| `ecommerce_stack` | string | Stack e-commerce |

## Bug Fixes (2026-07-16)

39 bugs identifiés et corrigés le 2026-07-16 :
- **BUG-01** : `hs_` prefix sur propriétés custom → renommé en `recent_funding_amount`
- **BUG-02** : Options vides sur boolean → ajout options true/false
- **BUG-03** : Lifecyclestage regression → forward-only enforcement
- **BUG-04** : HubSpot search limit 200 → pagination automatique
- **BUG-05** : Contact standardization modifie champs protégés → exclusion email/firstname/lastname/company/lifecyclestage/hs_lead_status
- **BUG-06** : Company name auto-write → flagged to review queue
- **BUG-07** : Phone field auto-write → jamais écrit automatiquement
- **BUG-08** : Duplicate merge sans validation → human confirmation required
- **BUG-09** : Irreversible actions sans confirmation → dry_run par défaut
- **BUG-10** : Dropdown options mismatch → labels exacts server.py
- **BUG-11** : DQS formula incorrect → (completeness×0.40) + ((1-doublons)×0.20) + (segmentation×0.20) + (pipeline_activity×0.20)
- **BUG-12** : ICP weight auto-apply → human validation required
- **BUG-13** : Breeze Intelligence API trigger → détection gaps uniquement
- **BUG-14** : Config paths wrong → ~/nanobot-workspace/ par défaut
- **BUG-15** : Sales Hub Starter constraint → custom icp_tier_company dropdown

## Configuration

Créer un fichier `.env` à la racine avec :

```
HUBSPOT_ACCESS_TOKEN=pat-xxxxxxxxxxxx
```

Ou utiliser `~/nanobot_secrets.env` (chmod 600) sourcé via `.bashrc`.

## License

Private — usage interne uniquement.