JeromeProg/mcp-zefix-ide-server

MCP Zefix-IDE Server

Serveur MCP (Model Context Protocol) pour l'accès unifié aux données publiques d'entreprises suisses via :

• Zefix (SPARQL) - Registre du commerce
• Registre IDE (WebService) - Office fédéral de la statistique

Déploiement rapide

Option 1: Script automatisé

curl -fsSL https://raw.githubusercontent.com/JeromeProg/mcp-zefix-ide-server/main/deploy.sh | bash

Option 2: Portainer (recommandé)

1. Portainer > Stacks > Add stack
2. Repository tab:
   • URL: https://github.com/JeromeProg/mcp-zefix-ide-server
   • Compose path: portainer/stack.yml
3. Deploy the stack

Option 3: Docker Compose direct

services:
  mcp-server:
    image: ghcr.io/jeromeprog/mcp-zefix-ide-server:latest
    ports:
      - "8080:8080"
    environment:
      - LOG_LEVEL=INFO
      - CACHE_TTL=3600

Images Docker disponibles

Registry: ghcr.io/jeromeprog/mcp-zefix-ide-server

API et fonctionnalités

Tools MCP disponibles

Recherche d'entreprises

• search_company_by_name - Recherche par nom
• search_company_by_uid - Recherche par numéro IDE
• search_company_by_commercial_id - Recherche par numéro RC
• search_companies_advanced - Recherche multicritères

Validation

• validate_uid - Validation numéro IDE
• validate_vat_number - Validation numéro TVA
• check_company_status - Vérification statut

Données détaillées

• get_company_details - Informations complètes
• get_company_addresses - Adresses de l'entreprise
• get_legal_form - Forme juridique
• get_noga_classification - Classification économique

Recherches spécialisées

• search_by_location - Recherche géographique
• search_by_noga - Par secteur d'activité
• bulk_company_lookup - Recherche en lot (max 10)

Limitations du service IDE public

Le serveur utilise l'API publique IDE qui impose des restrictions :

• Rate limiting: 25-30 requêtes/minute
• Accès lecture seule: Pas de création/modification
• Données publiques uniquement
• Recherches limitées à 30 résultats

Pour contourner ces limitations, le serveur fusionne automatiquement avec les données Zefix SPARQL.

Configuration

Variables d'environnement

Endpoints configurables

Monitoring

Health checks

curl http://localhost:8080/health

Métriques Prometheus

curl http://localhost:8080/metrics

Status du rate limiting

Via MCP tool get_ide_rate_limit_status

Développement

Build local

git clone https://github.com/JeromeProg/mcp-zefix-ide-server.git
cd mcp-zefix-ide-server
docker build -t mcp-zefix-ide:dev .

Tests

./deploy.sh development latest local
curl http://localhost:8081/health

Structure du projet

├── src/                     # Code source Python
│   ├── server.py           # Serveur MCP principal
│   ├── zefix_client.py     # Client SPARQL
│   ├── ide_client.py       # Client WebService IDE
│   └── utils/              # Rate limiter, cache, logs
├── portainer/              # Configuration Portainer
├── .github/workflows/      # CI/CD automatique
└── docs/                   # Documentation

Déploiement production

Recommandations

• Replicas: 2-3 instances minimum
• Resources: 1 CPU, 512MB RAM par instance
• Cache: TTL de 2 heures en production
• Monitoring: Activer Prometheus + alertes

Mise à jour

# Nouvelle version
git tag v1.0.1
git push origin v1.0.1

# Dans Portainer
MCP_VERSION: v1.0.1  # Puis Update stack

Backup

• Code: Automatiquement versionné sur GitHub
• Images: Stockées dans GitHub Container Registry
• Configuration: Via Portainer exports

Support et maintenance

Maintenance automatique

• Dependabot: Updates de sécurité automatiques
• GitHub Actions: Build et tests automatiques
• Security scanning: Scan hebdomadaire des vulnérabilités

Support

• Issues: GitHub Issues
• Documentation:
• Releases: GitHub Releases

Monitoring de production

GitHub Actions effectue des health checks automatiques et notifie en cas de problème.

Licence

MIT License - Voir pour les détails.

Liens utiles

• Documentation Zefix SPARQL
• API IDE OFS
• Standard eCH-0108
• Model Context Protocol