Vue d'ensemble

Le Serveur MCP Mapfolio est un serveur Model Context Protocol (MCP) qui permet aux assistants IA et autres clients compatibles MCP d'interagir avec les données et opérations de Mapfolio. Il fournit un accès programmatique aux entreprises, projets, utilisateurs, profils LinkedIn et fonctions administratives.

Qu'est-ce que MCP ?

Model Context Protocol (MCP) est un protocole ouvert qui permet aux assistants IA d'accéder de manière sécurisée à des sources de données et outils externes. Les serveurs MCP exposent des capacités via une interface standardisée, permettant aux assistants IA de :

Interroger et récupérer des données
Effectuer des opérations
Accéder à des ressources
S'intégrer avec des systèmes externes

Fonctionnalités

Le Serveur MCP Mapfolio fournit une fonctionnalité complète :

Données d'Entreprises

Rechercher des entreprises avec des filtres avancés
Obtenir les détails d'entreprise par ID
Récupérer des entreprises par canton et lettre initiale
Obtenir des entreprises aléatoires pour échantillonnage
Accéder aux statistiques de visites d'entreprises

Gestion de Projets

Créer et gérer des projets
Lister et filtrer les projets utilisateur
Mettre à jour les détails de projet
Supprimer des projets
Ajouter et retirer des entreprises des projets

Profils Utilisateur

Obtenir les informations de profil utilisateur
Mettre à jour les paramètres de profil
Lister les projets utilisateur
Gérer les clés API

Intégration LinkedIn

Obtenir les données de profil LinkedIn
Rechercher des profils LinkedIn
Accéder aux informations de connexion
Voir l'historique des versions de profil
Obtenir les données d'entreprise LinkedIn

Opérations Administratives

Lister tous les utilisateurs (admin uniquement)
Créer de nouveaux utilisateurs (admin uniquement)
Gérer les clés API (admin uniquement)
Accéder aux statistiques du tableau de bord admin

Statistiques

Obtenir des statistiques agrégées d'entreprises
Voir les comptages au niveau du canton
Accéder aux comptages basés sur les lettres
Obtenir des statistiques de combinaisons de deux lettres

Installation

Prérequis

Node.js >= 20.0.0
npm >= 10.0.0
Accès à l'instance Supabase Mapfolio

Configuration

Installer les dépendances :

cd mcp-server
npm install

Configurer les variables d'environnement :

cp .env.example .env

Éditez .env et configurez :

# URL de l'API Mapfolio (par défaut : https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Type de transport : 'stdio' (par défaut) ou 'http' pour accès distant
MCP_TRANSPORT=stdio

# Port HTTP (utilisé uniquement lorsque MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Optionnel : Authentification par défaut (peut être fournie via contexte MCP ou en-têtes HTTP)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here

Construire le serveur :

npm run build

Utilisation

Exécution du Serveur

Développement Local (transport stdio)

Le serveur MCP utilise le transport stdio par défaut (protocole MCP standard) :

npm start

Pour le développement avec rechargement automatique :

npm run dev

Transport HTTP (pour accès distant)

Pour exécuter le serveur avec transport HTTP pour tests locaux :

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

Cela démarre un serveur HTTP sur le port 3001 qui accepte les requêtes JSON-RPC 2.0 via HTTP POST.

Déploiement Vercel (Accès Distant)

Le serveur MCP est automatiquement disponible via HTTP lorsqu'il est déployé sur Vercel :

Endpoint : https://your-app.vercel.app/api/mcp
Protocole : JSON-RPC 2.0 via HTTP POST
Authentification : Via en-tête X-API-Key ou en-tête Authorization: Bearer <token>

Exemple de requête :

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Configuration du Client MCP

Claude Desktop

Déploiement local :

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

Configurez via les paramètres MCP :

Commande : node
Args : ["/path/to/mapfolio/mcp-server/dist/index.js"]
Variables d'environnement :
- MAPFOLIO_API_URL : https://mapfolio.app
- MAPFOLIO_API_KEY : Votre clé API (optionnel)

Authentification

Le serveur prend en charge deux méthodes d'authentification :

Authentification par Clé API

Les clés API sont préfixées avec mapf_ et peuvent :

Être définies via la variable d'environnement MAPFOLIO_API_KEY
Être transmises par requête via le paramètre apiKey dans les appels d'outils

Authentification par Token JWT

Les tokens JWT Supabase peuvent :

Être définis via la variable d'environnement MAPFOLIO_JWT_TOKEN
Être transmis par requête via le paramètre jwtToken dans les appels d'outils

Priorité d'Authentification

Transport HTTP : Les en-têtes (X-API-Key ou Authorization) ont la priorité
Identifiants par requête (apiKey ou jwtToken dans les arguments d'outils)
Variables d'environnement (MAPFOLIO_API_KEY ou MAPFOLIO_JWT_TOKEN)

Authentification Transport HTTP

Lors de l'utilisation du endpoint HTTP (/api/mcp), l'authentification est fournie via les en-têtes HTTP :

Clé API : X-API-Key: mapf_your_api_key
Token JWT : Authorization: Bearer your_jwt_token

Outils Disponibles

Le serveur fournit 30+ outils dans 6 catégories :

Outils Entreprises

search_companies - Rechercher avec filtres
get_company - Obtenir entreprise par ID
get_companies_by_canton_letter - Obtenir par canton et lettre
get_random_companies - Obtenir échantillons aléatoires
get_company_visits - Obtenir statistiques de visites

Outils Projets

create_project - Créer nouveau projet
list_projects - Lister projets utilisateur
get_project - Obtenir détails du projet
update_project - Mettre à jour projet
delete_project - Supprimer projet
add_companies_to_project - Ajouter entreprises
remove_companies_from_project - Retirer entreprises

Outils Utilisateur

get_user_profile - Obtenir profil
update_user_profile - Mettre à jour profil
get_user_projects - Lister projets
get_user_api_keys - Lister clés API

Outils LinkedIn

get_linkedin_profile - Obtenir profil
search_linkedin_profiles - Rechercher profils
get_linkedin_connections - Obtenir connexions
get_linkedin_profile_versions - Obtenir historique des versions
get_linkedin_companies - Obtenir données d'entreprise

Outils Admin (Admin Uniquement)

list_all_users - Lister tous les utilisateurs
create_user - Créer utilisateur
get_user_details - Obtenir détails utilisateur
list_api_keys - Lister toutes les clés API
create_api_key - Créer clé API
revoke_api_key - Révoquer clé API
get_admin_stats - Obtenir statistiques admin

Outils Statistiques

get_company_stats - Obtenir statistiques agrégées
get_canton_counts - Obtenir comptages de cantons
get_letter_counts - Obtenir comptages de lettres
get_two_letter_counts - Obtenir comptages de deux lettres

Ressources

Le serveur fournit un accès basé sur les ressources :

mapfolio://company/{id} - Données d'entreprise
mapfolio://project/{id} - Données de projet
mapfolio://user/{id} - Profil utilisateur
mapfolio://linkedin-profile/{id} - Profil LinkedIn

Les ressources peuvent inclure l'authentification via paramètres de requête :

mapfolio://company/{id}?apiKey=mapf_...
mapfolio://company/{id}?jwtToken=...

Exemple d'Utilisation

Rechercher des Entreprises

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Créer un Projet

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Obtenir les Détails d'Entreprise

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Gestion des Erreurs

Tous les outils renvoient des erreurs dans un format cohérent :

{
  "error": "Message d'erreur"
}

Scénarios d'erreur courants :

401 Non Autorisé : Authentification invalide ou manquante
403 Interdit : Permissions insuffisantes
404 Non Trouvé : Ressource introuvable
500 Erreur Interne du Serveur : Erreur côté serveur

Architecture API Uniquement

Le serveur MCP utilise des requêtes HTTP vers mapfolio.app au lieu d'un accès direct à la base de données. Cela signifie :

✅ Aucune credential Supabase nécessaire - Fonctionne avec juste l'URL de l'API et la clé API
✅ Déploiement Vercel facile - Déployer en tant que fonction serverless
✅ Sécurisé - Toutes les requêtes passent par l'API Mapfolio avec authentification
✅ Évolutif - Bénéficie de la limitation de débit et du cache de l'API Mapfolio

Actuellement Disponible via API

✅ Recherche et récupération d'entreprises
✅ Statistiques d'entreprises (comptages de cantons, comptages de lettres)
✅ Entreprises aléatoires
✅ Visites d'entreprises

À Venir (Nécessite des Endpoints API)

⏳ Gestion de projets (créer, lister, mettre à jour, supprimer)
⏳ Gestion de profils utilisateur
⏳ Accès aux profils LinkedIn
⏳ Opérations administratives

Ces fonctionnalités renverront des messages d'erreur utiles jusqu'à ce que les endpoints API soient créés.

Considérations de Sécurité

Clés API : Stocker de manière sécurisée, ne jamais commiter dans le contrôle de version
Tokens JWT : Les tokens expirent, gérer le rafraîchissement de manière appropriée
Limitation de Débit API : Respecte les limites de débit de l'API Mapfolio
HTTPS Uniquement : Toujours utiliser HTTPS pour les requêtes API
Opérations Admin : Nécessitent une authentification admin explicite (lorsque les endpoints sont disponibles)

Développement

Vérification de Type

npm run type-check

Construction

npm run build

Mode Développement

npm run dev

Documentation

Pour la documentation complète, consultez le README du Serveur MCP.

Support

Pour les problèmes ou questions :

GitHub Issues : [dépôt mapfolio]
Email : support@mapfolio.app

Licence

MIT