Skip to main content
Glama
snorbik-mcp-hybrid-starter-kit

snorbik-mcp-hybrid-starter-kit

Official
by snorbik-ai

snorbik-mcp-hybrid-starter-kit

SNORBIK MCP Hybrid Starter Kit

Python Protocol Architecture License Tests Status

Starter Kit Architecture MCP Hybride Tri-Canal
Gabarit de démarrage Python combinant 3 modes d'accès pour vos outils IA :
1. Canal STDIO pour les clients MCP (Cursor, VS Code, Claude Code).
2. Canal CLI pour vos scripts terminal et pipelines CI/CD.
3. Canal SDK In-Process pour vos applications Python en mémoire sans surcoût IPC.


1. Carte d'Identité & Spécifications

Propriété

Description

Composant

snorbik-mcp-hybrid-starter-kit

Licence

MIT Open-Source (usage commercial et personnel libre)

Spécification MCP

JSON-RPC 2.0 (Spécification officielle 2025-11-25)

Environnement

Python 3.10+ (Windows, macOS, Linux)

Clients Supportés & Testés

Cursor, VS Code, Claude Desktop, Claude Code CLI

Patron de Conception

Clean Architecture Tri-Canal (Core / Domain / Application / Adapters)


Related MCP server: faraztools-mcp

🎯 À Quoi Sert ce Squelette ? La Recette 5 Minutes avec votre IA

Par défaut, une IA de code (Cursor, Claude Code, Copilot) est enfermée dans votre éditeur : elle ne peut pas interroger vos bases de données, lire vos fichiers métier ni exécuter vos scripts d'entreprise.

Ce Starter Kit est le « châssis » prêt à l'emploi qui donne des super-pouvoirs réels à votre IA.
Au lieu d'écrire 500 lignes de plomberie protocolaire JSON-RPC, donnez simplement ce squelette à votre agent IA et demandez-lui d'y brancher votre logique métier :

3 Exemples Concrets d'Outils que vous pouvez fabriquer en 5 minutes :

Ce que vous voulez créer

Le prompt exact à donner à votre Agent IA dans ce dépôt

🔍 Connecter votre base de données

« En t'appuyant sur l'exemple de template_ping de ce Starter Kit, crée un outil MCP search_customer qui interroge ma base SQLite clients et retourne les résultats en JSON. Crée le use-case et le schéma Pydantic. »

📄 Analyser des documents ou rapports

« Ajoute un outil extract_doc_summary dans ce squelette qui lit les fichiers d'un dossier cible, extrait les métadonnées et retourne une synthèse structurée. »

⚡ Automatiser vos actions DevOps

« Ajoute un outil check_docker_health qui interroge l'API Docker locale et remonte les conteneurs arrêtés ou en erreur. »

Comment ça marche ? (La Recette en 3 Étapes)

  1. Clonez ce dépôt sur votre machine.

  2. Donnez la consigne à votre agent IA (exemples ci-dessus) : il génère le cas d'usage dans core/application/ et le déclare dans canal_mcp/mcp_server.py.

  3. Lancez l'installateur : python install.py --client cursor ➔ Votre outil sur-mesure est instantanément opérationnel dans votre IDE !


2. Guide d'Installation Multi-Clients

Option A : Install with your AI Coding Agent (Recommandée)

Si vous travaillez avec un agent de code (Cursor Agent, Claude Code, VS Code Copilot), copiez-collez simplement ce prompt dans votre chat IA :

Tu es mon ingénieur d'intégration. Configure le serveur MCP depuis ce dépôt :
1. Identifie le client MCP réellement actif dans notre session (Cursor, VS Code, Claude Code ou Claude Desktop).
2. Lis les instructions du README et sélectionne l'argument approprié pour l'installation (--client cursor, --client vscode, --client claude ou --client all).
3. Lance `python install.py --client <client_choisi>` et vérifie le code retour d'exécution.
4. Si nécessaire, rappelle-moi de recharger la fenêtre de mon client (Developer: Reload Window).
5. Vérifie que le serveur répond correctement en appelant l'outil `template_ping` et valide la réception de la réponse `pong`.
6. Rapporte-moi clairement le résultat du test et signale toute erreur éventuelle sans la masquer.

Option B : Installation Automatisée (Terminal)

Exécutez le script universel install.py à la racine du dépôt :

# Installation automatique tous clients détectés :
python install.py

# Ou installation ciblée selon votre environnement :
python install.py --client cursor   # Configure ~/.cursor/mcp.json (clé "mcpServers")
python install.py --client vscode   # Configure .vscode/mcp.json (clé officielle "servers")
python install.py --client claude   # Configure Claude Desktop et enregistre via claude mcp add
python install.py --client all      # Auto-détection et configuration universelle

Sécurité et Résilience de l'Installateur :

  • Vérification stricte de pip install : toute anomalie de dépendances bloque l'installation avec code d'erreur explicite.

  • Protection anti-corruption JSON : si un fichier de configuration existant est syntaxiquement invalide, l'installateur génère une sauvegarde .corrupted.bak et refuse formellement d'écraser le fichier.

  • Préservation intégrale : tous vos serveurs MCP et configurations existantes sont conservés sans perte.


Option C : Installation Manuelle Développeur

# 1. Cloner et installer en mode éditable
git clone https://github.com/snorbik-ai/snorbik-mcp-hybrid-starter-kit.git
cd snorbik-mcp-hybrid-starter-kit
pip install -e .

# 2. Exécuter la suite de tests unitaires
pytest

3. Configuration Manuelle des Clients

Si vous préférez déclarer manuellement ce serveur, voici les blocs de configuration prêts à copier :

Pour Cursor (~/.cursor/mcp.json) & Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "snorbik-mcp-hybrid-starter-kit": {
      "command": "python",
      "args": ["template_mcp_hybride/canal_mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "type": "stdio"
    }
  }
}

Pour VS Code (.vscode/mcp.json - Spécification Officielle VS Code) :

{
  "servers": {
    "snorbik-mcp-hybrid-starter-kit": {
      "command": "python",
      "args": ["template_mcp_hybride/canal_mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

4. Outils Déclarés (tools) & Test de Fonctionnement

Ce serveur expose deux outils déterministes validés selon le schéma Pydantic :

Outil (tool)

Rôle & Usage

Paramètres

Réponse Attendue

template_ping

Test de réactivité et santé du serveur. À appeler immédiatement après l'installation pour vérifier la liaison.

aucun

DTO ToolResponseDto avec status: "SUCCESS" et payload.reply: "pong".

template_execute_action

Démonstration de validation et sérialisation. Permet de transmettre une charge utile typée.

message (str, requis)

DTO enrichi avec horodatage Unix certifié et écho validé.

Cycle de vie MCP vérifié :

  1. Handshake initialize (négociation du protocole 2024-11-05 / 2025-11-25).

  2. Réception silencieuse des notifications JSON-RPC (notifications/initialized).

  3. Invocation d'outil tools/call (template_ping → réponse pong).


5. Performances Mesurées en Conditions Réelles

Mesuré sur banc d'essai local (environnement Windows 11 / Python 3.12) :

  • Installation des dépendances (python install.py) : ~2 à 3 secondes (avec cache pip local).

  • Suite de tests unitaires (pytest) : 3/3 tests passés à 100% en 1,53 s.

  • Latence à froid (1er appel) : ~390 à 400 ms (initialisation du runtime Python, chargement des modules Pydantic et handshake initialize).

  • Latence à chaud Canal STDIO (IPC) : 0,19 ms (moyenne sur 50 requêtes JSON-RPC consécutives sur stdin/stdout du même processus actif).

  • Latence à chaud Canal SDK (In-Process) : 0,008 ms (moyenne sur 1000 exécutions directes en mémoire sans IPC).


6. Utilisation Multi-Canal

Canal 1 : Via votre IDE IA (STDIO)

Demandez à votre assistant :

  • « Envoie un template_ping au serveur starter kit pour vérifier son statut. »

  • « Exécute template_execute_action avec le message "Hello MCP". »

Canal 2 : En Ligne de Commande (CLI)

python -m template_mcp_hybride.canal_sdk_cli.cli ping
python -m template_mcp_hybride.canal_sdk_cli.cli execute --message "Test CLI"

Canal 3 : En Bibliothèque Python (SDK In-Process)

from template_mcp_hybride.canal_sdk_cli.sdk import HybridMcpStarterSDK

sdk = HybridMcpStarterSDK()
reponse = sdk.ping()
print(reponse)  # {'reply': 'pong', 'timestamp': ...}

🛡️ Licence & Contribution

  • Éditeur : SNORBIK AI © 2026.

  • Licence : Open-Source sous licence MIT (libre pour projets commerciaux et open-source).

  • Spécification : Conforme aux standards officiels MCP (Model Context Protocol).

  • Statut Public : Certifié conforme V25 (Zéro référence interne, benchmarks locaux validés).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI clients to call small utility tools like echo and Markdown-to-PDF conversion, running locally over stdio.
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables clients to submit typed System One decisions against the Laya model and check service readiness over stdio or HTTP SSE, with the same configuration, validation, and API-key protection as the REST API.
      2
      1
      Apache 2.0